The m17n Library 1.8.4
Loading...
Searching...
No Matches
Typedefs | Enumerations | Functions | Variables
Text Property

Function to handle text properties. More...

Typedefs

typedef MPlist *(* MTextPropSerializeFunc) (void *val)
 Type of serializer functions.
 
typedef void *(* MTextPropDeserializeFunc) (MPlist *plist)
 Type of deserializer functions.
 

Enumerations

enum  MTextPropertyControl {
  MTEXTPROP_FRONT_STICKY = 0x01 ,
  MTEXTPROP_REAR_STICKY = 0x02 ,
  MTEXTPROP_VOLATILE_WEAK = 0x04 ,
  MTEXTPROP_VOLATILE_STRONG = 0x08 ,
  MTEXTPROP_NO_MERGE = 0x10 ,
  MTEXTPROP_CONTROL_MAX = 0x1F
}
 Flag bits to control text property. More...
 

Functions

void * mtext_get_prop (MText *mt, int pos, MSymbol key)
 Get the value of the topmost text property.
 
int mtext_get_prop_values (MText *mt, int pos, MSymbol key, void **values, int num)
 Get multiple values of a text property.
 
int mtext_get_prop_keys (MText *mt, int pos, MSymbol **keys)
 Get a list of text property keys at a position of an M-text.
 
int mtext_put_prop (MText *mt, int from, int to, MSymbol key, void *val)
 
int mtext_put_prop_values (MText *mt, int from, int to, MSymbol key, void **values, int num)
 Set multiple text properties with the same key.
 
int mtext_push_prop (MText *mt, int from, int to, MSymbol key, void *val)
 
int mtext_pop_prop (MText *mt, int from, int to, MSymbol key)
 
int mtext_prop_range (MText *mt, MSymbol key, int pos, int *from, int *to, int deeper)
 Find the range where the value of a text property is the same.
 
MTextPropertymtext_property (MSymbol key, void *val, int control_bits)
 Create a text property.
 
MTextmtext_property_mtext (MTextProperty *prop)
 Return the M-text of a text property.
 
MSymbol mtext_property_key (MTextProperty *prop)
 Return the key of a text property.
 
void * mtext_property_value (MTextProperty *prop)
 Return the value of a text property.
 
int mtext_property_start (MTextProperty *prop)
 Return the start position of a text property.
 
int mtext_property_end (MTextProperty *prop)
 Return the end position of a text property.
 
MTextPropertymtext_get_property (MText *mt, int pos, MSymbol key)
 Get the topmost text property.
 
int mtext_get_properties (MText *mt, int pos, MSymbol key, MTextProperty **props, int num)
 Get multiple text properties.
 
int mtext_attach_property (MText *mt, int from, int to, MTextProperty *prop)
 Attach a text property to an M-text.
 
int mtext_detach_property (MTextProperty *prop)
 Detach a text property from an M-text.
 
int mtext_push_property (MText *mt, int from, int to, MTextProperty *prop)
 Push a text property onto an M-text.
 
MTextmtext_serialize (MText *mt, int from, int to, MPlist *property_list)
 
MTextmtext_deserialize (MText *mt)
 

Variables

MSymbol Mtext_prop_serializer
 Symbol for specifying serializer functions.
 
MSymbol Mtext_prop_deserializer
 Symbol for specifying deserializer functions.
 

Detailed Description

Function to handle text properties.

Each character in an M-text can have properties called text properties. Text properties store various kinds of information attached to parts of an M-text to provide application programs with a unified view of those information. As rich information can be stored in M-texts in the form of text properties, functions in application programs can be simple.

A text property consists of a key and values, where key is a symbol and values are anything that can be cast to (void *) . Unlike other types of properties, a text property can have multiple values. "The text property whose key is K" may be shortened to "K property".

Typedef Documentation

◆ MTextPropSerializeFunc

typedef MPlist *(* MTextPropSerializeFunc) (void *val)

