Index

PowerDoc Objects

Rich Text Path

Overview

This objects represents a rich text path. In Power Engine API, a rich text path is an array of text fragments formatted according to the specified parameters and drawn along the edge of a user-defined polygon or shape. Functionally, the Rich Text Path object is similar to the Text Path object but is more complex. This is because a typical rich text path usually consists of many text fragments, while each fragment is formatted using a different set of typographic and layout attributes.

Designated Rendering Function: pdDrawRichTextPath (29)

Note 1: pdPolyArrX_08, pdPolyArrX_16, pdPolyArrX_24 and pdPolyArrX_32 cannot be used at the same time. pdPolyArrX_32 takes precedence over pdPolyArrX_24. pdPolyArrX_24 takes precedence over pdPolyArrX_16. Finally, pdPolyArrX_16 takes precedence over pdPolyArrX_08.

Note 2: pdPolyArrY_08, pdPolyArrY_16, pdPolyArrY_24 and pdPolyArrY_32 cannot be used at the same time. pdPolyArrY_32 takes precedence over pdPolyArrY_24. pdPolyArrY_24 takes precedence over pdPolyArrY_16. Finally, pdPolyArrY_16 takes precedence over pdPolyArrY_08.

pdTextFragmentPtr (1038)

Also appears in: Text Fragment, Rich Text Line, Rich Text Arc, Rich Text Area, Rich Text Design, Rich Text Box, Rich Button, Rich List Box

Link to the Text Fragment object.

This link in used to establish a link to the next text fragment. This can be the first text fragment or the fragment that follows the current one.

pdBaselinePtr (1113)

Also appears in: Text Extras, Text Line, Text Arc, Text Area, Rich Text Line, Rich Text Arc, Rich Text Area, Text Path

Link to the Baseline object.

This link supplies parameters necessary to render the baselines of text rows.

Properties

pdGlobalDirection (1075)   PD_BYTE_UNSIGNED

Also appears in: Text Line, Text Arc, Text Area, Rich Text Line, Rich Text Arc, Rich Text Area, Text Path

Global text direction and bidirectional text display method.

Supported values:

A) Horizontal Layout (Text in Rows) and Bidirectional Reordering:

0 = Left-to-Right, Top-to-Bottom (e.g. Latin, Cyrillic, Greek)
1 = Right-to-Left, Top-to-Bottom (e.g. Arabic, Hebrew)
2 = Left-to-Right, Bottom-to-Top
3 = Right-to-Left, Bottom-to-Top
4 = Same as 0 but swap Portrait & Landscape
5 = Same as 1 but swap Portrait & Landscape
6 = Same as 2 but swap Portrait & Landscape
7 = Same as 3 but swap Portrait & Landscape

B) Vertical Layout (Text in Columns) and Bidirectional Reordering:

8 = Top-to-Bottom, Right-to-Left (e.g. Vertical Chinese)
9 = Bottom-to-Top, Right-to-Left
10 = Top-to-Bottom, Left-to-Right
11 = Bottom-to-Top, Left-to-Right
12 = Same as 8 but swap Portrait & Landscape
13 = Same as 9 but swap Portrait & Landscape
14 = Same as 10 but swap Portrait & Landscape
15 = Same as 11 but swap Portrait & Landscape

C) Horizontal Layout (Text in Rows) and Bidirectional Rotation:

16 = Left-to-Right, Top-to-Bottom (e.g. Latin, Cyrillic, Greek)
17 = Right-to-Left, Top-to-Bottom (e.g. Arabic, Hebrew)
18 = Left-to-Right, Bottom-to-Top
19 = Right-to-Left, Bottom-to-Top
20 = Same as 16 but swap Portrait & Landscape
21 = Same as 17 but swap Portrait & Landscape
22 = Same as 18 but swap Portrait & Landscape
23 = Same as 19 but swap Portrait & Landscape

D) Vertical Layout (Text in Columns) and Bidirectional Rotation:

24 = Top-to-Bottom, Right-to-Left (e.g. Vertical Chinese)
25 = Bottom-to-Top, Right-to-Left
26 = Top-to-Bottom, Left-to-Right
27 = Bottom-to-Top, Left-to-Right
28 = Same as 24 but swap Portrait & Landscape
29 = Same as 25 but swap Portrait & Landscape
30 = Same as 26 but swap Portrait & Landscape
31 = Same as 27 but swap Portrait & Landscape

Notes:

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.

txLockStatus (2005)   PD_BYTE_UNSIGNED

Also appears in: Text Line, Text Arc, Text Area, Rich Text Line, Rich Text Arc, Rich Text Area, Text Path

A flag that indicates whether and how the text is locked for user interactions. This flag is respected by D-Type Text Engine.

Supported values:

0 = Text is not locked (all user interactions are enabled)

1 = Text is completely locked (all user interactions are disabled)

2 = Text is locked for both editing and formatting/styling (but a user can still move the cursor and make text selections)

3 = Text is locked for editing but not for formatting/styling (and a user can still move the cursor and make text selections)

4 = Text is locked for formatting/styling but not for editing (and a user can still move the cursor and make text selections)

txMiscFlags (2006)   PD_BYTE_UNSIGNED

Also appears in: Text Line, Text Arc, Text Area, Rich Text Line, Rich Text Arc, Rich Text Area, Text Path

Miscellaneous text handling flags respected by D-Type Text Engine.

Supported values:

Bit 0: If this bit is set, text selection and cursor movement operations will be processed normally by D-Type Text Engine but will not be shown to the user. It will appear as if the cursor and text selections are completely transparent.

Bits 1 - 7: Reserved for future use.

pdGlyphStart (1076)   PD_ARR_LONG_SIGNED

Also appears in: Text Line, Text Arc, Text Area, Rich Text Line, Rich Text Arc, Rich Text Area, Text Path

Start glyph position within the first text fragment, i.e. the index of the glyph in the first text fragment from which the text layout and display starts. This value cannot be negative and must be less than the length of the first text fragment.

This property is useful when building text flows (i.e. when text fragments span more than one text area). In most other cases, this property should be omitted or its value should be set to 0.

pdPolyArrI (1041)   PD_ARR_BYTE_UNSIGNED

Supported Compression Methods: 012, 015

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

Instructions for PolyArrX and PolyArrY (variable length, 1 byte per instruction).

pdPolyArrI is an array containing instructions that describe the corresponding pair of coordinates in the pdPolyArrX_... and pdPolyArrY_... arrays. Possible values for pdPolyArrI are:

A. Standard segment construction instructions:

D-Type Grayscale Rasterizers:

16 = New closed contour
17 = New open contour
20 = Line
24 = Bezier curve. Must be followed by n and 0 (see below).
25 = Quadratic B-Spline curve. Must be followed by n (see below).

D-Type Direct Color RGBA Rasterizers and D-Type Shading Rasterizers extend these instructions:

16 = New closed RGBT contour (the next 4-byte RGBT color value is read from pdPolyArrC)
17 = New open RGBT contour (the next 4-byte RGBT color value is read from pdPolyArrC)
20 = Line (the next 4-byte RGBT color value is unchanged).
24 = Bezier curve (the next 4-byte RGBT color value is unchanged). Must be followed by n and 0 (see below).
25 = Quadratic B-Spline curve (the next 4-byte RGBT color value is unchanged). Must be followed by n (see below).
40 = RGBT Line (the next 4-byte RGBT color value is read from pdPolyArrC)
44 = RGBT Bezier curve (the next 4-byte RGBT color value is read from pdPolyArrC). Must be followed by n and 0 (see below).
45 = RGBT Quadratic B-Spline curve (the next 4-byte RGBT color value is read from pdPolyArrC). Must be followed by n (see below).

B. Instructions that can only follow 24 or 25:

n = A positive number or zero. Used only when the preceding instruction is 24 (Bezier curve) or 25 (Quadratic B-Spline curve). A positive number represents the suggested number of line segments that the curve will be approximated with. Zero means that the rendering engine should automatically calculate the optimum number of line segments when rendering the curve.

