Detailed Description

The Aspose.Words.Loading namespace provides classes and enumerations that allow to specify additional options when loading documents.

Classes
class	ChmLoadOptions
	Allows to specify additional options when loading CHM document into a Document object. To learn more, visit the Specify Load Options documentation article. More...

class	DocumentLoadingArgs
	An argument passed into Notify(). To learn more, visit the Specify Load Options documentation article. More...

class	HtmlLoadOptions
	Allows to specify additional options when loading HTML document into a Document object. To learn more, visit the Specify Load Options documentation article. More...

interface	IDocumentLoadingCallback
	Implement this interface if you want to have your own custom method called during loading a document. More...

interface	IResourceLoadingCallback
	Implement this interface if you want to control how Aspose.Words loads external resource when importing a document and inserting images using DocumentBuilder. More...

class	LanguagePreferences
	Allows to set up language preferences. To learn more, visit the Specify Load Options documentation article. More...

class	LoadOptions
	Allows to specify additional options (such as password or base URI) when loading a document into a Document object. To learn more, visit the Specify Load Options documentation article. More...

class	PdfLoadOptions
	Allows to specify additional options when loading Pdf document into a Document object. To learn more, visit the Specify Load Options documentation article. More...

class	ResourceLoadingArgs
	Provides data for the ResourceLoading() method. More...

class	RtfLoadOptions
	Allows to specify additional options when loading Rtf document into a Document object. To learn more, visit the Specify Load Options documentation article. More...

class	TxtLoadOptions
	Allows to specify additional options when loading Text document into a Document object. To learn more, visit the Specify Load Options documentation article. More...

Enumerations
enum class	BlockImportMode
	Specifies how properties of block-level elements are imported from HTML-based documents. More...

enum class	DocumentDirection
	Allows to specify the direction to flow the text in a document. More...

enum class	EditingLanguage
	Specifies the editing language. More...

enum class	HtmlControlType
	Type of document nodes that represent <input> and <select> elements imported from HTML. More...

enum class	ResourceLoadingAction
	Specifies the mode of resource loading. To learn more, visit the Specify Load Options documentation article. More...

enum class	ResourceType
	Type of loaded resource. More...

enum class	TxtLeadingSpacesOptions
	Specifies available options for leading space handling during import from Text file. More...

enum class	TxtTrailingSpacesOptions
	Specifies available options for trailing spaces handling during import from Text file. More...

Enumeration Type Documentation

◆ BlockImportMode

enum class Aspose::Words::Loading::BlockImportMode

strong

Specifies how properties of block-level elements are imported from HTML-based documents.

Enumerator

Merge

Properties of parent blocks are merged and stored on child elements (i.e. paragraphs or tables).

Properties of parent blocks are merged as follows: margins are added together; borders of higher-level blocks are discarded and only the most inner-level borders are preserved. As a result, when this mode is specified, some formatting of blocks from the original document will be lost.

On the other hand, since all merged block-level properties are stored on document nodes, all formating in the resulting document will be available for modification.

Preserve

Properties of parent blocks are imported to a special logical structure and are stored separately from document nodes.

Only margins and borders of 'body', 'div', and 'blockquote' HTML elements are imported. Properties of each HTML element are stored individually.

This mode allows to better preserve borders and margins seen in the HTML document and get better conversion results. The downside is that the resulting document gets harder to modify, since borders and margins stored in the logical structure are not available for editing.

This mode mimics MS Word's behavior regarding import of block properties.

◆ DocumentDirection

enum class Aspose::Words::Loading::DocumentDirection

strong

Allows to specify the direction to flow the text in a document.

Enumerator
LeftToRight	Left to right direction.
RightToLeft	Right to left direction.
Auto	Auto-detect direction.

◆ EditingLanguage

enum class Aspose::Words::Loading::EditingLanguage

strong

Specifies the editing language.

Examples

Shows how to apply language preferences when loading a document.

auto loadOptions = MakeObject<LoadOptions>();
loadOptions->get_LanguagePreferences()->AddEditingLanguage(EditingLanguage::Japanese);
 
auto doc = MakeObject<Document>(MyDir + u"No default editing language.docx", loadOptions);
 
int localeIdFarEast = doc->get_Styles()->get_DefaultFont()->get_LocaleIdFarEast();
std::cout << (localeIdFarEast == (int)EditingLanguage::Japanese
                  ? String(u"The document either has no any FarEast language set in defaults or it was set to Japanese originally.")
                  : String(u"The document default FarEast language was set to another than Japanese language originally, so it is not overridden."))
          << std::endl;

