Index

C/C++ Functions

pdDocSetNumericValue

void pdDocSetNumericValue(DT_PDDOC power_doc, DT_ID_SWORD numeric_id, DT_SLONG numeric_value)

Short Description: Set document's numeric value

This function sets the value of various numeric parameters defined in a Power Engine document. This can be used to configure certain Power Engine document features and algorithms.

Parameters

ParameterDescription

power_doc

Handle of the associated Power Engine document.

numeric_id

Identifies the numeric parameter. Can be one of the following:

  • 0 (PD_NVAL_THICKNESS_INVERT_LINE) — Line thickness of the cursor, in pixels.

  • 1 (PD_NVAL_THICKNESS_IMG_BOUNDARY) — Line thickness of image boundaries, in pixels.

  • 2 (PD_NVAL_THICKNESS_IMG_ORIGIN_VISIBLE) — Line thickness of visible image origins, in pixels.

  • 3 (PD_NVAL_THICKNESS_IMG_ORIGIN_HIDDEN) — Line thickness of hidden image origins, in pixels.

  • 4 (PD_NVAL_COLOR_IMG_ORIGIN_VISIBLE) — RGBT color value of visible image origins (expressed as a 32-bit integer calculated as numeric_value = (R << 24) | (G << 16) | (B << 8) | T).

  • 5 (PD_NVAL_COLOR_IMG_ORIGIN_HIDDEN) — RGBT color value of hidden image origins (expressed as a 32-bit integer calculated as numeric_value = (R << 24) | (G << 16) | (B << 8) | T).

  • 6 (PD_NVAL_COLOR_IMG_BOUNDARY) — RGBT color value of image boundaries (expressed as a 32-bit integer calculated as numeric_value = (R << 24) | (G << 16) | (B << 8) | T).

  • 7 (PD_NVAL_COLOR_IMG_ORIGIN_FILL) — RGBT color value of image origin interiors (expressed as a 32-bit integer calculated as numeric_value = (R << 24) | (G << 16) | (B << 8) | T).

  • 8 (PD_NVAL_TEXT_BLANKS_SIZE) — Internal use only.

  • 9 (PD_NVAL_TEXT_PRINT_MODE) — Internal use only.

  • 10 (PD_NVAL_FONT_DISPLAY_LAYERS_GLYPHS) — Font display mode for color glyph layers (0=don't show color layers, 1=show color layers).

  • 11 (PD_NVAL_FONT_DISPLAY_BIMAGE_GLYPHS) — Font display mode for color PNG/JPEG bitmap glyph images (0=don't show bitmaps, 1=show bitmaps: low quality, 2=show bitmaps: high quality, 3=show bitmaps: very high quality, 4=show bitmaps: very high quality, more blur).

  • 12 (PD_NVAL_FONT_DISPLAY_SVGDOC_GLYPHS) — Font display mode for SVG glyphs (0=don't show SVG glyphs, 1=show SVG glyphs).

  • 13 (PD_NVAL_SELECT_EXTENSION) — Specifies how frames should be modified (usually extended but sometimes contracted) at the beginning and end of each text line, assuming the text is part of a Text Area or Rich Text Area object. This has a direct impact on text selection and hit testing behavior at the edges of each text line. The following values are supported:

    • 0 = Algorithm 0: Standard

    • 1 = Algorithm 1: Extend

    • 2 = Algorithm 2: Extend & Clip

    • 3 = Algorithm 3: Fully Extend

    • 4 = Algorithm 4: Fully Extend & Clip

    Currently, the default value is 0. See the Comments section below for more details and illustrations.

  • 14 (PD_NVAL_SIZE_ORIGIN) — Size of the box representing origin points of non-selected PowerDoc images (small white square), in pixels. Must be positive. The default value is 4 pixels. If you wish to increase or decrease this value, change this value accordingly.

  • 15 (PD_NVAL_SIZE_SELECT) — Size of the box representing origin points of selected PowerDoc images (small black square), in pixels. Must be positive. The default value is 6 pixels. If you wish to increase or decrease this value, change this value accordingly.

  • 16 (PD_NVAL_SIZE_CLIP_EXTEND_X) — Clip extension size in horizontal direction, in pixels. The default value is 10 pixels.

  • 17 (PD_NVAL_SIZE_CLIP_EXTEND_Y) — Clip extension size in vertical direction, in pixels. The default value is 10 pixels.

  • 18 (PD_NVAL_CACHE_FLAG_FOR_MASKING) — specifies which alpha-masking algorithm to use for the specified Power Engine document. The following values are supported:

    • 0 = Algorithm 0: Use Power Engine's caching subsystem to buffer the entire visible area of the referenced masking pages. This algorithm is suitable when many objects on the rendered page are masked with various parts of the same masking page. However, this typically requires more space in the caching subsystem than with any other algorithm (especially if nested alpha-masking is used and the size of the visible page area is large). This was the default algorithm prior to D-Type Engine version 4.0.4.7.

    • 1 = Algorithm 1: An obsolete and low-performance algorithm. Should not be used.

    • 2 = Algorithm 2: Do not use Power Engine's caching subsystem to buffer entire masking pages. Instead, use a local buffer to store only the area of the page that is to be masked, and dispose it immediately after use. This new algorithm requires less memory and is particularly suitable when objects on the rendered page are masked mostly with different masking pages.

    Currently, value 2 is the default algorithm. However, this default may be changed in the future versions. If you wish to set the alpha-masking algorithm explicitly, change this value accordingly.

  • 19 (PD_NVAL_CACHE_FLAG_FOR_GLYPHS) — Specifies which caching algorithm to use for the glyphs during text layout operations. The following values are supported:

    • 0 = Algorithm 0: Store in Power Engine's caching subsystem positional glyph data obtained from character codes during text layout operations and later reuse this data when rendering the same text.

    • 1 = Algorithm 1: Do not store in Power Engine's caching subsystem positional glyph data.

    Currently, value 0 is the default algorithm. However, this default may be changed in the future versions. If you wish to set the glyph caching algorithm explicitly, change this value accordingly.

  • 20 (PD_NVAL_CONTROL_GLYPHS) — A set of bit values to enable or disable the display of missing (undefined) glyphs and control the behavior of the underline/strike-through effects when applied to the missing (undefined) glyphs and tabs.

    • Bit 0: If unset (0), glyphs whose index is 0 (i.e. missing or undefined glyphs) will not be rendered. If set (1), glyphs whose index is 0 will be rendered (typically as a missing glyph box, provided that this glyph is defined in the font).

    • Bit 1: If unset (0), glyphs whose index is 0 (i.e. missing or undefined glyphs) will not be affected by the underline and strike-through effects. If set (1), glyphs whose index is 0 will be affected by the underline and strike-through effects.

    • Bit 2: If unset (0), tabs will not be affected by the underline and strike-through effects. If set (1), tabs will be affected by the underline and strike-through effects.

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

    Currently, the default value is 0 (i.e. none of the bits are set).

  • 21 (PD_NVAL_CONTROL_ALGORITHMS) — Miscellaneous bits as described below.

    • Bit 0 and 1: These two bits represent a single 2-bit value which identifies one of the 4 available frames generation algorithms. These algorithms are:

      00 (0) — Frames that are part of the same text flow are generated using a legacy algorithm that is designed to avoid, as much as possible, any overlaps between neighboring frames. This algorithm is fast, however, in some cases (e.g. when the value of the pdSpacingRow property is negative) generates frames that do not accurately represent the geometry of the glyphs they are supposed to enclose.

      01 (1) — Frames that are part of the same text flow are generated using a new algorithm that is designed to more accurately represent the geometry of the glyphs they enclose. Internally, the frames are generated using the glyphs' clip-boxes. However, this algorithm may generate frames that in some cases overlap (e.g. when the value of the pdSpacingRow property is negative).

      10 (2) — Similar to the algorithm defined by value 01 (1) but internally uses the glyphs' typo-boxes. This is the recommended algorithm since it minimizes the amount of overlap between neighboring frames while the frames themselves accurately represent the geometry of the glyphs they enclose.

      11 (3) — Similar to the algorithm defined by value 01 (1) but uses the glyphs' extent-boxes.

    • Bit 2: An internal library parameter. Must be set to 1.

    • Bit 3: Algorithm for calculating the glyph mid-x points in vertical text layout. This algorithm is utilized when the engine calculates the Default Baseline in Landscape Mode. If unset (0), the algorithm is "Glyph Width". With this algorithm the mid-x point is half way between the glyph's minimum and maximum x coordinate. If set (1), the algorithm is "Advance Width". With this algorithm 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.

    • Bit 4: This bit controls the direction of the line-break character (e.g. space or newline). If unset, the direction of the line-break character will be the same as the global text direction (pdGlobalDirection). If this bit is set, the direction of the line-break character will be resolved the same way as for other characters in text.

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

    Currently, the default value of this parameter is 0x1101 (13). This may change in the future.

  • 22 (PD_NVAL_FONT_COLOR_OFFSET_R) — The index of the RGBA color component in color fonts that will be interpreted as the R channel when rendering the specified Power Engine document to the destination memory surface. Must not be smaller than 0 or greater than 3. The default value is 0. Currently this setting works with OpenType color fonts that include color glyph layers, color PNG/JPEG bitmap glyph images or SVG glyphs.

  • 23 (PD_NVAL_FONT_COLOR_OFFSET_G) — The index of the RGBA color component in color fonts that will be interpreted as the G channel when rendering the specified Power Engine document to the destination memory surface. Must not be smaller than 0 or greater than 3. The default value is 1. Currently this setting works with OpenType color fonts that include color glyph layers, color PNG/JPEG bitmap glyph images or SVG glyphs.

  • 24 (PD_NVAL_FONT_COLOR_OFFSET_B) — The index of the RGBA color component in color fonts that will be interpreted as the B channel when rendering the specified Power Engine document to the destination memory surface. Must not be smaller than 0 or greater than 3. The default value is 2. Currently this setting works with OpenType color fonts that include color glyph layers, color PNG/JPEG bitmap glyph images or SVG glyphs.

  • 25 (PD_NVAL_FONT_COLOR_OFFSET_A) — The index of the RGBA color component in color fonts that will be interpreted as the A channel when rendering the specified Power Engine document to the destination memory surface. Must not be smaller than 0 or greater than 3. The default value is 3. Currently this setting works with OpenType color fonts that include color glyph layers, color PNG/JPEG bitmap glyph images or SVG glyphs.

numeric_value

The value of the numeric parameter.

Comments

The following table illustrates the effect of the PD_NVAL_SELECT_EXTENSION value on the text selection and hit testing behavior at the edges of text lines that are part of a rectangular Text Area or Rich Text Area object. In the following descriptions, the assumption is that hit testing (mouse clicks) are constrained to the text area's bounding rectangle. The illustrations show a single centered text paragraph.

PD_NVAL_SELECT_EXTENSION
Value
IllustrationDescription / Impact on text selection and hit testing
0

Algorithm 0:
Standard (Default)

Algorithm 0

Algorithm 0
 
  • All regular glyphs have frames that accurately describe their geometry. No frame is extended or modified in any way.

  • If a text line ends with a regular line-break glyph (e.g. whitespace), its frame might be partially outside the text area's bounding rectangle.

  • If a text line ends with a synthesized glyph (e.g. hyphen or ellipsis), that glyph will not be covered by any frame.

  • A mouse click to the left of the first glyph or a mouse click to the right of the last glyph, on any text line, will not fall within the bounds of any glyph frame. As a result, the hit testing algorithm will return the frame that is nearest (measured as the Euclidean distance) to the position of the click. Note that depending on the coordinates of the mouse click, the nearest glyph may or may not be on the same text line.

1

Algorithm 1:
Extend

Algorithm 1

Algorithm 1
 
  • All regular glyphs, with the possible exception of the first and last one on each text line, have frames that accurately describe their geometry. The first glyph on each text line, if regular, has its frame modified so the frame's left edge is aligned with the text area's left edge, as long as the frame is inside the text area's bounding rectangle (which means the frame can only be extended and never contracted). Similarly, the last glyph on each text line, if regular, has its frame modified so the frame's right edge is aligned with the text area's right edge, as long as the frame is inside the text area's bounding rectangle (which, again, means the frame can only be extended and never contracted).

  • If a text line ends with a regular line-break glyph (e.g. whitespace), its frame might be partially outside the text area's bounding rectangle.

  • If a text line ends with a synthesized glyph (e.g. hyphen or ellipsis), that glyph will not be covered by any frame.

  • A mouse click to the left of the first glyph, on any text line, will fall within the bounds of the first glyph frame, if that glyph is regular. A mouse click to the right of the last glyph, on any text line, will fall within the bounds of the last glyph frame, if that glyph is regular. Thus, if the glyph is regular and the click is within the left side of the bounding frame, the cursor will be positioned immediately before the chosen glyph; likewise if the glyph is regular and the click is within the right side of the bounding frame, the cursor will be positioned immediately after the chosen glyph. In all other situations (i.e. when the glyph is not regular), the cursor will behave the same as in Algorithm 0 described above.

2

Algorithm 2:
Extend & Clip

Algorithm 2

Algorithm 2
 
  • All regular glyphs, except the first and last one on each text line, have frames that accurately describe their geometry. The first glyph on each text line, if regular, has its frame modified so the frame's left edge is always aligned with the text area's left edge. Because of this unconditional alignment requirement, the frame might be contracted (clipped) if it's partially outside the text area's bounding rectangle. Similarly, the last glyph on each text line, if regular, has its frame modified so the frame's right edge is always aligned with the text area's right edge. Again, because of this unconditional alignment requirement, the frame might be contracted (clipped) if it's partially outside the text area's bounding rectangle.

  • If a text line ends with a regular line-break glyph (e.g. whitespace), its frame might be clipped so its right edge is aligned with the right edge of the text area's bounding rectangle.

  • If a text line ends with a synthesized glyph (e.g. hyphen or ellipsis), that glyph will not be covered by any frame.

  • A mouse click to the left of the first glyph, on any text line, will fall within the bounds of the first glyph frame, if that glyph is regular. A mouse click to the right of the last glyph, on any text line, will fall within the bounds of the last glyph frame, if that glyph is regular. Thus, if the glyph is regular and the click is within the left side of the bounding frame, the cursor will be positioned immediately before the chosen glyph; likewise if the glyph is regular and the click is within the right side of the bounding frame, the cursor will be positioned immediately after the chosen glyph. In all other situations (i.e. when the glyph is not regular), the cursor will behave the same as in Algorithm 0 described above.

3

Algorithm 3:
Fully Extended

Algorithm 3

Algorithm 3
 
  • All regular glyphs, with the possible exception of the first and last one on each text line, have frames that accurately describe their geometry. The first regular glyph on each text line has its frame modified so the frame's left edge is aligned with the text area's left edge, as long as the frame is inside the text area's bounding rectangle (which means the frame can only be extended and never contracted). Similarly, the last regular glyph on each text line has its frame modified so the frame's right edge is aligned with the text area's right edge, as long as the frame is inside the text area's bounding rectangle (which, again, means the frame can only be extended and never contracted).

  • If a text line ends with a regular line-break glyph (e.g. whitespace), its frame might be partially outside the text area's bounding rectangle.

  • If a text line ends with a synthesized glyph (e.g. hyphen or ellipsis), that glyph will be covered by the extended frame of its neighboring regular glyph.

  • A mouse click to the left of the first glyph, on any text line, will fall within the bounds of the first regular glyph frame. A mouse click to the right of the last glyph, on any text line, will fall within the bounds of the last regular glyph frame. Thus, if the click is within the left side of the bounding frame, the cursor will be positioned immediately before the chosen glyph; likewise if the click is within the right side of the bounding frame, the cursor will be positioned immediately after the chosen glyph.

4

Algorithm 4:
Fully Extended & Clip

Algorithm 4

Algorithm 4
 
  • All regular glyphs, except the first and last one on each text line, have frames that accurately describe their geometry. The first regular glyph on each text line has its frame modified so the frame's left edge is always aligned with the text area's left edge. Because of this unconditional alignment requirement, the frame might be contracted (clipped) if it's partially outside the text area's bounding rectangle. Similarly, the last regular glyph on each text line has its frame modified so the frame's right edge is always aligned with the text area's right edge. Again, because of this unconditional alignment requirement, the frame might be contracted (clipped) if it's partially outside the text area's bounding rectangle.

  • If a text line ends with a regular line-break glyph (e.g. whitespace), its frame might be clipped so its right edge is aligned with the right edge of the text area's bounding rectangle.

  • If a text line ends with a synthesized glyph (e.g. hyphen or ellipsis), that glyph will be covered by the modified frame of its neighboring regular glyph.

  • A mouse click to the left of the first glyph, on any text line, will fall within the bounds of the first regular glyph frame. A mouse click to the right of the last glyph, on any text line, will fall within the bounds of the last regular glyph frame. Thus, if the click is within the left side of the bounding frame, the cursor will be positioned immediately before the chosen glyph; likewise if the click is within the right side of the bounding frame, the cursor will be positioned immediately after the chosen glyph.

Related Functions

pdDocGetNumericValue

 

Index