0 = Reserved. Used only when the first instruction in a segment is 24.

C. Special "one byte does it all" instructions:

254 = Open Polyline/Polygon - All coordinates in the corresponding pdPolyArrX_... and pdPolyArrY_... arrays are interpreted as Polyline/Polygon vertices connected using straight line segments. There can be no curved segments in this case. As such, no other instructions in pdPolyArrI are needed. Polylines constructed using this method are not automatically closed.

255 = Closed Polyline/Polygon - All coordinates in the corresponding pdPolyArrX_... and pdPolyArrY_... arrays are interpreted as Polyline/Polygon vertices connected using straight line segments. There can be no curved segments in this case. As such, no other instructions in pdPolyArrI are needed. Polylines constructed using this method are automatically closed.

The instruction 254 and 255 are special. Only one of them can be used per single Polyline/Polygon. When specified, this instruction must be the only instruction in the pdPolyArrI array. In other words, pdPolyArrI must be a single element array, containing only the instruction 254 or 255.

Sample values:

"16, 20, 20, 20"
"16, 20, 25, 0, 20"
"16, 20, 20, 24, 0, 0, 20, 25, 10, 20, 20"
"254"
"255"

pdPolyArrX_32 (1042)   PD_ARR_LONG_SIGNED

Supported Compression Methods: 000

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

An array containing X coordinates of segment's control points (variable length, 4 bytes per coordinate).

Sample values:

"0, 400, 300, 200"
"100, 200, -100, -200, -250"
"50, 100, 120, 80, 120, 95, 130, 40, 80, 100, 190"

pdPolyArrX_24 (1140)   PD_ARR_TRIO_SIGNED

Supported Compression Methods: 002

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

An array containing X coordinates of segment's control points (variable length, 3 bytes per coordinate).

Sample values:

"0, 400, 300, 200"
"100, 200, -100, -200, -250"
"50, 100, 120, 80, 120, 95, 130, 40, 80, 100, 190"

pdPolyArrX_16 (1141)   PD_ARR_WORD_SIGNED

Supported Compression Methods: 004

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

An array containing X coordinates of segment's control points (variable length, 2 bytes per coordinate).

Sample values:

"0, 400, 300, 200"
"100, 200, -100, -200, -250"
"50, 100, 120, 80, 120, 95, 130, 40, 80, 100, 190"

pdPolyArrX_08 (1142)   PD_ARR_BYTE_SIGNED

Supported Compression Methods: 006

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

An array containing X coordinates of segment's control points (variable length, 1 byte per coordinate).

Sample values:

"0, 40, 30, 20"
"10, 20, -10, -20, -25"
"5, 10, 12, 8, 12, 9, 13, 4, 8, 10, 19"

pdPolyArrY_32 (1043)   PD_ARR_LONG_SIGNED

Supported Compression Methods: 000

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

An array containing Y coordinates of segment's control points (variable length, 4 bytes per coordinate).

Sample values:

"0, 100, 350, 200"
"200, 200, -200, -200, 100"
"-50, -90, -20, -80, -120, 10, 30, 20, -20, 10, 50"

pdPolyArrY_24 (1143)   PD_ARR_TRIO_SIGNED

Supported Compression Methods: 002

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

An array containing Y coordinates of segment's control points (variable length, 3 bytes per coordinate).

Sample values:

"0, 100, 350, 200"
"200, 200, -200, -200, 100"
"-50, -90, -20, -80, -120, 10, 30, 20, -20, 10, 50"

pdPolyArrY_16 (1144)   PD_ARR_WORD_SIGNED

Supported Compression Methods: 004

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

An array containing Y coordinates of segment's control points (variable length, 2 bytes per coordinate).

Sample values:

"0, 100, 350, 200"
"200, 200, -200, -200, 100"
"-50, -90, -20, -80, -120, 10, 30, 20, -20, 10, 50"

pdPolyArrY_08 (1145)   PD_ARR_BYTE_SIGNED

Supported Compression Methods: 006

Also appears in: Custom Shape or Polygon, Polyline (also Bezier and B-Spline curve), Text Path