Enumerator
Afrikaans
Albanian
Alsatian
Amharic
ArabicAlgeria
ArabicBahrain
ArabicEgypt
ArabicIraq
ArabicJordan
ArabicKuwait
ArabicLebanon
ArabicLibya
ArabicMorocco
ArabicOman
ArabicQatar
ArabicSaudiArabia
ArabicSyria
ArabicTunisia
ArabicUAE
ArabicYemen
Armenian
Assamese
AzerbaijaniCyrillic
AzerbaijaniLatin
BanglaBangladesh
BanglaIndia
Bashkir
Basque
Belarusian
BosnianCyrillic
BosnianLatin
Breton
Bulgarian
Burmese
Catalan
CentralKurdishIraq
Cherokee
ChineseHongKong
ChineseMacao
ChinesePRC
ChineseSingapore
ChineseTaiwan
Corsican
CroatianBozniaAndHerzegovina
Croatian
Czech
Danish
Divehi
DutchBelgium
DutchNetherlands
Edo
EnglishAustralia
EnglishBelize
EnglishCanada
EnglishCaribbean
EnglishHongKong
EnglishIndia
EnglishIndonesia
EnglishIreland
EnglishJamaica
EnglishMalaysia
EnglishNewZealand
EnglishPhilippines
EnglishSingapore
EnglishSouthAfrica
EnglishTrinidadAndTobago
EnglishUK
EnglishUS
EnglishZimbabwe
Estonian
Faeroese
Filipino
Finnish
FrenchBelgium
FrenchCanada
FrenchFrance
FrenchLuxembourg
FrenchMonaco
FrenchSwitzerland
Frisian
FulahLatinSenegal
FulahNigeria
Galician
Georgian
GermanAustria
GermanGermany
GermanLiechtenstein
GermanLuxembourg
GermanSwitzerland
Greek
Greenlandic
Guarani
Gujarati
Hausa
Hawaiian
Hebrew
Hindi
Hungarian
Icelandic
Igbo
InariSamiFinland
Indonesian
InuktitutLatin
InuktitutSyllabics
Irish
IsiXhosa
IsiZulu
ItalianItaly
ItalianSwitzerland
Japanese
Kannada
Kanuri
Kashmiri
KashmiriArabic
Kazakh
Khmer
Kiche
Kinyarwanda
Kiswahili
Konkani
Korean
Kyrgyz
Lao
Latin
Latvian
Lithuanian
LowerSorbian
LuleSamiNorway
LuleSamiSweden
Luxembougish
Macedonian
MalayMalaysia
MalayBruneiDarussalam
Malayalam
Maltese
Manipuri
Maori
MapudungunChile
Marathi
Mohawk
MongolianCyrillic
MongolianMongolian
Nepali
NorthernSamiFinland
NorthernSamiNorway
NorthernSamiSweden
NorwegianBokmal
NorwegianNynorsk
Oriya
Oromo
Papiamentu
Pashto
Persian
Polish
PortugueseBrazil
PortuguesePortugal
PunjabiIndia
PunjabiPakistan
QuechuaBolivia
QuechuaEcuador
QuechuaPeru
Romanian
Romansh
Russian
Sakha
Sanskrit
ScottishGaelic
SerbianCyrillicBosniaAndHerzegovina
SerbianCyrillicSerbiaAndMontenegro
SerbianLatinBosniaAndHerzegovina
SerbianLatinSerbiaAndMontenegro
Sindhi
SindhiDevanagaric
Sinhalese
Slovak
Slovenian
Somali
Sorbian
SpanishArgentina
SpanishBolivia
SpanishChile
SpanishColombia
SpanishCostaRica
SpanishDominicanRepublic
SpanishEcuador
SpanishElSalvador
SpanishGuatemala
SpanishHonduras
SpanishMexico
SpanishNicaragua
SpanishPanama
SpanishParaguay
SpanishPeru
SpanishPuertoRico
SpanishSpainModernSort
SpanishSpainTraditionalSort
SpanishUruguay
SpanishVenezuela
Sutu
SwedishFinland
SwedishSweden
Syriac
Tajik
Tamazight
TamazightLatin
Tamil
Tatar
Telugu
Thai
TibetanButan
TibetanChina
TigrignaEritrea
TigrignaEthiopia
Tsonga
Tswana
Turkish
Turkmen
Ukrainian
Urdu
UzbekCyrillic
UzbekLatin
Venda
Vietnamese
Welsh
Yi
Yiddish
Yoruba