Type of serializer functions.

This is the type of serializer functions. If the key of a symbol property is Mtext_prop_serializer, the value must be of this type.

See Also:
mtext_serialize(), Mtext_prop_serializer

◆ MTextPropDeserializeFunc

typedef void *(* MTextPropDeserializeFunc) (MPlist *plist)

Type of deserializer functions.

This is the type of deserializer functions. If the key of a symbol property is Mtext_prop_deserializer, the value must be of this type.

See Also:
mtext_deserialize(), Mtext_prop_deserializer

Enumeration Type Documentation

◆ MTextPropertyControl

Flag bits to control text property.

The mtext_property() function accepts logical OR of these flag bits as an argument. They control the behaviour of the created text property as described in the documentation of each flag bit.

Enumerator
MTEXTPROP_FRONT_STICKY 

If this flag bit is on, an M-text inserted at the start position or at the middle of the text property inherits the text property.

MTEXTPROP_REAR_STICKY 

If this flag bit is on, an M-text inserted at the end position or at the middle of the text property inherits the text property.

MTEXTPROP_VOLATILE_WEAK 

If this flag bit is on, the text property is removed if a text in its region is modified.

MTEXTPROP_VOLATILE_STRONG 

If this flag bit is on, the text property is removed if a text or the other text property in its region is modified.

MTEXTPROP_NO_MERGE 

If this flag bit is on, the text property is not automatically merged with the others.

MTEXTPROP_CONTROL_MAX 

Function Documentation

◆ mtext_get_prop()

void * mtext_get_prop ( MText mt,
int  pos,
MSymbol  key 
)

Get the value of the topmost text property.

The mtext_get_prop() function searches the character at pos in M-text mt for the text property whose key is key.

Return value:
If a text property is found, mtext_get_prop() returns the value of the property. If the property has multiple values, it returns the topmost one. If no such property is found, it returns NULL without changing the external variable merror_code.

If an error is detected, mtext_get_prop() returns NULL and assigns an error code to the external variable merror_code.

Note
If NULL is returned without an error, there are two possibilities:
  • the character at pos does not have a property whose key is key, or
  • the character does have such a property and its value is NULL.

If you need to distinguish these two cases, use the mtext_get_prop_values() function instead.

Errors:
MERROR_RANGE, MERROR_SYMBOL
See Also:
mtext_get_prop_values(), mtext_put_prop(), mtext_put_prop_values(), mtext_push_prop(), mtext_pop_prop(), mtext_prop_range()

◆ mtext_get_prop_values()

int mtext_get_prop_values ( MText mt,
int  pos,
MSymbol  key,
void **  values,
int  num 
)

Get multiple values of a text property.

The mtext_get_prop_values() function searches the character at pos in M-text mt for the property whose key is key. If such a property is found, its values are stored in the memory area pointed to by values. num limits the maximum number of stored values.

Return value:
If the operation was successful, mtext_get_prop_values() returns the number of actually stored values. If the character at pos does not have a property whose key is key, the return value is 0. If an error is detected, mtext_get_prop_values() returns -1 and assigns an error code to the external variable merror_code.
Errors:
MERROR_RANGE, MERROR_SYMBOL
See Also:
mtext_get_prop(), mtext_put_prop(), mtext_put_prop_values(), mtext_push_prop(), mtext_pop_prop(), mtext_prop_range()

◆ mtext_get_prop_keys()

int mtext_get_prop_keys ( MText mt,
int  pos,
MSymbol **  keys 
)

Get a list of text property keys at a position of an M-text.

The mtext_get_prop_keys() function creates an array whose elements are the keys of text properties found at position pos in M-text mt, and sets *keys to the address of the created array. The user is responsible to free the memory allocated for the array.

