Index

PowerDoc Objects

Text Layout (Manual)

Overview

This objects holds parameters that provide precise control over manual text layout. As such, the Text Layout (Manual) object can be used to build the Text Design and Rich Text Design object.

Designated Rendering Function: NONE

Note 1: pdPosArrX_08, pdPosArrX_16, pdPosArrX_24 and pdPosArrX_32 cannot be used at the same time. pdPosArrX_32 takes precedence over pdPosArrX_24. pdPosArrX_24 takes precedence over pdPosArrX_16. Finally, pdPosArrX_16 takes precedence over pdPosArrX_08.

Note 2: pdPosArrY_08, pdPosArrY_16, pdPosArrY_24 and pdPosArrY_32 cannot be used at the same time. pdPosArrY_32 takes precedence over pdPosArrY_24. pdPosArrY_24 takes precedence over pdPosArrY_16. Finally, pdPosArrY_16 takes precedence over pdPosArrY_08.

None

Properties

pdHinting (1100)   PD_BYTE_UNSIGNED

Also appears in: Text Layout (Automatic)

Sets one of the hinting modes. The hinting mode tells the Typesetter how to interact with the pixel grid when rendering glyphs. See D-Type Standard Engine Manual for details.

Supported values:

0 = Engine Default A (same as 8)

1 = Engine Default B (same as 9)

2 = User Default A (same as 4)

3 = User Default B (same as 6)

4 = X On, Y On
Both X and Y edges are snapped to the pixel grid. As a result, both X and Y edges look reasonably sharp.

5 = X On, Y Off
Only X edges are snapped to the pixel grid. As a result, X edges look reasonably sharp, while Y edges look somewhat blurry.

6 = X Off, Y On
Only Y edges are snapped to the pixel grid. As a result, X edges look somewhat blurry, while Y edges look reasonably sharp.

7 = X Off, Y Off
Neither X nor Y edges are snapped to the pixel grid. As a result, both X and Y edges look somewhat blurry.

8 = Auto A
Same as 4 for standard font sizes, but disables hinting in the X and/or Y direction for very small and very big font sizes. This is done in order to improve speed when rendering using very small and very big font sizes. This is a useful and recommended mode since hinting is not really necessary at those sizes.

9 = Auto B
Same as 6 for standard font sizes, but disables hinting in the Y direction for very small and very big font sizes. This is done in order to improve speed when rendering using very small and very big font sizes. This is a useful and recommended mode since hinting is not really necessary at those sizes.

All the above values are inherited from D-Type Standard Engine. See D-Type Standard Engine Manual for more details.

pdPositioning (1053)   PD_BYTE_UNSIGNED

Also appears in: Text Layout (Automatic)

Sets one of the positioning modes. The positioning mode tells the Typesetter how to position glyphs. See D-Type Standard Engine Manual for details.

Supported values:

0 = Engine Default A (same as 8)

1 = Engine Default B (same as 9)

2 = User Default A (same as 4)

3 = User Default B (same as 5)

4 = Frac X, Frac Y
Both X and Y coordinates of origin points are placed at fractional positions. As a result, spacing between characters looks reasonably consistent in both the horizontal and vertical direction.

5 = Frac X, Int Y
X coordinates of origin points are placed at fractional positions, while Y coordinates are snapped to the closest whole pixel positions. As a result, spacing between characters looks reasonably consistent in horizontal direction and somewhat inconsistent in vertical direction.

6 = Int X, Frac Y
X coordinates of origin points are snapped to the closest whole pixel positions, while Y coordinates are placed at fractional positions. As a result, spacing between characters looks somewhat inconsistent in horizontal direction and reasonably consistent in vertical direction.

7 = Int X, Int Y
Both X and Y coordinates of origin points are snapped to the closest whole pixel positions. As a result, spacing between characters looks somewhat inconsistent in both the horizontal and vertical direction.

8 = Auto A
Same as 4 for standard font sizes, but disables fractional pixel positioning in the X and/or Y direction for very small and very big font sizes. This is done in order to improve bitmap cache efficiency when rendering using very small and very big font sizes. This is a useful and recommended mode since fractional pixel positioning is not really necessary at those sizes.

9 = Auto B
Same as 5 for standard font sizes, but disables fractional pixel positioning in the X direction for very small and very big font sizes. This is done in order to improve bitmap cache efficiency when rendering using very small and very big font sizes. This is a useful and recommended mode since fractional pixel positioning is not really necessary at those sizes.

The above values are inherited from D-Type Standard Engine. See D-Type Standard Engine Manual for more details.

When rendering Text Lines, Rich Text Lines, Text Areas and Rich Text Areas, the following values are also supported:

10 = Enhanced Frac X, Frac Y
This positioning mode is similar to mode 4 but designed to further enhance spacing between glyphs based on the context. This mode can noticeably improve glyph spacing when compared with mode 4 and is highly recommended.