◆ HtmlControlType

enum class Aspose::Words::Loading::HtmlControlType

strong

Type of document nodes that represent <input> and <select> elements imported from HTML.

Enumerator
FormField
StructuredDocumentTag

◆ ResourceLoadingAction

enum class Aspose::Words::Loading::ResourceLoadingAction

strong

Specifies the mode of resource loading. To learn more, visit the Specify Load Options documentation article.

Examples

Shows how to customize the process of loading external resources into a document.

void ResourceLoadingCallback()
{
    auto doc = MakeObject<Document>();
    doc->set_ResourceLoadingCallback(MakeObject<ExDocumentBase::ImageNameHandler>());
 
    auto builder = MakeObject<DocumentBuilder>(doc);
 
    // Images usually are inserted using a URI, or a byte array.
    // Every instance of a resource load will call our callback's ResourceLoading method.
    builder->InsertImage(u"Google logo");
    builder->InsertImage(u"Aspose logo");
    builder->InsertImage(u"Watermark");
 
    ASSERT_EQ(3, doc->GetChildNodes(NodeType::Shape, true)->get_Count());
 
    doc->Save(ArtifactsDir + u"DocumentBase.ResourceLoadingCallback.docx");
}
 
class ImageNameHandler : public IResourceLoadingCallback
{
public:
    ResourceLoadingAction ResourceLoading(SharedPtr<ResourceLoadingArgs> args) override
    {
        // If this callback encounters one of the image shorthands while loading an image,
        // it will apply unique logic for each defined shorthand instead of treating it as a URI.
        if (args->get_ResourceType() == ResourceType::Image)
        {
            String imageUri = args->get_OriginalUri();
            if (imageUri == u"Google logo")
            {
                {
                    auto webClient = MakeObject<System::Net::WebClient>();
                    args->SetData(webClient->DownloadData(u"http://www.google.com/images/logos/ps_logo2.png"));
                }
                return ResourceLoadingAction::UserProvided;
            }
            else if (imageUri == u"Aspose logo")
            {
                args->SetData(System::IO::File::ReadAllBytes(ImageDir + u"Logo.jpg"));
                return ResourceLoadingAction::UserProvided;
            }
            else if (imageUri == u"Watermark")
            {
                args->SetData(System::IO::File::ReadAllBytes(ImageDir + u"Transparent background logo.png"));
                return ResourceLoadingAction::UserProvided;
            }
        }
        return ResourceLoadingAction::Default;
    }
};

Enumerator
Default	Aspose.Words will load this resource as usual.
Skip	Aspose.Words will skip loading of this resource. Only link without data will be stored for an image, CSS style sheet will be ignored for HTML format.
UserProvided	Aspose.Words will use byte array provided by user in SetData() as resource data.

◆ ResourceType

enum class Aspose::Words::Loading::ResourceType

strong

Type of loaded resource.

Examples

Shows how to customize the process of loading external resources into a document.

void ResourceLoadingCallback()
{
    auto doc = MakeObject<Document>();
    doc->set_ResourceLoadingCallback(MakeObject<ExDocumentBase::ImageNameHandler>());
 
    auto builder = MakeObject<DocumentBuilder>(doc);
 
    // Images usually are inserted using a URI, or a byte array.
    // Every instance of a resource load will call our callback's ResourceLoading method.
    builder->InsertImage(u"Google logo");
    builder->InsertImage(u"Aspose logo");
    builder->InsertImage(u"Watermark");
 
    ASSERT_EQ(3, doc->GetChildNodes(NodeType::Shape, true)->get_Count());
 
    doc->Save(ArtifactsDir + u"DocumentBase.ResourceLoadingCallback.docx");
}
 
class ImageNameHandler : public IResourceLoadingCallback
{
public:
    ResourceLoadingAction ResourceLoading(SharedPtr<ResourceLoadingArgs> args) override
    {
        // If this callback encounters one of the image shorthands while loading an image,
        // it will apply unique logic for each defined shorthand instead of treating it as a URI.
        if (args->get_ResourceType() == ResourceType::Image)
        {
            String imageUri = args->get_OriginalUri();
            if (imageUri == u"Google logo")
            {
                {
                    auto webClient = MakeObject<System::Net::WebClient>();
                    args->SetData(webClient->DownloadData(u"http://www.google.com/images/logos/ps_logo2.png"));
                }
                return ResourceLoadingAction::UserProvided;
            }
            else if (imageUri == u"Aspose logo")
            {
                args->SetData(System::IO::File::ReadAllBytes(ImageDir + u"Logo.jpg"));
                return ResourceLoadingAction::UserProvided;
            }
            else if (imageUri == u"Watermark")
            {
                args->SetData(System::IO::File::ReadAllBytes(ImageDir + u"Transparent background logo.png"));
                return ResourceLoadingAction::UserProvided;
            }
        }
        return ResourceLoadingAction::Default;
    }
};