Return value:
If the operation was successful, mtext_get_prop_keys() returns the length of the key list. Otherwise it returns -1 and assigns an error code to the external variable merror_code.
Errors:
MERROR_RANGE
See Also:
mtext_get_prop(), mtext_put_prop(), mtext_put_prop_values(), mtext_get_prop_values(), mtext_push_prop(), mtext_pop_prop()

◆ mtext_put_prop()

int mtext_put_prop ( MText mt,
int  from,
int  to,
MSymbol  key,
void *  val 
)
@brief Set a text property.

The mtext_put_prop() function sets a text property to the
characters between @b from (inclusive) and @b to (exclusive) in M-text
@b mt.  @b key and @b val specify the key and the value of the text
property.  With this function,
                     FROM                   TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <------------------ OLD_VAL -------------------->

becomes

                     FROM                   TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <-- OLD_VAL-><-------- VAL -------><-- OLD_VAL-->
@par Return value:
If the operation was successful, mtext_put_prop() returns 0.
Otherwise it returns -1 and assigns an error code to the external
variable #merror_code.   

@par Errors:
@c MERROR_RANGE, @c MERROR_SYMBOL

@par See Also:
mtext_put_prop_values(), mtext_get_prop(),
mtext_get_prop_values(), mtext_push_prop(),
mtext_pop_prop(), mtext_prop_range()   

◆ mtext_put_prop_values()

int mtext_put_prop_values ( MText mt,
int  from,
int  to,
MSymbol  key,
void **  values,
int  num 
)

Set multiple text properties with the same key.

The mtext_put_prop_values() function sets a text property to the characters between from (inclusive) and to (exclusive) in M-text mt. key and values specify the key and the values of the text property. num specifies the number of property values to be set.

Return value:
If the operation was successful, mtext_put_prop_values() returns 0. Otherwise it returns -1 and assigns an error code to the external variable merror_code.
Errors:
MERROR_RANGE, MERROR_SYMBOL
See Also:
mtext_put_prop(), mtext_get_prop(), mtext_get_prop_values(), mtext_push_prop(), mtext_pop_prop(), mtext_prop_range()

◆ mtext_push_prop()

int mtext_push_prop ( MText mt,
int  from,
int  to,
MSymbol  key,
void *  val 
)
@brief Push a text property.

The mtext_push_prop() function pushes a text property whose key
is @b key and value is @b val to the characters between @b from
(inclusive) and @b to (exclusive) in M-text @b mt.  With this
function,
                    FROM                    TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <------------------ OLD_VAL -------------------->
becomes
                    FROM                    TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <------------------- OLD_VAL ------------------->
PROP  :               <-------- VAL ------->
@par Return value:
If the operation was successful, mtext_push_prop() returns 0.
Otherwise it returns -1 and assigns an error code to the external
variable #merror_code.   

@par Errors:
@c MERROR_RANGE, @c MERROR_SYMBOL

@par See Also:
mtext_put_prop(), mtext_put_prop_values(),
mtext_get_prop(), mtext_get_prop_values(),
mtext_pop_prop(), mtext_prop_range()   

◆ mtext_pop_prop()

int mtext_pop_prop ( MText mt,
int  from,
int  to,
MSymbol  key 
)
@brief Pop a text property.

The mtext_pop_prop() function removes the topmost text property
whose key is @b key from the characters between @b from (inclusive)
and and @b to (exclusive) in @b mt.

This function does nothing if characters in the region have no
such text property. With this function,
                    FROM                    TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <------------------ OLD_VAL -------------------->
becomes
                    FROM                    TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <--OLD_VAL-->|                     |<--OLD_VAL-->|
@par Return value:
If the operation was successful, mtext_pop_prop() return 0.
Otherwise it returns -1 and assigns an error code to the external
variable #merror_code.   

@par Errors:
@c MERROR_RANGE, @c MERROR_SYMBOL

@par See Also:
mtext_put_prop(), mtext_put_prop_values(),
mtext_get_prop(), mtext_get_prop_values(),
mtext_push_prop(), mtext_prop_range()   

◆ mtext_prop_range()