11 = Enhanced Frac X, Int Y
This positioning mode is similar to mode 5 but designed to further enhance spacing between glyphs based on the context. This mode can noticeably improve glyph spacing when compared with mode 5 and is highly recommended.

12 = Enhanced Int X, Frac Y
This positioning mode is similar to mode 6 but designed to further enhance spacing between glyphs based on the context. This mode can significantly improve glyph spacing when compared with mode 6 and is highly recommended.

13 = Enhanced Int X, Int Y
This positioning mode is similar to mode 7 but designed to further enhance spacing between glyphs based on the context. This mode can significantly improve glyph spacing when compared with mode 7 and is highly recommended.

pdRelativeDirection (1074)   PD_BYTE_UNSIGNED

Also appears in: Text Layout (Automatic)

Text direction relative to the global text direction.

Sample values:

0 = Same as global text direction
1 = Opposite to global text direction
2 = Same as global text direction (nested, level 1)
3 = Opposite to global text direction (nested, level 1)
4 = Same as global text direction (nested, level 2)
5 = Opposite to global text direction (nested, level 2)
6 = Same as global text direction (nested, level 3)
7 = Opposite to global text direction (nested, level 3)

pdPosArrI (1102)   PD_ARR_BYTE_UNSIGNED

Instructions for pdPosArrX_32 and pdPosArrY_32 (variable length, 1 byte per instruction).

pdPosArrI is an array containing instructions that describe the corresponding pair of coordinates in the pdPosArrX_32 and pdPosArrY_32 arrays and provide some additional information about the letters (i.e. characters or glyphs). The length of the array should be the same as the number of letters. If the array is shorter, any missing instructions will assume the value 0. If the array is longer, any extra instructions will be ignored.

Each instruction is a combination of the following bit independent bit values:

Bit 0: If set (1), the corresponding letter starts a new text row. If not set (0), the letter is in the same (current) row. Visually, this bit has no impact on the text layout. However, its value is used to calculate and set the Row member of the DT_PD_FRAME structure when the text layout engine generates frames. This makes it possible to implement cursor movement in the vertical direction and not just horizontal.

Bit 1: If set (1), the corresponding value in the pdPosArrX_32 is an absolute X coordinate. If not set (0), the corresponding value represents a relative delta (i.e. horizontal move relative to the previous X coordinate).

Bit 2: If set (1), the corresponding value in the pdPosArrY_32 is an absolute Y coordinate. If not set (0), the corresponding value represents a relative delta (i.e. vertical move relative to the previous Y coordinate).

The remaining bits are reserved for future use and must be set to 0.

Based on the above, each element of the pdPosArrI array can represent one of the following 8 valid instructions:

0 (000) : Y-RELATIVE, X-RELATIVE, SAME ROW
1 (001) : Y-RELATIVE, X-RELATIVE, NEW ROW
2 (010) : Y-RELATIVE, X-ABSOLUTE, SAME ROW
3 (011) : Y-RELATIVE, X-ABSOLUTE, NEW ROW
4 (100) : Y-ABSOLUTE, X-RELATIVE, SAME ROW
5 (101) : Y-ABSOLUTE, X-RELATIVE, NEW ROW
6 (110) : Y-ABSOLUTE, X-ABSOLUTE, SAME ROW
7 (111) : Y-ABSOLUTE, X-ABSOLUTE, NEW ROW

Any other instructions are invalid.

Sample values:

0, 0, 0, 1, 0, 0, 0, 0, 7

Tip:

If all the elements of the pdPosArrI array are 0, the array can be omitted. Similarly, all trailing zero values can be omitted. For example, the array 0, 0, 0, 1, 0, 0, 0, 0, 7 will have the same effect as the array 0, 0, 0, 1, 0, 0, 0, 0, 7, 0, 0, 0, 0, 0, 0.

pdPosArrX_08 (1149)   PD_ARR_BYTE_SIGNED

Supported Compression Methods: 006

Also appears in: Grid

An array containing X coordinates for manual positioning (variable length, 1 byte per coordinate).

Same as pdPosArrX_32 but uses 1 byte per coordinate.

pdPosArrX_16 (1148)   PD_ARR_WORD_SIGNED

Supported Compression Methods: 004

Also appears in: Grid

An array containing X coordinates for manual positioning (variable length, 2 bytes per coordinate).

Same as pdPosArrX_32 but uses 2 bytes per coordinate.

pdPosArrX_24 (1147)   PD_ARR_TRIO_SIGNED

Supported Compression Methods: 002

Also appears in: Grid

An array containing X coordinates for manual positioning (variable length, 3 bytes per coordinate).

Same as pdPosArrX_32 but uses 3 bytes per coordinate.

pdPosArrX_32 (1103)   PD_ARR_LONG_SIGNED

Supported Compression Methods: 000

Also appears in: Grid

An array containing X coordinates for manual positioning (variable length, 4 bytes per coordinate).