Enumerator
Image	Image.
CssStyleSheet	Css style sheet.
Document	Document.

◆ TxtLeadingSpacesOptions

enum class Aspose::Words::Loading::TxtLeadingSpacesOptions

strong

Specifies available options for leading space handling during import from Text file.

Examples

Shows how to trim whitespace when loading plaintext documents.

String textDoc = String(u"      Line 1 \n") + u"    Line 2   \n" + u" Line 3       ";
 
// Create a "TxtLoadOptions" object, which we can pass to a document's constructor
// to modify how we load a plaintext document.
auto loadOptions = MakeObject<TxtLoadOptions>();
 
// Set the "LeadingSpacesOptions" property to "TxtLeadingSpacesOptions.Preserve"
// to preserve all whitespace characters at the start of every line.
// Set the "LeadingSpacesOptions" property to "TxtLeadingSpacesOptions.ConvertToIndent"
// to remove all whitespace characters from the start of every line,
// and then apply a left first line indent to the paragraph to simulate the effect of the whitespaces.
// Set the "LeadingSpacesOptions" property to "TxtLeadingSpacesOptions.Trim"
// to remove all whitespace characters from every line's start.
loadOptions->set_LeadingSpacesOptions(txtLeadingSpacesOptions);
 
// Set the "TrailingSpacesOptions" property to "TxtTrailingSpacesOptions.Preserve"
// to preserve all whitespace characters at the end of every line.
// Set the "TrailingSpacesOptions" property to "TxtTrailingSpacesOptions.Trim" to
// remove all whitespace characters from the end of every line.
loadOptions->set_TrailingSpacesOptions(txtTrailingSpacesOptions);
 
auto doc = MakeObject<Document>(MakeObject<System::IO::MemoryStream>(System::Text::Encoding::get_UTF8()->GetBytes(textDoc)), loadOptions);
SharedPtr<ParagraphCollection> paragraphs = doc->get_FirstSection()->get_Body()->get_Paragraphs();
 