int mtext_prop_range ( MText mt,
MSymbol  key,
int  pos,
int *  from,
int *  to,
int  deeper 
)

Find the range where the value of a text property is the same.

The mtext_prop_range() function investigates the extent where all characters have the same value for a text property. It first finds the value of the property specified by key of the character at pos in M-text mt. Then it checks if adjacent characters have the same value for the property key. The beginning and the end of the found range are stored to the variable pointed to by from and to. The character position stored in from is inclusive but that in to is exclusive; this fashion is compatible with the range specification in the mtext_put_prop() function, etc.

If deeper is not 0, not only the topmost but also all the stacked properties whose key is key are compared.

If from is NULL, the beginning of range is not searched for. If to is NULL, the end of range is not searched for.

Return value:

If the operation was successful, mtext_prop_range() returns the number of values the property key has at pos. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

Errors:
MERROR_RANGE, MERROR_SYMBOL
See Also:
mtext_put_prop(), mtext_put_prop_values(), mtext_get_prop(), mtext_get_prop_values(), mtext_pop_prop(), mtext_push_prop()

◆ mtext_property()

MTextProperty * mtext_property ( MSymbol  key,
void *  val,
int  control_bits 
)

Create a text property.

The mtext_property() function returns a newly allocated text property whose key is key and value is val. The created text property is not attached to any M-text, i.e. it is detached.

control_bits must be 0 or logical OR of enum MTextPropertyControl.

◆ mtext_property_mtext()

MText * mtext_property_mtext ( MTextProperty prop)

Return the M-text of a text property.

The mtext_property_mtext() function returns the M-text to which text property prop is attached. If prop is currently detached, NULL is returned.

◆ mtext_property_key()

MSymbol mtext_property_key ( MTextProperty prop)

Return the key of a text property.

The mtext_property_key() function returns the key (symbol) of text property prop.

◆ mtext_property_value()

void * mtext_property_value ( MTextProperty prop)

Return the value of a text property.

The mtext_property_value() function returns the value of text property prop.

◆ mtext_property_start()

int mtext_property_start ( MTextProperty prop)

Return the start position of a text property.

The mtext_property_start() function returns the start position of text property prop. The start position is a character position of an M-text where prop begins. If prop is detached, it returns -1.

◆ mtext_property_end()

int mtext_property_end ( MTextProperty prop)

Return the end position of a text property.

The mtext_property_end() function returns the end position of text property prop. The end position is a character position of an M-text where prop ends. If prop is detached, it returns -1.

◆ mtext_get_property()

MTextProperty * mtext_get_property ( MText mt,
int  pos,
MSymbol  key 
)

Get the topmost text property.

The mtext_get_property() function searches the character at position pos in M-text mt for a text property whose key is key.

Return value:
If a text property is found, mtext_get_property() returns it. If there are multiple text properties, it returns the topmost one. If no such property is found, it returns NULL without changing the external variable merror_code.

If an error is detected, mtext_get_property() returns NULL and assigns an error code to the external variable merror_code.

◆ mtext_get_properties()

int mtext_get_properties ( MText mt,
int  pos,
MSymbol  key,
MTextProperty **  props,
int  num 
)

Get multiple text properties.

The mtext_get_properties() function searches the character at pos in M-text mt for properties whose key is key. If such properties are found, they are stored in the memory area pointed to by props. num limits the maximum number of stored properties.

Return value:
If the operation was successful, mtext_get_properties() returns the number of actually stored properties. If the character at pos does not have a property whose key is key, the return value is 0. If an error is detected, mtext_get_properties() returns -1 and assigns an error code to the external variable merror_code.

◆ mtext_attach_property()

int mtext_attach_property ( MText mt,
int  from,
int  to,
MTextProperty prop 
)

Attach a text property to an M-text.

The mtext_attach_property() function attaches text property prop to the range between from and to in M-text mt. If prop is already attached to an M-text, it is detached before attached to mt.