When used in the context of the Text Layout (Manual) object, pdPosArrX_32 is an array containing X coordinates or relative deltas needed to manually position the corresponding letters (i.e. characters or glyphs). The length of the array should be the same as the number of letters. If the array is shorter, any missing coordinates will assume the value 0. If the array is longer, any extra coordinates will be ignored. All X coordinates and relative deltas are specified in 1/256 document units (i.e. they are document units multiplied by 256). This provides the extra precision needed for precise text layout. Whether a value is an absolute X coordinate or relative delta depends on the corresponding instruction in the pdPosArrI.

When used in the context of the Grid object, pdPosArrX_32 is an array containing X coordinates needed to manually position the vertical grid lines, relative to the grid's origin. The length of the array equals the number of vertical grid lines. All X coordinates are in document units. They must be non-negative and must not exceed the width of the Grid object.

Sample values:

0, 12800, 25600, -16000, 15360, 15360, 15360, 29360, 15360, 25600, 25600, 25600, 25600

pdPosArrY_08 (1152)   PD_ARR_BYTE_SIGNED

Supported Compression Methods: 006

Also appears in: Grid

An array containing Y coordinates for manual positioning (variable length, 1 byte per coordinate).

Same as pdPosArrY_32 but uses 1 byte per coordinate.

pdPosArrY_16 (1151)   PD_ARR_WORD_SIGNED

Supported Compression Methods: 004

Also appears in: Grid

An array containing Y coordinates for manual positioning (variable length, 2 bytes per coordinate).

Same as pdPosArrY_32 but uses 2 bytes per coordinate.

pdPosArrY_24 (1150)   PD_ARR_TRIO_SIGNED

Supported Compression Methods: 002

Also appears in: Grid

An array containing Y coordinates for manual positioning (variable length, 3 bytes per coordinate).

Same as pdPosArrY_32 but uses 3 bytes per coordinate.

pdPosArrY_32 (1104)   PD_ARR_LONG_SIGNED

Supported Compression Methods: 000

Also appears in: Grid

An array containing Y coordinates for manual positioning (variable length, 4 bytes per coordinate).

When used in the context of the Text Layout (Manual) object, pdPosArrY_32 is an array containing Y coordinates or relative deltas needed to manually position the corresponding letters (i.e. characters or glyphs). The length of the array should be the same as the number of letters. If the array is shorter, any missing coordinates will assume the value 0. If the array is longer, any extra coordinates will be ignored. All Y coordinates and relative deltas are specified in 1/256 document units (i.e. they are document units multiplied by 256). This provides the extra precision needed for precise text layout. Whether a value is an absolute Y coordinate or relative delta depends on the corresponding instruction in the pdPosArrI.

When used in the context of the Grid object, pdPosArrY_32 is an array containing Y coordinates needed to manually position the horizontal grid lines, relative to the grid's origin. The length of the array equals the number of horizontal grid lines. All Y coordinates are in document units. They must be non-negative and must not exceed the height of the Grid object.

Sample values:

0, 6400, -6400, 25600, 0, 0, 0, 0, 55600

Example

C/C++

DT_ID_SLONG obj[1];

obj[0] = pdObjAdd(pd, 0, "Text Layout - Manual");

/* Properties for object 0 */
pdPropAdd(pd, obj[0], pdPosArrI, "0, 0, 0, 1, 0, 0, 0, 0, 7", PD_ARR_BYTE_UNSIGNED);
pdPropAdd(pd, obj[0], pdPosArrX_32, "2000, 21800, 15600, -16000, 15360, 15360, 5360, 9360, 1360, 15600, 22600, 18600, 15600, 10000, 11000, 8000, 10000, 4100, 3000", PD_ARR_LONG_SIGNED);
pdPropAdd(pd, obj[0], pdPosArrY_32, "0, 6400, -6400, 30600, 0, 0, 0, 0, 55600, 0, -1000, -1000, -1000, -1000, -3000, -5000, -11000, -14000, -15000", PD_ARR_LONG_SIGNED);
pdPropAdd(pd, obj[0], pdHinting, "1", PD_BYTE_UNSIGNED);
pdPropAdd(pd, obj[0], pdPositioning, "1", PD_BYTE_UNSIGNED);

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 Layout - Manual");

/* Object Properties */

obj_0 + p(pdPosArrI, "0, 0, 0, 1, 0, 0, 0, 0, 7");
obj_0 + p(pdPosArrX_32, "2000, 21800, 15600, -16000, 15360, 15360, 5360, 9360, 1360, 15600, 22600, 18600, 15600, 10000, 11000, 8000, 10000, 4100, 3000");
obj_0 + p(pdPosArrY_32, "0, 6400, -6400, 30600, 0, 0, 0, 0, 55600, 0, -1000, -1000, -1000, -1000, -3000, -5000, -11000, -14000, -15000");
obj_0 + i(pdHinting, 1);
obj_0 + i(pdPositioning, 1);
 

Index