Index

D-Type Unicode Text Module Core Structures

In addition to the basic data types, D-Type Unicode Text Module also defines and utilizes the following structure types:

DT_RECT_SLONG

This structure type describers a rectangle whose coordinates are expressed as 32-bit signed integers.

/* D-Type Rectangle (coordinates expressed as 32-bit signed integers) */ 
typedef struct
{
    DT_SLONG xmn, ymn, xmx, ymx;

} DT_RECT_SLONG;

Here, xmn and ymn represent the minimum (x, y) coordinate of the rectangle (or its top left corner) while xmx and ymx represent the maximum (x, y) coordinate of the rectangle (or its bottom right corner).

DT_MDC

This structure type contains information about D-Type's memory (off-screen) surfaces.

/* D-Type's memory (off-screen) surface */ 
typedef struct
{
    DT_SRAST_L w, h; /* Surface's dimensions in pixels */ 
    DT_UBYTE* m;     /* Pointer to surface's memory buffer */ 
    DT_SLONG l;      /* Length of the buffer in bytes (defines pitch) */ 

} DT_MDC;

The structure members have the following purpose:

DT_TX_DOC_PARAMS

This structure is used by the txTextSetParams and txTextGetParams functions. For details, see the txTextSetParams function.

Deprecation Notice: As of D-Type 8.0.1.3 this structure is deprecated and might be removed in the future.

/* Parameters for text documents */ 
typedef struct
{
    DT_ULONG EnableBits;          /* A set of bit values to enable or disable various text document features */ 
    DT_ULONG ConfigBits;          /* Various configuration bits */ 
    const DT_PD_DOC_PARAMS* Extra /* Optional extra parameters (can be DV_NULL) */ 

} DT_TX_DOC_PARAMS;

DT_TX_TEXTFLOW_AREA

This structure represents a single textflow area and contains parameters such as the area's (x, y) location (in document units), width and height (in document units), type (rectangular, circular, diamond-like etc.), row spacing calculation method (e.g. typographical, mathematical etc.), global text direction (e.g. Letf-to-Right & Top-to-Bottom, Top-to-Bottom & Left-to-Right, Top-to-Bottom & Right-to-Left etc.), bidirectional text display method (bidirectional reordering or bidirectional rotation), device mode (e.g. device dependent, device independent, mixed) and, optionally, a transformation matrix (affine or 2D perspective).

This structure type is utilized by the txTextSetFlow function, but can also be supplied while creating a new Unicode text document using the txTextIniViaStream or txTextIniViaBuffer function.

The structure is defined as follows:

/* Textflow area attributes */ 
typedef struct
{
    DT_SLONG X, Y, W, H;            /* Textflow area's bounding box in document units */ 
    DT_ID_UBYTE Type;               /* Type of textflow area and control of empty text lines */ 
    DT_ID_UBYTE RowType;            /* Row type within the textflow area */ 
    DT_ID_UBYTE WrapType;           /* Text wrap method */ 
    DT_ID_UBYTE GlobalDirection;    /* Global text direction and bidirectional text display method for a textflow area */ 
    DT_ID_UBYTE TargetDeviceID;     /* Textflow area's device mode */ 
    DT_ID_UBYTE TransformAndExtras; /* Identifies the type of the transformation matrix and/or any extra parameters. Can be one of the following:
                                       TX_TM_NULL       = no transformation matrix and no extra parameters - TransformArray/Extra is DV_NULL
                                       TX_TM_1X1        = 1x1 transformation matrix only - TransformArray is a valid pointer to an array
                                                          containing 1 element
                                       TX_TM_2X2        = 2x2 transformation matrix only - TransformArray is a valid pointer to an array
                                                          containing 4 elements
                                       TX_TM_3X3        = 3x3 transformation matrix only - TransformArray is a valid pointer to an array
                                                          containing 9 elements
                                       TX_TM_EXTRA_NULL = extra parameters only - Extra is a valid pointer to the DT_TX_TEXTFLOW_AREA_EXTRA
                                                          structure, Extra->TransformArray is DV_NULL
                                       TX_TM_EXTRA_1X1  = 1x1 transformation matrix and extra parameters - Extra is a valid pointer to
                                                          the DT_TX_TEXTFLOW_AREA_EXTRA structure, Extra->TransformArray is a valid pointer
                                                          to an array containing 1 element
                                       TX_TM_EXTRA_2X2  = 2x2 transformation matrix and extra parameters - Extra is a valid pointer to
                                                          the DT_TX_TEXTFLOW_AREA_EXTRA structure, Extra->TransformArray is a valid pointer
                                                          to an array containing 4 elements
                                       TX_TM_EXTRA_3X3  = 3x3 transformation matrix and extra parameters - Extra is a valid pointer to
                                                          the DT_TX_TEXTFLOW_AREA_EXTRA structure, Extra->TransformArray is a valid pointer
                                                          to an array containing 9 elements
                                    */ 
    union
    {
        /* An affine or perspective transformation to apply to the textflow area */ 
        const DT_FLOAT* TransformArray;
        /* An affine or perspective transformation and any extra parameters to apply to the textflow area */ 
        const DT_TX_TEXTFLOW_AREA_EXTRA* Extra;
    };

} DT_TX_TEXTFLOW_AREA;

The structure members have the following purpose:

DT_TX_TEXTFLOW_AREA_EXTRA

This structure type supplements the DT_TX_TEXTFLOW_AREA structure, providing additional information. The structure is defined as follows:

