In addition to the basic data types, D-Type Unicode Text Module also defines and utilizes the following structure types:
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).
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:
w — width of the memory surface in pixels. This value must be positive.
h — height of the memory surface in pixels. D-Type supports bottom-to-top and top-to-bottom surfaces. A positive h value indicates a bottom-to-top surface; a negative h value indicates a top-to-bottom surface. The value 0 is illegal.
m — pointer to a memory buffer that stores the surface's pixels. Depending on the format of the surface, each pixel in the buffer is represented with 8, 16, 24 or 32 bits (i.e. 1, 2, 3 or 4 bytes per pixel).
l — length of the memory buffer in bytes; must equal pitch * abs(h)
In the above equation, pitch is the distance, in bytes, between two memory addresses in the buffer that represent the beginning of two neighbouring pixel rows. Each pixel row consists of precisely w * bytes per pixel bytes that represent the surface's pixels. Consequently, a valid pitch value must not be less than w * bytes per pixel. A pitch value that is exactly w * bytes per pixel bytes indicates that the pixel rows are contiguous; in other words there are no extra bytes between the neighbouring pixel rows. A pitch value that is larger than w * bytes per pixel bytes indicates that the pixel rows are non contiguous; in other words at the end of each row there are some extra bytes (the number of extra bytes is pitch - w * bytes per pixel). Note that when rendering to the memory surface D-Type never reads or writes these extra bytes.
Although not explicitly specified, pitch is an important value that has a direct impact on how D-Type renders pixels to your memory surface. To obtain the surface's pitch, D-Type divides the length of the memory buffer l by the absolute height of the memory surface h. For this reason, you must ensure that l is divisible by abs(h) and that the result of this division is not less than w * bytes per pixel. If these conditions are not met, your pitch value is not properly defined and D-Type will assume the value w * bytes per pixel instead.
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;
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:
X, Y — (x, y) coordinate of the textflow area's bounding box (its top left corner), in document units.
W, H — width and height of the textflow area's bounding box, in document units. Both values must be positive.
Type — type of textflow area and control of empty text lines. The first 6 bits (Bit 0 - Bit 5) are interpreted as a single 6 bit value. This value specifies the type of the text area and can be one of the following:
TX_RECT 0 /* Rectangular */ TX_CUSTOM 5 /* Custom */ TX_CUSTOM2 6 /* Custom With Extra Precision */ TX_CIRC_QRTR_A 10 /* Quarter-Circular A */ TX_CIRC_QRTR_B 11 /* Quarter-Circular B */ TX_CIRC_QRTR_C 12 /* Quarter-Circular C */ TX_CIRC_QRTR_D 13 /* Quarter-Circular D */ TX_CIRC_HALF_A 14 /* Half-Circular A */ TX_CIRC_HALF_B 15 /* Half-Circular B */ TX_CIRC_HALF_C 16 /* Half-Circular C */ TX_CIRC_HALF_D 17 /* Half-Circular D */ TX_CIRC 18 /* Circular */ TX_DIAM_QRTR_A 20 /* Quarter-Diamond A */ TX_DIAM_QRTR_B 21 /* Quarter-Diamond B */ TX_DIAM_QRTR_C 22 /* Quarter-Diamond C */ TX_DIAM_QRTR_D 23 /* Quarter-Diamond D */ TX_DIAM_HALF_A 24 /* Half-Diamond A */ TX_DIAM_HALF_B 25 /* Half-Diamond B */ TX_DIAM_HALF_C 26 /* Half-Diamond C */ TX_DIAM_HALF_D 27 /* Half-Diamond D */ TX_DIAM 28 /* Diamond */
The seventh bit (Bit 6) is interpreted as a single bit value that specifies how the left (pdTextAreaEdgeLeft) and right edge (pdTextAreaEdgeRight) in non-rectangular text areas will be calculated. If this bit is set (1), the calculation will be more precise but slower; otherwise, if this bit is unset (0), the calculation will be less precise but faster. In rectangular text areas, this bit is ignored.
The final bit (Bit 7) is interpreted as a single bit value that signifies whether the control of empty text lines is enabled. If this bit is set (1), the control of empty text lines is enabled; otherwise, if this bit is unset (0), the control of empty text lines is disabled.
When the control of empty text lines is enabled, D-Type Engine will ignore any trailing empty text lines (i.e. text lines that only contain white characters such as spaces or carriage returns) when performing vertical alignment of text in this text area. This is useful in high-end text layout applications that require more professional vertical alignment of text.
RowType — specifies the way spacing between rows is calculated within the textflow area. Can be one of the following:
TX_MATHROW 0 /* mathematically calculate spacing between text rows */ TX_TYPOROW 10 /* respect typographic values (i.e. sTypoAscender, sTypoDescender) when calculating spacing between text rows */ TX_TYPOROW_LINEGAP 20 /* same as TX_TYPOROW but adds additional linegap (i.e. sTypoLineGap), if available in the font */ TX_WINTYPOROW 30 /* respect Windows specific typographic values (i.e. usWinAscent, usWinDescent) when calculating spacing between text rows */ TX_HORTYPOROW 110 /* same as TX_TYPOROW but horizontal typographic values are used for text in vertical layout (columns) */ TX_HORTYPOROW_LINEGAP 120 /* same as TX_TYPOROW_LINEGAP but horizontal typographic values are used for text in vertical layout (columns) */
Explanation of row spacing calculation methods:
TX_MATHROW (0) = Mathematically calculate spacing between text rows.
TX_TYPOROW (10) = Respect typographic values when calculating spacing between text rows. The typographic values must be defined in the font file in order for this method to function as intended. For text in horizontal layout (rows), the typographic values are supplied by the sTypoAscender and sTypoDescender fields of the OS/2 table (TrueType/OpenType fonts) or the Ascender and Descender key of the Font Metrics (AFM) file (Type 1/Type 3 fonts). D-Type Font Engine refers to these values in a portable fashion via the DV_NVAL_ASCENDER and DV_NVAL_DESCENDER identifiers. For text in vertical layout (columns), the typographic values are supplied by the vertTypoAscender and vertTypoDescender fields of the vhea table (TrueType/OpenType fonts). D-Type Font Engine refers to these values in a portable fashion via the DV_NVAL_VER_ASCENDER and DV_NVAL_VER_DESCENDER identifiers. If the typographic values are not defined in the font file, method 0 will be used instead.
TX_TYPOROW_LINEGAP (20) = Same as method 10 but adds an additional linegap, if available in the font. For text in horizontal layout (rows), this additional linegap is supplied by the sTypoLineGap field of the OS/2 table (TrueType/OpenType fonts); in Type 1 and Type 3 fonts, this information is most likely not available. D-Type Font Engine refers to this value in a portable fashion via the DV_NVAL_LINEGAP identifier. For text in vertical layout (columns), the additional linegap is supplied by the vertTypoLineGap field of the vhea table (TrueType/OpenType fonts). D-Type Font Engine refers to this value in a portable fashion via the DV_NVAL_VER_LINEGAP identifier.
TX_WINTYPOROW (30) = Respect Windows specific typographic values when calculating spacing between text rows. The Windows specific typographic values must be defined in the font file in order for this method to function as intended. For text in either horizontal layout (rows) or vertical layout (columns), the Windows specific typographic values are supplied by the usWinAscent and usWinDescent fields of the OS/2 table (TrueType/OpenType fonts). D-Type Font Engine refers to these values in a portable fashion via the DV_NVAL_WIN_ASCENT and DV_NVAL_WIN_DESCENT identifiers. If the Windows specific typographic values are not defined in the font file, method 0 will be used instead.
TX_HORTYPOROW (110) = Same as method 10, but horizontal typographic values are used for text in vertical layout (columns). Although not ideal from a purely mathematical standpoint, this method seems to work well with most CJK fonts.
TX_HORTYPOROW_LINEGAP (120) = Same as method 20, but horizontal typographic values are used for text in vertical layout (columns). Although not ideal from a purely mathematical standpoint, this method seems to work well with most CJK fonts.
WrapType — text wrap method. Can be one of the following:
TX_WRAP 0 /* Soft Wrap Enabled */ TX_NOWRAP_A 1 /* Soft Wrap Disabled - trim text after any character */ TX_NOWRAP_B 2 /* Soft Wrap Disabled - trim text only after space or some other breakable character (e.g. CJK) but not after a hyphen */ TX_NOWRAP_C 3 /* Soft Wrap Disabled - trim text only after space or some other breakable character (e.g. CJK) or after a hyphen */ TX_NOWRAP_D 4 /* Soft Wrap Disabled - trim text after any character and add a horizontal ellipsis */
Most applications will set WrapType to TX_WRAP (0).
GlobalDirection — specifies the global text direction and bidirectional text display method for a textflow area. Can be one of the following:
/* Horizontal Layout (Text in Rows) and Bidirectional Reordering: */ TX_DIR_ROW_LR_TB 0 /* Letf-to-Right, Top-to-Bottom (e.g. Latin, Cyrillic, Greek) */ TX_DIR_ROW_RL_TB 1 /* Right-to-Left, Top-to-Bottom (e.g. Arabic, Hebrew) */ TX_DIR_ROW_LR_BT 2 /* Letf-to-Right, Bottom-to-Top */ TX_DIR_ROW_RL_BT 3 /* Right-to-Left, Bottom-to-Top */ TX_DIR_ROW_LR_TB_SWAP 4 /* Same as TX_DIR_ROW_LR_TB but swap Portrait & Landscape */ TX_DIR_ROW_RL_TB_SWAP 5 /* Same as TX_DIR_ROW_RL_TB but swap Portrait & Landscape */ TX_DIR_ROW_LR_BT_SWAP 6 /* Same as TX_DIR_ROW_LR_BT but swap Portrait & Landscape */ TX_DIR_ROW_RL_BT_SWAP 7 /* Same as TX_DIR_ROW_RL_BT but swap Portrait & Landscape */ /* Vertical Layout (Text in Columns) and Bidirectional Reordering: */ TX_DIR_COL_TB_RL 8 /* Top-to-Bottom, Right-to-Left (e.g. Vertical Chinese) */ TX_DIR_COL_BT_RL 9 /* Bottom-to-Top, Right-to-Left */ TX_DIR_COL_TB_LR 10 /* Top-to-Bottom, Left-to-Right */ TX_DIR_COL_BT_LR 11 /* Bottom-to-Top, Left-to-Right */ TX_DIR_COL_TB_RL_SWAP 12 /* Same as TX_DIR_COL_TB_RL but swap Portrait & Landscape */ TX_DIR_COL_BT_RL_SWAP 13 /* Same as TX_DIR_COL_BT_RL but swap Portrait & Landscape */ TX_DIR_COL_TB_LR_SWAP 14 /* Same as TX_DIR_COL_TB_LR but swap Portrait & Landscape */ TX_DIR_COL_BT_LR_SWAP 15 /* Same as TX_DIR_COL_BT_LR but swap Portrait & Landscape */ /* Horizontal Layout (Text in Rows) and Bidirectional Rotation: */ TX_DIR_ROW_BIDIROT_LR_TB 16 /* Letf-to-Right, Top-to-Bottom (e.g. Latin, Cyrillic, Greek) */ TX_DIR_ROW_BIDIROT_RL_TB 17 /* Right-to-Left, Top-to-Bottom (e.g. Arabic, Hebrew) */ TX_DIR_ROW_BIDIROT_LR_BT 18 /* Letf-to-Right, Bottom-to-Top */ TX_DIR_ROW_BIDIROT_RL_BT 19 /* Right-to-Left, Bottom-to-Top */ TX_DIR_ROW_BIDIROT_LR_TB_SWAP 20 /* Same as TX_DIR_ROW_BIDIROT_LR_TB but swap Portrait & Landscape */ TX_DIR_ROW_BIDIROT_RL_TB_SWAP 21 /* Same as TX_DIR_ROW_BIDIROT_RL_TB but swap Portrait & Landscape */ TX_DIR_ROW_BIDIROT_LR_BT_SWAP 22 /* Same as TX_DIR_ROW_BIDIROT_LR_BT but swap Portrait & Landscape */ TX_DIR_ROW_BIDIROT_RL_BT_SWAP 23 /* Same as TX_DIR_ROW_BIDIROT_RL_BT but swap Portrait & Landscape */ /* Vertical Layout (Text in Columns) and Bidirectional Rotation: */ TX_DIR_COL_BIDIROT_TB_RL 24 /* Top-to-Bottom, Right-to-Left (e.g. Vertical Chinese) */ TX_DIR_COL_BIDIROT_BT_RL 25 /* Bottom-to-Top, Right-to-Left */ TX_DIR_COL_BIDIROT_TB_LR 26 /* Top-to-Bottom, Left-to-Right */ TX_DIR_COL_BIDIROT_BT_LR 27 /* Bottom-to-Top, Left-to-Right */ TX_DIR_COL_BIDIROT_TB_RL_SWAP 28 /* Same as TX_DIR_COL_BIDIROT_TB_RL but swap Portrait & Landscape */ TX_DIR_COL_BIDIROT_BT_RL_SWAP 29 /* Same as TX_DIR_COL_BIDIROT_BT_RL but swap Portrait & Landscape */ TX_DIR_COL_BIDIROT_TB_LR_SWAP 30 /* Same as TX_DIR_COL_BIDIROT_TB_LR but swap Portrait & Landscape */ TX_DIR_COL_BIDIROT_BT_LR_SWAP 31 /* Same as TX_DIR_COL_BIDIROT_BT_LR but swap Portrait & Landscape */
D-Type Engine can display text in horizontal writing mode (text in rows) and vertical writing mode (text in columns). In horizontal writing mode, the global text progression can be Letf-to-Right/Top-to-Bottom, Right-to-Left/Top-to-Bottom, Letf-to-Right/Bottom-to-Top or Right-to-Left/Bottom-to-Top. In vertical writing mode, the global text progression can be Top-to-Bottom/Right-to-Left, Bottom-to-Top/Right-to-Left, Top-to-Bottom/Left-to-Right or Bottom-to-Top/Left-to-Right.
Additionally, D-Type Engine can display bidirectional text (e.g. a mixture of left-to-right text such as English or Chinese and right-to-left text such as Arabic or Hebrew) using two different methods: the first method is Bidirectional Reordering, the second method is Bidirectional Rotation. Visually, these two methods produce quite different output. However, both are suitable for displaying text that was processed by the Unicode Bidirectional Algorithm (BiDi).
With Bidirectional Reordering the characters are reordered for display depending on the relative direction of the containing text fragment. Thus, a left-to-right text fragment has its characters ordered (visually) in the opposite order from a right-to-left text fragment. While reading bidirectional text, from start to end, the reader must alternate the reading direction (left-to-right/right-to-left in horizontal writing mode or top-to-bottom/bottom-to-top in vertical writing mode) each time a change of direction occurs. This is also the progression of the cursor as it advances from one character to another. This means that with Bidirectional Reordering, the order in which the characters are displayed is not the same as the order in which they are stored in memory (logical or storage order).
With Bidirectional Rotation all characters are ordered uniformly (e.g. from left-to-right in horizontal writing mode or top-to-bottom in vertical writing mode) regardless of whether the containing text fragment has a left-to-right or right-to-left direction. However, their rotation depends on the relative direction of the containing text fragment. More specifically, characters that are part of a left-to-right text fragment are rotated 180 degrees relative to the characters that are part of a right-to-left text fragment. Thus, while reading bidirectional text, from start to end, the reader must rotate the display surface or tilt his/her head (clockwise or counterclockwise) each time a change of direction occurs. However, the reading direction and the progression of the cursor remain uniform. This also means that with Bidirectional Rotation, the order in which the characters are displayed is the same as the order in which they are stored in memory.
Bidirectional Reordering is frequently used in horizontal writing mode and also works well in vertical writing mode. Bidirectional Rotation is typically not used in horizontal writing mode due to the fact that almost all Unicode scripts, when displayed in horizontal writing mode, have their orientation set to portrait (meaning that the glyph's x-axis in font design space is parallel with the baseline). Using Bidirectional Rotation in this case would require the user to rotate the display surface by 180 degrees (clockwise or counterclockwise) each time a change of direction is encountered — which is, needles to say, far from practical. However, Bidirectional Rotation works well in vertical writing mode. This is due to the fact that vertical writing is used mostly with CJK scripts (Chinese/Japanese/Korean) which typically have their orientation set to landscape (meaning that the glyph's x-axis in font design space is perpendicular to the baseline). Non-CJK scripts, such as Latin or Arabic then have their orientation set to portrait. Under this scheme, the reading direction and the progression of the cursor is always top-to-bottom. When reading the majority of content (i.e. CJK text), there is no need to rotate the display surface. However, when a left-to-right text fragment (e.g. English) is encountered, the reader rotates the display surface by 90 degrees clockwise. Similarly, when a right-to-left text fragment (e.g. Arabic) is encountered, the reader rotates the display surface by 90 degrees counterclockwise. In all three cases (Chinese, English and Arabic) the characters are ordered from top to bottom and the reader is never expected to alter the reading direction (which would otherwise be required if Bidirectional Reordering was used). This is not to say that Bidirectional Reordering cannot be used in vertical writing mode. However, Bidirectional Rotation might work better in certain applications as rotating the display surface by 90 degrees clockwise or counterclockwise relative to the vertical baseline is sometimes considered a more practical way of reading vertical bidirectional text.
TargetDeviceID — specifies textflow area's device mode. Can be one of the following:
TX_LAY_FRAC 0 /* Device Independent (Mode 0, Enhanced Fractional Positioning) */ TX_LAY_WHOLE 1 /* Device Independent (Mode 0, Enhanced Whole Pixel Positioning) */ TX_LAY_DEVICE_A 2 /* Device Dependent (Mode 1) */ TX_LAY_DEVICE_B 3 /* Device Dependent (Mode 2) */ TX_LAY_MIXED_A 4 /* Mixed (Mode 101) */ TX_LAY_MIXED_B 5 /* Mixed (Mode 102) */
Explanation of device modes:
0 = Device Independent Mode. Text will be rendered in a device independent mode, which means that text metrics are independent of the device, resolution or zoom factor and are mathematically accurate. Therefore, characters that are supposed to vertically line up will always line up. In addition, all text lines will always fit within the width of the textflow area. Recommended for WYSIWYG applications.
1 = Device Dependent Mode #1. Text will be rendered in a device dependent mode, which means that text metrics are device specific. This mode utilizes a complex device dependent formula that is specially crafted to give good looking character spacing (calculated in whole-pixel units). This mode corresponds to the DV_TEXTMODE_DEVICE value in D-Type Standard Engine. See the dtxTextDoOutput family of functions in D-Type Standard Engine Manual for details.
Because this mode is device dependent, please be aware that the length of certain text lines will sometimes exceed the width of the textflow area; also characters that are supposed to vertically line up will usually not line up. This behavior is by design.
2 = Device Dependent Mode #2. Text will be rendered in a device dependent mode, which means that text metrics are device specific. This mode is similar to Device Dependent Mode #1 since it also utilizes a complex device dependent formula crafted to give good looking character spacing. However, this mode produces even better looking and easier to read text, especially at smaller sizes. This is accomplished by artificially increasing the amount of character spacing between certain characters and in certain conditions. This mode corresponds to the DV_TEXTMODE_DEVICE_2 value in D-Type Standard Engine. See the dtxTextDoOutput family of functions in D-Type Standard Engine Manual for details.
Because this mode is device dependent (and also because the character spacing may be artificially increased), please be aware that the length of certain text lines will sometimes exceed the width of the textflow area; also characters that are supposed to vertically line up will usually not line up. This behavior is by design.
101 = Mixed Mode #1. By default, the engine will render all text using Device Dependent Mode #1. However, if there are any text lines whose length would exceed the width of the textflow area, those text lines will be rendered in a device independent manner. Consequently, this mode guarantees that all text lines will always fit within the width of the textflow area.
102 = Mixed Mode #2. By default, the engine will render all text using Device Dependent Mode #2. However, if there are any text lines whose length would exceed the width of the textflow area, then the engine will attempt to render those lines using Device Dependent Mode #1. If, after this, there are still some text lines whose length exceeds the width of the textflow area, those lines will be rendered in a device independent manner. Consequently, this mode guarantees that all text lines will always fit within the width of the textflow area. This mode usually produces great looking character spacing and is highly recommended whenever true WYSIWYG support is not a priority.
TransformAndExtras — type of transformation matrix held in the TransformArray member or extra parameters. It is used in conjunction with the TransformArray or Extra members and can be one of the following:
TX_TM_NULL 0 /* no transformation matrix and no extra parameters - TransformArray/Extra is DV_NULL */ TX_TM_1X1 1 /* 1x1 transformation matrix only - TransformArray is a valid pointer to an array containing 1 element */ TX_TM_2X2 2 /* 2x2 transformation matrix only - TransformArray is a valid pointer to an array containing 4 elements */ TX_TM_3X3 3 /* 3x3 transformation matrix only - TransformArray is a valid pointer to an array containing 9 elements */ TX_TM_EXTRA_NULL 4 /* 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 5 /* 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 6 /* 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 7 /* 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 */
TransformArray — a pointer to an array that holds an affine or perspective transformation to apply to the textflow area. Depending on the value of the TransformAndExtras member, this pointer is either DV_NULL or points to an array of floats containing 1, 4 or 9 elements.
Extra — a pointer to the DT_TX_TEXTFLOW_AREA_EXTRA structure. This structure contains a pointer to an array that holds an affine or perspective transformation and any additional parameters (e.g. vertical text alignment, user-defined left/right edge) to apply to the textflow area.
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:
TransformArray — a pointer to an array that holds an affine or perspective transformation to apply to the textflow area. Depending on the value of the TransformAndExtras member of the DT_TX_TEXTFLOW_AREA structure, this pointer is either DV_NULL or points to an array of floats containing 1, 4 or 9 elements.
EdgeArrayLeft — a pointer to an array that defines the left edge polyline for text areas with a custom (i.e. user-defined) left edge. In order for this feature to work, the Type member of the DT_TX_TEXTFLOW_AREA structure must be set to TX_CUSTOM or TX_CUSTOM2. In all other cases, EdgeArrayLeft should be set to DV_NULL and EdgeLenLeft should be set to 0.
Explanation of the left edge polyline:
The left edge polyline is defined as a sequence of connected segments which can be made of lines, Quadratic B-Spline and/or Bézier curves. Each sequence begins with the descriptor (value 20, 25 or 24) followed by an appropriate number of coordinates for the control points as shown below:
Line: 20, X1, Y1 Quadratic B-Spline Curve: 25, X1, Y1, X2, Y2 Bézier Curve: 24, X1, Y1, X2, Y2, X3, Y3
The size of each descriptor value (20, 25 or 24) is always 1 byte.
When the Type member of the DT_TX_TEXTFLOW_AREA structure is set to TX_CUSTOM, the size of each coordinate is 1 byte. In this case X1, X2 and X3 represent X coordinates of the segment's control points and must be in the 0-255 range. The value 0 means 0% of the text area width while the value 255 means 100% of the text area width. Similarly, Y1, Y2 and Y3 represent Y coordinates of the segment's control points and must be in the 0-255 range. The value 0 means 0% of the text area height while the value 255 means 100% of the text area height
When the Type member of the DT_TX_TEXTFLOW_AREA structure is set to TX_CUSTOM2, the size of each coordinate is 2 bytes (little endian byte ordering). In this case X1, X2 and X3 represent X coordinates of the segment's control points and must be in the 0 - 65,535 range. The value 0 means 0% of the text area width while the value 65,535 means 100% of the text area width. Similarly, Y1, Y2 and Y3 represent Y coordinates of the segment's control points and must be in the 0 - 65,535 range. The value 0 means 0% of the text area height while the value 65,535 means 100% of the text area height.
Implicitly, the first control point is always located at the coordinate (0,0) which is the top left corner of the text area. Therefore, the user definition of the polyline starts with the second control point. In addition, the last control point is automatically placed at the coordinate (x_last, y_max) where x_last is the X coordinate of the last user defined control point and y_max is 255 (when Type is TX_CUSTOM) or 65,535 (when Type is TX_CUSTOM2). In this way the polyline and the text area always have the same height.
Although any sequence of connected lines, Quadratic B-Spline and/or Bézier curves can be used to define a polyline, the Y coordinates should be specified in a non-decreasing order. That is, any time a new Y coordinates is specified, its value should not be less than the value of the previously specified Y coordinate. This is to ensure that the polyline does not have multiple intersections with any horizontal line. This restriction does not apply to X coordinates.
EdgeArrayRight — a pointer to an array that defines the right edge polyline for text areas with a custom (i.e. user-defined) left edge. In order for this feature to work, the Type member of the DT_TX_TEXTFLOW_AREA structure must be set to TX_CUSTOM or TX_CUSTOM2. In all other cases, EdgeArrayRight should be set to DV_NULL and EdgeLenRight should be set to 0.
Explanation of the right edge polyline:
The right edge polyline is defined as a sequence of connected segments which can be made of lines, Quadratic B-Spline and/or Bézier curves. Each sequence begins with the descriptor (value 20, 25 or 24) followed by an appropriate number of coordinates for the control points as shown below:
Line: 20, X1, Y1 Quadratic B-Spline Curve: 25, X1, Y1, X2, Y2 Bézier Curve: 24, X1, Y1, X2, Y2, X3, Y3
The size of each descriptor value (20, 25 or 24) is always 1 byte.
When the Type member of the DT_TX_TEXTFLOW_AREA structure is set to TX_CUSTOM, the size of each coordinate is 1 byte. In this case X1, X2 and X3 represent X coordinates of the segment's control points and must be in the 0-255 range. The value 0 means 0% of the text area width while the value 255 means 100% of the text area width. Similarly, Y1, Y2 and Y3 represent Y coordinates of the segment's control points and must be in the 0-255 range. The value 0 means 0% of the text area height while the value 255 means 100% of the text area height
When the Type member of the DT_TX_TEXTFLOW_AREA structure is set to TX_CUSTOM2, the size of each coordinate is 2 bytes (little endian byte ordering). In this case X1, X2 and X3 represent X coordinates of the segment's control points and must be in the 0 - 65,535 range. The value 0 means 0% of the text area width while the value 65,535 means 100% of the text area width. Similarly, Y1, Y2 and Y3 represent Y coordinates of the segment's control points and must be in the 0 - 65,535 range. The value 0 means 0% of the text area height while the value 65,535 means 100% of the text area height.
Implicitly, the first control point is always located at the coordinate (0,0) which is the top right corner of the text area. Therefore, the user definition of the polyline starts with the second control point. In addition, the last control point is automatically placed at the coordinate (x_last, y_max) where x_last is the X coordinate of the last user defined control point and y_max is 255 (when Type is TX_CUSTOM) or 65,535 (when Type is TX_CUSTOM2). In this way the polyline and the text area always have the same height.
Although any sequence of connected lines, Quadratic B-Spline and/or Bézier curves can be used to define a polyline, the Y coordinates should be specified in a non-decreasing order. That is, any time a new Y coordinates is specified, its value should not be less than the value of the previously specified Y coordinate. This is to ensure that the polyline does not have multiple intersections with any horizontal line. This restriction does not apply to X coordinates.
EdgeLenLeft — the length of the EdgeArrayLeft array, in bytes.
EdgeLenRight — the length of the EdgeArrayRight array, in bytes.
VAlign — vertical alignment of text inside the text area (top, middle, bottom, justified), when the text flow does not end in this text area. Can be one of the following:
TX_VALIGN_TOP 0 /* Top */ TX_VALING_MIDDLE 1 /* Middle */ TX_VALIGN_BOTTOM 2 /* Bottom */ TX_VALIGN_JUSTIFIED 3 /* Justified */
Values other than TX_VALIGN_TOP should be used only with rectangular text areas, i.e. when the Type member of the DT_TX_TEXTFLOW_AREA structure is set to TX_RECT.
VAlignEnd — vertical alignment of text inside the text area (top, middle, bottom, justified), when the text flow ends in this text area. Can be one of the following:
TX_VALIGN_TOP 0 /* Top */ TX_VALING_MIDDLE 1 /* Middle */ TX_VALIGN_BOTTOM 2 /* Bottom */ TX_VALIGN_JUSTIFIED 3 /* Justified */
Values other than TX_VALIGN_TOP should be used only with rectangular text areas, i.e. when the Type member of the DT_TX_TEXTFLOW_AREA structure is set to TX_RECT.
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:
Id — identifies the formatting/styling attribute and, at the same time, specifies whether its value is supplied via the Value or Buffer union member variable.
The list of currently supported formatting/styling attribute identifiers follows. Click on any attribute identifier for a more detailed description:
/* Typography */ TX_ATTR_FONT_INDEX 1 TX_ATTR_FONT_UNIQUEID 2 TX_ATTR_FONT_MMCONTRIBUTIONS 3 TX_ATTR_FONT_WIDTH 4 TX_ATTR_FONT_HEIGHT 5 TX_ATTR_SKEW_HOR 6 TX_ATTR_SKEW_VER 7 TX_ATTR_ROTATION 8 TX_ATTR_EFFECT 9 TX_ATTR_EFFECT_PARAM0 54 TX_ATTR_EFFECT_PARAM1 55 TX_ATTR_EFFECT_PARAM2 56 TX_ATTR_EFFECT_PARAM3 57 TX_ATTR_EFFECT_PARAM4 58 /* Text Body */ TX_ATTR_BODY 38 TX_ATTR_BODY_RGBT 10 TX_ATTR_BODY_EP 11 TX_ATTR_BODY_EFFECTS 60 /* Text Shadow */ TX_ATTR_SHADOW 39 TX_ATTR_SHADOW_DX 12 TX_ATTR_SHADOW_DY 13 TX_ATTR_SHADOW_RGBT 14 TX_ATTR_SHADOW_EP 15 TX_ATTR_SHADOW_EFFECTS 61 /* Text Outline */ TX_ATTR_OUTLINE 40 TX_ATTR_OUTLINE_TREATMENT 37 TX_ATTR_OUTLINE_THICKNESS 16 TX_ATTR_OUTLINE_SEGMENT 17 TX_ATTR_OUTLINE_DASHSIZE 69 TX_ATTR_OUTLINE_RGBT 18 TX_ATTR_OUTLINE_EP 19 TX_ATTR_OUTLINE_EFFECTS 62 /* Text Underline */ TX_ATTR_UNDERLINE 44 TX_ATTR_UNDERLINE_THICKNESS 45 TX_ATTR_UNDERLINE_SEGMENT 46 TX_ATTR_UNDERLINE_DASHSIZE 70 TX_ATTR_UNDERLINE_RGBT 47 TX_ATTR_UNDERLINE_EP 48 TX_ATTR_UNDERLINE_EFFECTS 63 /* Text Layout */ TX_ATTR_TEXTLAYOUT 41 TX_ATTR_SPACING_LETTER 20 TX_ATTR_SPACING_ROW 21 TX_ATTR_SPACING_BASELINE 43 TX_ATTR_SPACING_FACTOR 49 TX_ATTR_DX 22 TX_ATTR_DY 23 TX_ATTR_ALIGN 24 TX_ATTR_ALIGNEND 25 TX_ATTR_VALIGN_ROW 59 TX_ATTR_KERNING 26 TX_ATTR_HINTING 27 TX_ATTR_POSITIONING 28 TX_ATTR_DIRECTION 29 TX_ATTR_ORIENTATION 30 /* Text Ruler */ TX_ATTR_TEXTRULER 42 TX_ATTR_TABSTOP_POSITIONS 31 TX_ATTR_TABSTOP_FLAGS 32 TX_ATTR_MARGIN_LEFT 67 TX_ATTR_MARGIN_RIGHT 68 TX_ATTR_INDENT_LEFT 33 TX_ATTR_INDENT_RIGHT 34 /* Miscellaneous */ TX_ATTR_ENCODING 35 TX_ATTR_SHAPING 36 TX_ATTR_SHAPING_PARAM0 66 TX_ATTR_BREAK_FLAGS 50 TX_ATTR_HYPHENATION 51 TX_ATTR_MISC_ATTRIBS 64 TX_ATTR_LANGUAGE 65 TX_ATTR_POWERFONT_PTR 52 /* not currently supported */ TX_ATTR_USER_SPECIFIC_CONTENT 53 /* Typographic Frame Body */ TX_ATTR_TYPOFRAME_BODY 71 TX_ATTR_TYPOFRAME_BODY_RGBT 72 TX_ATTR_TYPOFRAME_BODY_EP 73 TX_ATTR_TYPOFRAME_BODY_EFFECTS 74 /* Typographic Frame Shadow */ TX_ATTR_TYPOFRAME_SHADOW 75 TX_ATTR_TYPOFRAME_SHADOW_DX 76 TX_ATTR_TYPOFRAME_SHADOW_DY 77 TX_ATTR_TYPOFRAME_SHADOW_RGBT 78 TX_ATTR_TYPOFRAME_SHADOW_EP 79 TX_ATTR_TYPOFRAME_SHADOW_EFFECTS 80 /* Typographic Frame Outline */ TX_ATTR_TYPOFRAME_OUTLINE 81 TX_ATTR_TYPOFRAME_OUTLINE_TREATMENT 82 TX_ATTR_TYPOFRAME_OUTLINE_THICKNESS 83 TX_ATTR_TYPOFRAME_OUTLINE_SEGMENT 84 TX_ATTR_TYPOFRAME_OUTLINE_DASHSIZE 85 TX_ATTR_TYPOFRAME_OUTLINE_RGBT 86 TX_ATTR_TYPOFRAME_OUTLINE_EP 87 TX_ATTR_TYPOFRAME_OUTLINE_EFFECTS 88 /* Text Extras - Row Boundary Body */ TX_ATTR_ROWBOUND_BODY 89 TX_ATTR_ROWBOUND_BODY_RGBT 90 TX_ATTR_ROWBOUND_BODY_EP 91 TX_ATTR_ROWBOUND_BODY_EFFECTS 92 /* Text Extras - Row Boundary Shadow */ TX_ATTR_ROWBOUND_SHADOW 93 TX_ATTR_ROWBOUND_SHADOW_DX 94 TX_ATTR_ROWBOUND_SHADOW_DY 95 TX_ATTR_ROWBOUND_SHADOW_RGBT 96 TX_ATTR_ROWBOUND_SHADOW_EP 97 TX_ATTR_ROWBOUND_SHADOW_EFFECTS 98 /* Text Extras - Row Boundary Outline */ TX_ATTR_ROWBOUND_OUTLINE 99 TX_ATTR_ROWBOUND_OUTLINE_TREATMENT 100 TX_ATTR_ROWBOUND_OUTLINE_THICKNESS 101 TX_ATTR_ROWBOUND_OUTLINE_SEGMENT 102 TX_ATTR_ROWBOUND_OUTLINE_DASHSIZE 103 TX_ATTR_ROWBOUND_OUTLINE_RGBT 104 TX_ATTR_ROWBOUND_OUTLINE_EP 105 TX_ATTR_ROWBOUND_OUTLINE_EFFECTS 106 /* Text Extras - Row Boundary General */ TX_ATTR_ROWBOUND_MARGIN_LEFT 107 TX_ATTR_ROWBOUND_MARGIN_RIGHT 108 TX_ATTR_ROWBOUND_MARGIN_TOP 109 TX_ATTR_ROWBOUND_MARGIN_BOTTOM 110 TX_ATTR_ROWBOUND_ROUND 111 TX_ATTR_ROWBOUND_MERGE 112 /* Text Extras - Baseline Line */ TX_ATTR_BASELINE_LINE 113 TX_ATTR_BASELINE_LINE_THICKNESS 114 TX_ATTR_BASELINE_LINE_SEGMENT 115 TX_ATTR_BASELINE_LINE_DASHSIZE 116 TX_ATTR_BASELINE_LINE_START 117 TX_ATTR_BASELINE_LINE_END 118 TX_ATTR_BASELINE_LINE_RGBT 119 TX_ATTR_BASELINE_LINE_EP 120 TX_ATTR_BASELINE_LINE_EFFECTS 121 /* Text Extras - Baseline General */ TX_ATTR_BASELINE_MARGIN_LEFT 122 TX_ATTR_BASELINE_MARGIN_RIGHT 123 /* Text Extras - Baseline Shadow */ TX_ATTR_BASELINE_SHADOW 124 TX_ATTR_BASELINE_SHADOW_DX 125 TX_ATTR_BASELINE_SHADOW_DY 126 TX_ATTR_BASELINE_SHADOW_RGBT 127 TX_ATTR_BASELINE_SHADOW_EP 128 TX_ATTR_BASELINE_SHADOW_EFFECTS 129
If Id is set to one of the above attribute identifiers, this automatically indicates that its value is supplied via the Value union member variable. If, however, Id is set to one of the above attribute identifiers increased by TX_ATTR_BUFFER (1024), then this is an indicator that its value is supplied via the Buffer union member variable.
Example 1a - value supplied via the Value union member variable
DT_TX_ATTRIBS attrib; attrib.Id = TX_ATTR_FONT_WIDTH; attrib.Value = 48;
Example 1b - value supplied via the Value union member variable
DT_TX_ATTRIBS attrib = {TX_ATTR_FONT_WIDTH, {"48"}};
Example 2a - value supplied via the Buffer union member variable
const DT_CHAR* buffer = "48"; DT_TX_ATTRIBS attrib; attrib.Id = TX_ATTR_BUFFER + TX_ATTR_FONT_WIDTH; attrib.Buffer.Addr = (DT_UBYTE*)buffer; attrib.Buffer.Len = strlen(buffer);
Example 2b - value supplied via the Buffer union member variable
DT_UBYTE buffer[512] = {32, 22, 12, 12, 44, 0, 0, 12, 21, 44, 78, 33, 66, 88, 12, 14, etc...} /* some binary data */ DT_TX_ATTRIBS attrib; attrib.Id = TX_ATTR_BUFFER + TX_ATTR_USER_SPECIFIC_CONTENT; attrib.Buffer.Addr = buffer; attrib.Buffer.Len = 512;
Value — the value of the formatting/styling attribute. If stored this way, the value must be a null-terminated ASCII string (as there is no other way to specify the length of the string).
Buffer — buffer holding the value of the formatting/styling attribute. The Addr member of this structure represents the memory address at which the value of the formatting/styling attribute begins while Len is its length. If stored this way the value does not have to be a null-terminated ASCII string (since the length of the string is explicitly specified using the Len member).
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.
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;