Index

PowerDoc Objects

Text Layout (Automatic)

Overview

This objects holds parameters that provide precise control over automatic text layout. As such, the Automatic Text Layout object can be used to build the following text objects: Text Line, Text Arc, Text Path, Text Area, Rich Text Line, Rich Text Arc, Rich Text Path, Rich Text Area.

Designated Rendering Function: NONE

None

Properties

pdAlign (1019)   PD_BYTE_UNSIGNED

Alignment of a text line.

Supported values:

0 = Left: The text line is aligned left.

1 = Center: The text line is centered.

2 = Right: The text line is aligned right.

3 = Justify Type A / Left: Justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then align left.

4 = Justify Type B / Left: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then align left.

5 = Justify Type A / Center: Justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then center.

6 = Justify Type B / Center: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then center.

7 = Justify Type A / Right: Justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then align right.

8 = Justify Type B / Right: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then align right.

9 = Justify Type B / Justify Type A / Left: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then align left.

10 = Justify Type B / Justify Type A / Center: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then center.

11 = Justify Type B / Justify Type A / Right: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then align right.

pdAlignEnd (1062)   PD_BYTE_UNSIGNED

Alignment of the last text line in a paragraph.

Supported values:

0 = Left: The text line is aligned left.

1 = Center: The text line is centered.

2 = Right: The text line is aligned right.

3 = Justify Type A / Left: Justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then align left.

4 = Justify Type B / Left: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then align left.

5 = Justify Type A / Center: Justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then center.

6 = Justify Type B / Center: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then center.

7 = Justify Type A / Right: Justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then align right.

8 = Justify Type B / Right: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then align right.

9 = Justify Type B / Justify Type A / Left: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then align left.

10 = Justify Type B / Justify Type A / Center: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then center.

11 = Justify Type B / Justify Type A / Right: Justify the text line by inserting extra spacing only after the space characters. If this is not possible (e.g. the text line does not have any space characters), then justify the text line by inserting extra spacing after each character. If this is not possible (e.g. the text line contains a single character), then align right.

pdKerning (1020)   PD_BYTE_UNSIGNED

Text kerning.

Supported values:

0 = Disable Kerning
1 = Enable Standard Kerning

pdSpacingLetter (1021)   PD_WORD_SIGNED

Amount of spacing to be added after a character or glyph, in document units. Both positive and negative values are valid.

Sample values:

10 = character spacing of 10 document units
40 = character spacing of 40 document units
-10 = character spacing of -10 document units

pdSpacingRow (1022)   PD_LONG_SIGNED

Amount of spacing to be added after a text line, in document units.

Sample values:

10 = spacing of 10 document units
15 = spacing of 15 document units
-5 = spacing of -5 document units

pdSpacingBaseline (1112)   PD_LONG_SIGNED

Amount of spacing from the previous baseline, in document units. This provides a means of manually setting the line height in text areas and rich text areas. This value must be non-negative. The value -1 is special and indicates that the line height is to be calculated automatically.

Sample values:

48 = spacing of 48 document units
16 = spacing of 16 document units
-1 = calculate the baseline spacing automatically

pdPositioning (1053)   PD_BYTE_UNSIGNED

Also appears in: Text Layout (Manual)

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.

pdHinting (1100)   PD_BYTE_UNSIGNED

Also appears in: Text Layout (Manual)

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.

pdDx (1027)   PD_LONG_SIGNED

Also appears in: Group Member

Horizontal offset in document units.

pdDy (1028)   PD_LONG_SIGNED

Also appears in: Group Member

Vertical offset in document units.

pdSpacingFont (1090)   PD_WORD_SIGNED

Amount of spacing to be added after a character or glyph, in font units. Both positive and negative values are valid.

pdRelativeDirection (1074)   PD_BYTE_UNSIGNED

Also appears in: Text Layout (Manual)

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)

pdRelativeOrientation (1105)   PD_LONG_UNSIGNED

Relative text orientation (Portrait or Landscape) and baseline, for horizontal and vertical text layout.

This is a 32-bit value that consists of the following 4 bytes:

BYTE 3 - Reserved for future use. All bits in this byte must be set to 0.

BYTE 2 - Relative text orientation and baseline for vertical text layout (text in columns). The bits in this byte are interpreted as follows:

Bit 7: Relative text orientation - If unset (0), the orientation is Portrait. If set (1), the orientation is Landscape. Portrait means that the glyph's x-axis (in font design space) is parallel with the baseline. Landscape means that the glyph's x-axis (in font design space) is perpendicular to the baseline.
Bit 6: Reserved for future use - Must be set to 0.
Bit 5: Reserved for future use - Must be set to 0.
Bit 4: Reserved for future use - Must be set to 0.
Bit 3: Reserved for future use - Must be set to 0.
Bit 2: Reserved for future use - Must be set to 0.
Bit 1 & 0: Baseline - These two bits represent a single 2-bit value which, depending on the relative text orientation, identifies one of the 4 available baselines.

In Portrait Mode (when Bit 7 is unset), the available baselines are:

00 (0) - Default - coincides with glyph's zero y coordinate (in font design space).
01 (1) - Shifted (Middle) - above the Default baseline, shifted by an amount that equals half the distance between the font's ascend and descend.
10 (2) - Top - coincides with glyph's ascend (in font design space).
11 (3) - Bottom - coincides with glyph's descend (in font design space).

In Landscape Mode (when Bit 7 is set), the available baselines are:

00 (0) - Default - coincides with glyph's mid-x point (in font design space). The definition of the mid-x point depends on the currently active algorithm for calculating the glyph mid-x points in vertical text layout. If the active algorithm is "Glyph Width" the mid-x point is half way between the glyph's minimum and maximum x coordinate. If the active algorithm is "Advance Width" the mid-x point is half way between the glyph's left and right side-bearing. Note that the left side-bearing coincides with the x coordinate 0 while the right side-bearing coincides with the glyph's advance width.
01 (1) - Shifted (Left) - to the left of the Default baseline, shifted by an amount that equals half the font's em square.
10 (2) - Center - same as the Default baseline.
11 (3) - Right - to the right of the Default baseline, shifted by an amount that equals half the font's em square.

BYTE 1 - Relative text orientation and baseline for horizontal text layout (text in rows). The bits in this byte are interpreted precisely the same as in BYTE 2. The only difference is that they control the relative text orientation and baseline in horizontal text layout (e.g. when text is laid out in rows), unlike the bits in BYTE 2 which control the relative text orientation and baseline in vertical text layout (e.g. when text is laid out in columns).

BYTE 0 - Flags and presets. This byte contains the following bits:

Bit 7: Advanced Configuration Mode - If unset (0), Advanced Configuration Mode is off. If set (1), Advanced Configuration Mode is on. In Advanced Configuration Mode, bits in BYTE 1 and 2 are respected and presets are ignored. When Advanced Configuration Mode is off, bits in BYTE 1 and 2 are ignored and instead presets are used. See below the list of available presets.
Bit 6: Reserved for future use - Must be set to 0.
Bit 5: Reserved for future use - Must be set to 0.
Bit 4: Flip Mode - If unset (0), Flip Mode is off. If set (1), Flip Mode is on. Flip Mode simply rotates glyphs 180 degrees. This bit is always respected i.e. regardless of whether Advanced Configuration Mode is on or off.
Bit 3, 2, 1 & 0: Presets - These four bits represent a single 4-bit value, which identifies one of the 16 available presets.

0000 (0) - Hor. Layout: Portrait + Default Baseline / Ver. Layout: Portrait + Default Baseline
0001 (1) - Hor. Layout: Landscape + Default Baseline / Ver. Layout: Landscape + Default Baseline
0010 (2) - Hor. Layout: Portrait + Default Baseline / Ver. Layout: Landscape + Default Baseline
0011 (3) - Hor. Layout: Landscape + Default Baseline / Ver. Layout: Portrait + Default Baseline
0100 (4) - Hor. Layout: Portrait + Shifted Baseline / Ver. Layout: Portrait + Shifted Baseline
0101 (5) - Hor. Layout: Landscape + Shifted Baseline / Ver. Layout: Landscape + Shifted Baseline
0110 (6) - Hor. Layout: Portrait + Shifted Baseline / Ver. Layout: Landscape + Shifted Baseline
0111 (7) - Hor. Layout: Landscape + Shifted Baseline / Ver. Layout: Portrait + Shifted Baseline
1000 (8) - Hor. Layout: Portrait + Default Baseline / Ver. Layout: Portrait + Shifted Baseline
1001 (9) - Hor. Layout: Landscape + Default Baseline / Ver. Layout: Landscape + Shifted Baseline
1010 (10) - Hor. Layout: Portrait + Default Baseline / Ver. Layout: Landscape + Shifted Baseline
1011 (11) - Hor. Layout: Landscape + Default Baseline / Ver. Layout: Portrait + Shifted Baseline
1100 (12) - Hor. Layout: Portrait + Shifted Baseline / Ver. Layout: Portrait + Default Baseline
1101 (13) - Hor. Layout: Landscape + Shifted Baseline / Ver. Layout: Landscape + Default Baseline
1110 (14) - Hor. Layout: Portrait + Shifted Baseline / Ver. Layout: Landscape + Default Baseline
1111 (15) - Hor. Layout: Landscape + Shifted Baseline / Ver. Layout: Portrait + Default Baseline