/* Extra information for DT_TX_TEXTFLOW_AREA */ 
typedef struct
{
    const DT_FLOAT* TransformArray; /* An affine or perspective transformation to apply to the textflow area */ 
    const DT_UBYTE* EdgeArrayLeft;  /* Left edge polyline for text areas with a custom (i.e. user-defined) left edge.
                                       Should be used only with custom text areas (Type=TX_CUSTOM or Type=TX_CUSTOM2). */ 
    const DT_UBYTE* EdgeArrayRight; /* Right edge polyline for text areas with a custom (i.e. user-defined) right edge.
                                       Should be used only with custom text areas (Type=TX_CUSTOM or Type=TX_CUSTOM2). */ 
    DT_SLONG EdgeLenLeft;           /* Length of the EdgeArrayLeft array */ 
    DT_SLONG EdgeLenRight;          /* Length of the EdgeArrayRight array */ 
    DT_ID_UBYTE VAlign;             /* Vertical alignment of text inside the text area, when the text flow does not end in this text area.
                                       Should be used only with rectangular text areas (Type=TX_RECT). */ 
    DT_ID_UBYTE VAlignEnd;          /* Vertical alignment of text inside the text area, when the text flow ends in this text area.
                                       Should be used only with rectangular text areas (Type=TX_RECT). */ 
} DT_TX_TEXTFLOW_AREA_EXTRA;

The structure members have the following purpose:

DT_TX_ATTRIBS

This structure type represents a single text formatting/styling attribute. It is primarily utilized by the txTextSetAttribs function although it can also be supplied while creating a new Unicode text document using the txTextIniViaStream or txTextIniViaBuffer function. It is defined as follows:

/* Text formatting/styling structure */ 
typedef struct
{
    DT_ID_SLONG Id;                  /* Text formatting/styling attribute identifier and indicator if its value is supplied via the Value or Buffer union member */ 

    union
    {
        DT_TX_ATTRIBS_VALUE Value;   /* Value of the formatting/styling attribute (suitable for null-terminated ASCII strings up to 255 bytes long) */ 
        DT_TX_ATTRIBS_BUFFER Buffer; /* Buffer holding the value of the formatting/styling attribute (suitable for longer values and/or binary data) */ 
    };

} DT_TX_ATTRIBS;

The type of the Value union member variable is DT_TX_ATTRIBS_VALUE, which is defined as follows:

/* Formatting/Styling Value */ 
typedef DT_CHAR DT_TX_ATTRIBS_VALUE [256];

This type is suitable for storing null-terminated ASCII strings that are up to 255 characters long. In D-Type Unicode Text Module most formatting/styling attributes have values that are much shorter than 255 bytes. Thus, this type is suitable and recommended for the majority of formatting/styling attributes.

The type of the Buffer union member variable is DT_TX_ATTRIBS_BUFFER, which is defined as follows:

/* Formatting/Styling Buffer */ 
typedef struct
{
    const DT_UBYTE* Addr; /* Memory address at which the value of the formatting/styling attribute begins */ 
    DT_SLONG Len;         /* Length of the value in bytes */ 

} DT_TX_ATTRIBS_BUFFER;

This type is suitable for supplying longer strings and/or binary data. In D-Type Unicode Text Module there are presently a few formatting/styling attributes that may require more than 255 bytes of storage for their values. These are TX_ATTR_TABSTOP_POSITIONS, TX_ATTR_TABSTOP_FLAGS and TX_ATTR_USER_SPECIFIC_CONTENT. Thus, this type is primarily suitable for these three formatting/styling attributes.

Note, however, that regardless of whether the value is supplied via the Value or Buffer union member, all values must be shorter than 1024 bytes in length. This is the current implementation limit. D-Type Unicode Text Module will reject any requests to format/style text if the length of a formatting/styling attribute value equals or exceeds 1024 bytes.

The members of the DT_TX_ATTRIBS structure have the following purpose:

The txTextSetAttribs, txTextIniViaStream and txTextIniViaBuffer functions expect an array of the DT_TX_ATTRIBS structures so that multiple formatting/styling attributes can be applied at the same time. In order to signal the end of the array, the Id member of the last structure in the array must be TX_ATTR_END (-1) while its Value must be an empty string. For example, an array of DT_TX_ATTRIBS structures that specify a font width and height of 60 documents units would be initialized as follows:

const DT_TX_ATTRIBS attrib_array[] =
{
   {TX_ATTR_FONT_WIDTH,  {"60" /* font width in document units */ }},
   {TX_ATTR_FONT_HEIGHT, {"60" /* font height in document units */ }},
   {TX_ATTR_END,         {""   /* mandatory end-of-array */ }}
};

The value TX_ATTR_END (-1) cannot be combined with TX_ATTR_BUFFER (1024). In other words only TX_ATTR_END signals the end of an array, the sum TX_ATTR_BUFFER + TX_ATTR_END is invalid and does not signal anything.

DT_TX_TEXTEDIT_CONFIG

This structure type represents a text edit configuration. For details see the txTextRegisterConfig function.

/* Textedit configuration */ 
typedef struct
{
    DT_SWORD FnDraw;
    DT_SLONG DefaultWidth, DefaultHeight;
    DT_SLONG Name_TextAreaW, Name_TextAreaH;
    DT_SLONG Name_TextString_8, Name_TextString_16;
    DT_SLONG Name_TextFragmentPtr;
    DT_UBYTE DisableTextFormat;

} DT_TX_TEXTEDIT_CONFIG;
 

Index