switch (txtLeadingSpacesOptions)
{
case TxtLeadingSpacesOptions::ConvertToIndent:
    ASPOSE_ASSERT_EQ(37.8, paragraphs->idx_get(0)->get_ParagraphFormat()->get_FirstLineIndent());
    ASPOSE_ASSERT_EQ(25.2, paragraphs->idx_get(1)->get_ParagraphFormat()->get_FirstLineIndent());
    ASPOSE_ASSERT_EQ(6.3, paragraphs->idx_get(2)->get_ParagraphFormat()->get_FirstLineIndent());
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().StartsWith(u"Line 1"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().StartsWith(u"Line 2"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().StartsWith(u"Line 3"));
    break;
 
case TxtLeadingSpacesOptions::Preserve:
    ASSERT_TRUE(paragraphs->LINQ_All([](SharedPtr<Node> p)
                                     { return (System::DynamicCast<Paragraph>(p))->get_ParagraphFormat()->get_FirstLineIndent() == 0.0; }));
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().StartsWith(u"      Line 1"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().StartsWith(u"    Line 2"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().StartsWith(u" Line 3"));
    break;
 
case TxtLeadingSpacesOptions::Trim:
    ASSERT_TRUE(paragraphs->LINQ_All([](SharedPtr<Node> p)
                                     { return (System::DynamicCast<Paragraph>(p))->get_ParagraphFormat()->get_FirstLineIndent() == 0.0; }));
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().StartsWith(u"Line 1"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().StartsWith(u"Line 2"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().StartsWith(u"Line 3"));
    break;
}
 
switch (txtTrailingSpacesOptions)
{
case TxtTrailingSpacesOptions::Preserve:
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().EndsWith(u"Line 1 \r"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().EndsWith(u"Line 2   \r"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().EndsWith(u"Line 3       \f"));
    break;
 
case TxtTrailingSpacesOptions::Trim:
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().EndsWith(u"Line 1\r"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().EndsWith(u"Line 2\r"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().EndsWith(u"Line 3\f"));
    break;
}

Enumerator
ConvertToIndent
Trim
Preserve

◆ TxtTrailingSpacesOptions

enum class Aspose::Words::Loading::TxtTrailingSpacesOptions

strong

Specifies available options for trailing spaces handling during import from Text file.

Examples

Shows how to trim whitespace when loading plaintext documents.

String textDoc = String(u"      Line 1 \n") + u"    Line 2   \n" + u" Line 3       ";
 
// Create a "TxtLoadOptions" object, which we can pass to a document's constructor
// to modify how we load a plaintext document.
auto loadOptions = MakeObject<TxtLoadOptions>();
 
// Set the "LeadingSpacesOptions" property to "TxtLeadingSpacesOptions.Preserve"
// to preserve all whitespace characters at the start of every line.
// Set the "LeadingSpacesOptions" property to "TxtLeadingSpacesOptions.ConvertToIndent"
// to remove all whitespace characters from the start of every line,
// and then apply a left first line indent to the paragraph to simulate the effect of the whitespaces.
// Set the "LeadingSpacesOptions" property to "TxtLeadingSpacesOptions.Trim"
// to remove all whitespace characters from every line's start.
loadOptions->set_LeadingSpacesOptions(txtLeadingSpacesOptions);
 
// Set the "TrailingSpacesOptions" property to "TxtTrailingSpacesOptions.Preserve"
// to preserve all whitespace characters at the end of every line.
// Set the "TrailingSpacesOptions" property to "TxtTrailingSpacesOptions.Trim" to
// remove all whitespace characters from the end of every line.
loadOptions->set_TrailingSpacesOptions(txtTrailingSpacesOptions);
 
auto doc = MakeObject<Document>(MakeObject<System::IO::MemoryStream>(System::Text::Encoding::get_UTF8()->GetBytes(textDoc)), loadOptions);
SharedPtr<ParagraphCollection> paragraphs = doc->get_FirstSection()->get_Body()->get_Paragraphs();
 
switch (txtLeadingSpacesOptions)
{
case TxtLeadingSpacesOptions::ConvertToIndent:
    ASPOSE_ASSERT_EQ(37.8, paragraphs->idx_get(0)->get_ParagraphFormat()->get_FirstLineIndent());
    ASPOSE_ASSERT_EQ(25.2, paragraphs->idx_get(1)->get_ParagraphFormat()->get_FirstLineIndent());
    ASPOSE_ASSERT_EQ(6.3, paragraphs->idx_get(2)->get_ParagraphFormat()->get_FirstLineIndent());
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().StartsWith(u"Line 1"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().StartsWith(u"Line 2"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().StartsWith(u"Line 3"));
    break;
 
case TxtLeadingSpacesOptions::Preserve:
    ASSERT_TRUE(paragraphs->LINQ_All([](SharedPtr<Node> p)
                                     { return (System::DynamicCast<Paragraph>(p))->get_ParagraphFormat()->get_FirstLineIndent() == 0.0; }));
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().StartsWith(u"      Line 1"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().StartsWith(u"    Line 2"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().StartsWith(u" Line 3"));
    break;
 
case TxtLeadingSpacesOptions::Trim:
    ASSERT_TRUE(paragraphs->LINQ_All([](SharedPtr<Node> p)
                                     { return (System::DynamicCast<Paragraph>(p))->get_ParagraphFormat()->get_FirstLineIndent() == 0.0; }));
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().StartsWith(u"Line 1"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().StartsWith(u"Line 2"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().StartsWith(u"Line 3"));
    break;
}
 
switch (txtTrailingSpacesOptions)
{
case TxtTrailingSpacesOptions::Preserve:
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().EndsWith(u"Line 1 \r"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().EndsWith(u"Line 2   \r"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().EndsWith(u"Line 3       \f"));
    break;
 
case TxtTrailingSpacesOptions::Trim:
    ASSERT_TRUE(paragraphs->idx_get(0)->GetText().EndsWith(u"Line 1\r"));
    ASSERT_TRUE(paragraphs->idx_get(1)->GetText().EndsWith(u"Line 2\r"));
    ASSERT_TRUE(paragraphs->idx_get(2)->GetText().EndsWith(u"Line 3\f"));
    break;
}

Enumerator
Trim
Preserve

Detailed Description

Classes

Enumerations

Enumeration Type Documentation

◆ BlockImportMode

◆ DocumentDirection

◆ EditingLanguage

◆ HtmlControlType

◆ ResourceLoadingAction

◆ ResourceType

◆ TxtLeadingSpacesOptions

◆ TxtTrailingSpacesOptions