Value 0010 (2) is particularly useful for Unicode scripts that are typically written in portrait mode when the text is in horizontal layout (rows) and landscape mode when the text is in vertical layout (columns). Such scripts primarily include CJK scripts (Chinese/Japanese/Korean) and sometimes Latin or Cyrillic.

Value 1000 (8) is particularly useful for Unicode scripts that are always written in portrait mode, regardless of whether the text is in horizontal layout (rows) or vertical layout (columns). Such scripts include Arabic, Indic or any scripts that have horizontally joined characters. Value 8 also works well for Latin or Cyrillic scripts and can be applied to mirrored Unicode characters such as the parenthesis, square and curly brackets etc.

Sample values:

"0" = Preset #0: Portrait orientation and Default Baseline with horizontal layout; Portrait orientation and Default Baseline with vertical layout.

"6" = Preset #6: Portrait orientation and Shifted Baseline with horizontal layout; Landscape orientation and Shifted Baseline with vertical layout.

"8" = Preset #8: Portrait orientation and Default Baseline with horizontal layout; Portrait orientation and Shifted Baseline with vertical layout.

"18" = Flip Mode & Preset #2: Glyphs are rotated 180 degrees; Portrait orientation and Default Baseline with horizontal layout; Landscape orientation and Default Baseline with vertical layout.

"22" = Flip Mode & Preset #6: Glyphs are rotated 180 degrees; Portrait orientation and Shifted Baseline with horizontal layout; Landscape orientation and Shifted Baseline with vertical layout.

"896" = Advanced Configuration: Portrait orientation and Bottom Baseline with horizontal layout; Portrait orientation and Default Baseline with vertical layout.

"912" = Flip Mode & Advanced Configuration: Glyphs are rotated 180 degrees; Portrait orientation and Bottom Baseline with horizontal layout; Portrait orientation and Default Baseline with vertical layout.

"33664" = Advanced Configuration: Landscape orientation and Right Baseline with horizontal layout; Portrait orientation and Default Baseline with vertical layout.

"33680" = Flip Mode & Advanced Configuration: Glyphs are rotated 180 degrees; Landscape orientation and Right Baseline with horizontal layout; Portrait orientation and Default Baseline with vertical layout.

pdSpacingFactor (1115)   PD_WORD_SIGNED

Line Height Multiple, multiplied by 1024.

Sample values:

512 = 0.5
1024 = 1.0
1536 = 1.5
2048 = 2.0
2560 = 2.5

pdVAlignRow (1126)   PD_BYTE_UNSIGNED

Vertical alignment of glyphs/characters within the current text row.

Supported values:

0 = Baseline - character is vertically aligned with the baseline (the default behavior for most programs)
1 = Top - character's ascender is vertically aligned with the top edge of the current text row
2 = Middle - character's mid y point (a point that is half way between the ascender and descender) is vertically aligned with the mid y point of the current text row
3 = Bottom - character's descender is vertically aligned with the bottom edge of the current text row

Example

C/C++

DT_ID_SLONG obj[1];

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

/* Properties for object 0 */
pdPropAdd(pd, obj[0], pdSpacingRow, "5", PD_WORD_SIGNED);
pdPropAdd(pd, obj[0], pdSpacingLetter, "10", PD_WORD_SIGNED);
pdPropAdd(pd, obj[0], pdKerning, "1", PD_BYTE_UNSIGNED);
pdPropAdd(pd, obj[0], pdAlign, "3", PD_BYTE_UNSIGNED);
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 - Automatic");

/* Object Properties */

obj_0 + i(pdSpacingRow, 5);
obj_0 + i(pdSpacingLetter, 10);
obj_0 + i(pdKerning, 1);
obj_0 + i(pdAlign, 3);
obj_0 + i(pdHinting, 1);
obj_0 + i(pdPositioning, 1);
 

Index