An array containing Y coordinates of segment's control points (variable length, 1 byte per coordinate).

Sample values:

"0, 10, 35, 20"
"20, 20, -20, -20, 10"
"-5, -9, -2, -8, -12, 1, 3, 2, -2, 1, 5"

pdWrapType (1066)   PD_BYTE_UNSIGNED

Also appears in: Text Area, Rich Text Area, Text Path

Text wrap method.

Supported values:

0 = Soft Wrap Enabled
1 = Soft Wrap Disabled - trim text after any character
2 = Soft Wrap Disabled - trim text only after space or some other breakable character (e.g. CJK) but not after a hyphen
3 = Soft Wrap Disabled - trim text only after space or some other breakable character (e.g. CJK) or after a hyphen
4 = Soft Wrap Disabled - trim text after any character and add a horizontal ellipsis

Example

C/C++

DT_ID_SLONG obj[10];

obj[0] = pdObjAdd(pd, 0, "Text Fragment Outline Style");
obj[1] = pdObjAdd(pd, 0, "Text Fragment Body Style");
obj[2] = pdObjAdd(pd, 0, "Text Fragment Shadow Style");
obj[3] = pdObjAdd(pd, 0, "Text Fragment Outline");
obj[4] = pdObjAdd(pd, 0, "Text Fragment Shadow");
obj[5] = pdObjAdd(pd, 0, "Text Fragment Typography");
obj[6] = pdObjAdd(pd, 0, "Text Fragment Layout");
obj[7] = pdObjAdd(pd, 0, "Text Fragment Ruler");
obj[8] = pdObjAdd(pd, 0, "Text Fragment");
obj[9] = pdObjAdd(pd, 0, "RichTextPath");

/* Properties for object 0 */
pdPropAdd(pd, obj[0], pdRGBT, "50641400", PD_HEX);

/* Properties for object 1 */
pdPropAdd(pd, obj[1], pdRGBT, "B4961400", PD_HEX);

/* Properties for object 2 */
pdPropAdd(pd, obj[2], pdRGBT, "80808078", PD_HEX);
pdPropAdd(pd, obj[2], pdEP, "030A", PD_HEX);

/* Properties for object 3 */
pdLinkAdd(pd, obj[3], pdStylePtr, obj[0]);
pdPropAdd(pd, obj[3], pdLineThickness, "240", PD_WORD_SIGNED);

/* Properties for object 4 */
pdLinkAdd(pd, obj[4], pdStylePtr, obj[2]);
pdPropAdd(pd, obj[4], pdShadowDx, "5", PD_WORD_SIGNED);
pdPropAdd(pd, obj[4], pdShadowDy, "5", PD_WORD_SIGNED);

/* Properties for object 5 */
pdLinkAdd(pd, obj[5], pdBodyPtr, obj[1]);
pdLinkAdd(pd, obj[5], pdShadowPtr, obj[4]);
pdLinkAdd(pd, obj[5], pdOutlinePtr, obj[3]);
pdPropAdd(pd, obj[5], pdFontIndex, "0", PD_WORD_SIGNED);
pdPropAdd(pd, obj[5], pdFontDw, "70", PD_WORD_SIGNED);
pdPropAdd(pd, obj[5], pdFontDh, "70", PD_WORD_SIGNED);

/* Properties for object 6 */
pdPropAdd(pd, obj[6], pdSpacingRow, "10", PD_WORD_SIGNED);
pdPropAdd(pd, obj[6], pdSpacingLetter, "5", PD_WORD_SIGNED);
pdPropAdd(pd, obj[6], pdKerning, "1", PD_BYTE_UNSIGNED);
pdPropAdd(pd, obj[6], pdAlign, "3", PD_BYTE_UNSIGNED);

/* Properties for object 7 */
pdPropAdd(pd, obj[7], pdTabStopPositions, "40, 80, 150, 220", PD_ARR_BYTE_UNSIGNED);
pdPropAdd(pd, obj[7], pdTabStopFlags, "1, 0, 0, 2", PD_ARR_BYTE_UNSIGNED);

