Labels serialization

Functions

void Labels.Deserialize (string newVal)
 Restores the state of the Labels class from the string. More...
 
bool Labels.LoadFromDbf (bool loadText, bool loadCategory)
 Loads text and position of labels from the attribute table of the parent shapefile. More...
 
bool Labels.LoadFromDbf2 (string xField, string yField, string angleField, string textField, string categoryField, bool loadText, bool loadCategory)
 Loads text and position of labels from the attribute table of the parent shapefile. More...
 
bool Labels.LoadFromXML (string Filename)
 Restores the state of the labels from the specified XML file. More...
 
bool Labels.SaveToDbf (bool saveText, bool saveCategory)
 Saves position and text of the labels to the attribute table (dbf file). More...
 
bool Labels.SaveToDbf2 (string xField, string yField, string angleField, string textField, string categoryField, bool saveText, bool saveCategory)
 Saves positions and text of the labels to the attribute table (dbf file). More...
 
bool Labels.SaveToXML (string Filename)
 Saves the text, positions and visualization options of the labels to the XML file. More...
 
string Labels.Serialize ()
 Saves the state of the labels. More...
 

Properties

tkSavingMode Labels.SavingMode [get, set]
 Gets or sets the method to save and restore the state labels. More...
 

Detailed Description

Here is a list of methods and properties for serialization of labels and their persistence between the runs of application. This module is a part of the documentation of Labels class.

dot_inline_dotgraph_23.png

Graph description

It's possible to serialize different types of information for labels (charts):

  1. The drawing settings, such visualization options, order of drawing, etc. It's desirable to save them in virtually any scenario.

  2. The positions of the labels (charts). It makes sense to save them to avoid the recalculation of the positions on the next loading. It's quite relevant even for middle sized datasets if the more or less complex routine for positioning is used (Shape.Centroid, Shape.InteriorPoint).

  3. The angles rotation, text and categories for labels. This type of information requires serialization less often. The text of labels can be easily restored by applying Labels.Expression. Unless the Label.Text property was set manually. In the same way categories rely on LabelCategory.Expression and will be serialized among the first group of settings, unless Label.Category property was set manually. Finally the rotation of labels which is preserved less often.

The first group of settings is embedded in the larger XML body, either layer or map settings. It can be saved:

For data described in the 2nd and 3rd sections more options are available by Labels.SavingMode property and tkSavingMode enumeration. It can be:

Function Documentation

◆ Deserialize()

void Labels.Deserialize ( string  newVal)

Restores the state of the Labels class from the string.

Parameters
newValA string with serialized state generated by Labels.Serialize() method.

◆ LoadFromDbf()

bool Labels.LoadFromDbf ( bool  loadText,
bool  loadCategory 
)

Loads text and position of labels from the attribute table of the parent shapefile.

Applicable for the instance of the Labels class associated with polyline shapefiles, i.e. obtained by Shapefile.Labels property

Parameters
loadTextA value which indicates whether the text of the labels should be loaded.
loadCategoryA value which indicates whether the mapping between labels and visualization categories should be restored.
Returns
True on successful loading and false otherwise.

◆ LoadFromDbf2()

bool Labels.LoadFromDbf2 ( string  xField,
string  yField,
string  angleField,
string  textField,
string  categoryField,
bool  loadText,
bool  loadCategory 
)

Loads text and position of labels from the attribute table of the parent shapefile.

Parameters
xFieldThe name of field which holds x values.
yFieldThe name of field which holds y values.
angleFieldThe name of field which holds rotation angles.
textFieldThe name of the field which stores text of the labels.
categoryFieldThe name of the field which stores index of visualization category for each label.
loadTextA value which indicates whether the text of the labels should be loaded.
loadCategoryA value which indicates whether the mapping between labels and visualization categories should be restored.
Returns
True on successful loading and false otherwise.

◆ LoadFromXML()

bool Labels.LoadFromXML ( string  Filename)

Restores the state of the labels from the specified XML file.

Parameters
FilenameThe name of the file previously generated by Labels.SaveToXML method.
Returns
True on successful loading and false otherwise.

◆ SaveToDbf()

bool Labels.SaveToDbf ( bool  saveText,
bool  saveCategory 
)

Saves position and text of the labels to the attribute table (dbf file).

Parameters
saveTextA value which indicates whether the text of labels will be saved.
saveCategoryA value which indicates whether the mapping between labels and visualization categories will be saved.
Returns
True on success and false otherwise.

◆ SaveToDbf2()

bool Labels.SaveToDbf2 ( string  xField,
string  yField,
string  angleField,
string  textField,
string  categoryField,
bool  saveText,
bool  saveCategory 
)

Saves positions and text of the labels to the attribute table (dbf file).

This method allows to specify the names of fields to save the data in.

Parameters
xFieldThe name of field to store x coordinate.
yFieldThe name of field to store y coordinate.
angleFieldThe name of field to store angle.
textFieldThe name of field to store text.
categoryFieldThe name of field to store category.
saveTextA value which indicates whether the text of labels will be saved.
saveCategoryA value which indicates whether the mapping between labels and visualization categories will be saved.
Returns
True on success and false otherwise.

◆ SaveToXML()

bool Labels.SaveToXML ( string  Filename)

Saves the text, positions and visualization options of the labels to the XML file.

Parameters
FilenameThe name of the file to save the settings to.
Returns
True on successful saving and false otherwise. Use Labels.get_ErrorMsg() to find out the reason of failure.

◆ Serialize()

string Labels.Serialize ( )

Saves the state of the labels.

Serialized state holds information about visualization options, categories and text expressions.

Optionally it can hold information about position and text of labels (see Labels.SavingMode property). The default values of the properties will not be serialized.

Returns
A string with serialized state. On failure an empty string will be returned.

Properties

◆ SavingMode

tkSavingMode Labels.SavingMode
getset

Gets or sets the method to save and restore the state labels.

See details in tkSavingMode enumeration.