Return value:
If the operation was successful, mtext_attach_property() returns 0. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

◆ mtext_detach_property()

int mtext_detach_property ( MTextProperty prop)

Detach a text property from an M-text.

The mtext_detach_property() function makes text property prop detached.

Return value:
This function always returns 0.

◆ mtext_push_property()

int mtext_push_property ( MText mt,
int  from,
int  to,
MTextProperty prop 
)

Push a text property onto an M-text.

The mtext_push_property() function pushes text property prop to the characters between from (inclusive) and to (exclusive) in M-text mt.

Return value:
If the operation was successful, mtext_push_property() returns 0. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

◆ mtext_serialize()

MText * mtext_serialize ( MText mt,
int  from,
int  to,
MPlist property_list 
)
@brief Serialize text properties in an M-text.

The mtext_serialize() function serializes the text between @b from
and @b to in M-text @b mt.  The serialized result is an M-text in a
form of XML.  @b property_list limits the text properties to be
serialized. Only those text properties whose key 

@li appears as the value of an element in @b property_list, and
@li has the symbol property #Mtext_prop_serializer

are serialized as a "property" element in the resulting XML
representation.

The DTD of the generated XML is as follows:
<!DOCTYPE mtext [
  <!ELEMENT mtext (property*,body+)>
  <!ELEMENT property EMPTY>
  <!ELEMENT body (#PCDATA)>
  <!ATTLIST property key CDATA #REQUIRED>
  <!ATTLIST property value CDATA #REQUIRED>
  <!ATTLIST property from CDATA #REQUIRED>
  <!ATTLIST property to CDATA #REQUIRED>
  <!ATTLIST property control CDATA #REQUIRED>
 ]>
This function depends on the libxml2 library.  If the m17n library
is configured without libxml2, this function always fails.

@par Return value:
If the operation was successful, mtext_serialize() returns an
M-text in the form of XML.  Otherwise it returns @c NULL and assigns an
error code to the external variable #merror_code.

@par See Also:
mtext_deserialize(), #Mtext_prop_serializer   

◆ mtext_deserialize()

MText * mtext_deserialize ( MText mt)
@brief Deserialize text properties in an M-text.

The mtext_deserialize() function deserializes M-text @b mt.  @b mt
must be an XML having the following DTD.
<!DOCTYPE mtext [
  <!ELEMENT mtext (property*,body+)>
  <!ELEMENT property EMPTY>
  <!ELEMENT body (#PCDATA)>
  <!ATTLIST property key CDATA #REQUIRED>
  <!ATTLIST property value CDATA #REQUIRED>
  <!ATTLIST property from CDATA #REQUIRED>
  <!ATTLIST property to CDATA #REQUIRED>
  <!ATTLIST property control CDATA #REQUIRED>
 ]>
This function depends on the libxml2 library.  If the m17n library
is configured without libxml2, this function always fail.

@par Return value:
If the operation was successful, mtext_deserialize() returns the
resulting M-text.  Otherwise it returns @c NULL and assigns an error
code to the external variable #merror_code.

@par See Also:
mtext_serialize(), #Mtext_prop_deserializer   

Variable Documentation

◆ Mtext_prop_serializer

MSymbol Mtext_prop_serializer

Symbol for specifying serializer functions.

To serialize a text property, the user must supply a serializer function for that text property. This is done by giving a symbol property whose key is Mtext_prop_serializer and value is a pointer to an appropriate serializer function.

See Also:
mtext_serialize(), MTextPropSerializeFunc

◆ Mtext_prop_deserializer

MSymbol Mtext_prop_deserializer

Symbol for specifying deserializer functions.

To deserialize a text property, the user must supply a deserializer function for that text property. This is done by giving a symbol property whose key is Mtext_prop_deserializer and value is a pointer to an appropriate deserializer function.

See Also:
mtext_deserialize(), MTextPropSerializeFunc

m17n-lib Home