/* Properties for object 8 */
pdLinkAdd(pd, obj[8], pdTypographyPtr, obj[5]);
pdLinkAdd(pd, obj[8], pdTextLayoutPtr, obj[6]);
pdLinkAdd(pd, obj[8], pdTextRulerHorPtr, obj[7]);
pdPropAdd(pd, obj[8], pdTextString_08, "This is a text fragment", PD_ASC);

/* Properties for object 9 */
pdLinkAdd(pd, obj[9], pdTextFragmentPtr, obj[8]);
pdPropAdd(pd, obj[9], pdPolyArrI, "17, 20, 25, 20, 20", PD_ARR_BYTE_UNSIGNED);
pdPropAdd(pd, obj[9], pdPolyArrX_32, "0, 400, 300, 200, -60", PD_ARR_LONG_SIGNED);
pdPropAdd(pd, obj[9], pdPolyArrY_32, "0, 100, 350, 200, 100", PD_ARR_LONG_SIGNED);


/* Image placement */
pdImgAdd(pd, obj[9], 0, 100, 100, 0, 0, 0, pdDrawRichTextPath, DV_NULL);

INTEGRAL DSL

/* Lambda shortcuts */

local o = @(label = "") CDTObj(::my.doc, label); /* to make object */
local p = @(id, str, len = PD_DEFAULT) CDTProp(id, str, len); /* to add property - general */
local s = @(id, str) CDTPropStr(id, str); /* to add property - string */
local i = @(id, num) CDTPropInt(id, num); /* to add property - integer */
local l = @(id, obj) CDTLink(id, obj); /* to add link */

/* Objects */

local obj_0 = o("Text Fragment Outline Style");
local obj_1 = o("Text Fragment Body Style");
local obj_2 = o("Text Fragment Shadow Style");
local obj_3 = o("Text Fragment Outline");
local obj_4 = o("Text Fragment Shadow");
local obj_5 = o("Text Fragment Typography");
local obj_6 = o("Text Fragment Layout");
local obj_7 = o("Text Fragment Ruler");
local obj_8 = o("Text Fragment");
local obj_9 = o("RichTextPath");

/* Object Properties */

obj_0 + s(pdRGBT, "50641400");

obj_1 + s(pdRGBT, "B4961400");

obj_2 + s(pdRGBT, "80808078");
obj_2 + s(pdEP, "030A");

obj_3 + l(pdStylePtr, obj_0);
obj_3 + i(pdLineThickness, 240);

obj_4 + l(pdStylePtr, obj_2);
obj_4 + i(pdShadowDx, 5);
obj_4 + i(pdShadowDy, 5);

obj_5 + l(pdBodyPtr, obj_1);
obj_5 + l(pdShadowPtr, obj_4);
obj_5 + l(pdOutlinePtr, obj_3);
obj_5 + i(pdFontIndex, 0);
obj_5 + i(pdFontDw, 70);
obj_5 + i(pdFontDh, 70);

obj_6 + i(pdSpacingRow, 10);
obj_6 + i(pdSpacingLetter, 5);
obj_6 + i(pdKerning, 1);
obj_6 + i(pdAlign, 3);

obj_7 + p(pdTabStopPositions, "40, 80, 150, 220");
obj_7 + p(pdTabStopFlags, "1, 0, 0, 2");

obj_8 + l(pdTypographyPtr, obj_5);
obj_8 + l(pdTextLayoutPtr, obj_6);
obj_8 + l(pdTextRulerHorPtr, obj_7);
obj_8 + s(pdTextString_08, "This is a text fragment");

obj_9 + l(pdTextFragmentPtr, obj_8);
obj_9 + p(pdPolyArrI, "17, 20, 25, 20, 20");
obj_9 + p(pdPolyArrX_32, "0, 400, 300, 200, -60");
obj_9 + p(pdPolyArrY_32, "0, 100, 350, 200, 100");

/* Image Pinning */

obj_9.Pin(0, 100, 100, pdDrawRichTextPath);
 

Index