Index

C/C++ Functions

txTextSetHighlighter

DT_SWORD txTextSetHighlighter(DT_TXDOC text_doc, const DT_UBYTE cursor_blend_arr[], const DT_UBYTE select_blend_arr[], DT_SWORD reserved)

Short Description: Set text document's highlighter

This function sets the text document's highlighter. The highlighter supplies the blend mode and color needed to render the cursor and active text selections.

Parameters

ParameterDescription

text_doc

Handle of the associated text document instance.

cursor_blend_arr

An array of five bytes (BM, C1, C2, C3 and C4) specifying the blend mode and color of the cursor. The first byte, blend mode (BM), defines how the surface of the cursor will interact with the background. This byte can have the following values:

TX_BLEND_INVERT      0   /* Invert background */ 
TX_BLEND_HIGHLIGHT_1 1   /* Highlight over light background */ 
TX_BLEND_HIGHLIGHT_2 2   /* Highlight over dark background */ 
TX_BLEND_RENDER      255 /* Standard rendering */ 

The remaining four bytes, C1, C2, C3 and C4, define the color of the cursor. The interpretation is specific to the blend mode specified. For details, see the comments below.

cursor_blend_arr can be passed as DV_NULL. This has the same effect as supplying an array in which all five bytes are set to 0. This is the default setting when the text document is initialized.

select_blend_arr

An array of five bytes (BM, C1, C2, C3 and C4) specifying the blend mode and color of any active text selections. The first byte, blend mode (BM), defines how the surface of the text selection(s) will interact with the background. This byte can have the following values:

TX_BLEND_INVERT      0   /* Invert background */ 
TX_BLEND_HIGHLIGHT_1 1   /* Highlight over light background */ 
TX_BLEND_HIGHLIGHT_2 2   /* Highlight over dark background */ 
TX_BLEND_RENDER      255 /* Standard rendering */ 

The remaining four bytes, C1, C2, C3 and C4, define the color of the text selection(s). The interpretation is specific to the blend mode specified. For details, see the comments below.

select_blend_arr can be passed as DV_NULL. This has the same effect as supplying an array in which all five bytes are set to 0. This is the default setting when the text document is initialized.

reserved

Reserved for future use. Must be set to 0.

Return Value

If successful, the return value is 1. If the function was not successful (e.g. invalid input parameters), the return value is 0.

Comments

TX_BLEND_INVERT indicates that the background underneath the surface will be inverted. This means that pixels underneath the surface are typically still visible, but displayed using a different color. This color is computed using a formula that takes into account both the original color of the covered pixels and the color of the covering surface.

TX_BLEND_INVERT ExamplesParameters
TX_BLEND_INVERT BM = TX_BLEND_INVERT, C1 = 255, C2 = 255, C3 = 255, C4 = 0
BM = TX_BLEND_INVERT, C1 = 102, C2 = 204, C3 = 255, C4 = 0
BM = TX_BLEND_INVERT, C1 = 180, C2 = 150, C3 = 20, C4 = 0
BM = TX_BLEND_INVERT, C1 = 0, C2 = 0, C3 = 0, C4 = 0

TX_BLEND_HIGHLIGHT_1 and TX_BLEND_HIGHLIGHT_2 indicate that the background underneath the surface will be highlighted. The effect is similar to the one produced when a highlighter is used to mark something on a sheet of paper. With both highlight modes the pixels underneath the surface are typically still visible. TX_BLEND_HIGHLIGHT_1 is suitable for light backgrounds (e.g. white) on which dark text (e.g. black) is displayed. This highlight mode "removes" light from the background. Thus, the more times the same background is highlighted, the darker it gets. TX_BLEND_HIGHLIGHT_2 works the opposite way and is suitable for dark backgrounds (e.g. black) on which light text (e.g. white) is displayed. This highlight mode "adds" light to the background. Thus, the more times the same background is highlighted, the lighter it gets.

TX_BLEND_HIGHLIGHT_1 ExamplesParameters
TX_BLEND_HIGHLIGHT_1 BM = TX_BLEND_HIGHLIGHT_1, C1 = 255, C2 = 255, C3 = 255, C4 = 0
BM = TX_BLEND_HIGHLIGHT_1, C1 = 102, C2 = 204, C3 = 255, C4 = 0
BM = TX_BLEND_HIGHLIGHT_1, C1 = 180, C2 = 150, C3 = 20, C4 = 0
BM = TX_BLEND_HIGHLIGHT_1, C1 = 0, C2 = 0, C3 = 0, C4 = 0

TX_BLEND_HIGHLIGHT_2 ExamplesParameters
TX_BLEND_HIGHLIGHT_2 BM = TX_BLEND_HIGHLIGHT_2, C1 = 255, C2 = 255, C3 = 255, C4 = 0
BM = TX_BLEND_HIGHLIGHT_2, C1 = 102, C2 = 204, C3 = 255, C4 = 0
BM = TX_BLEND_HIGHLIGHT_2, C1 = 180, C2 = 150, C3 = 20, C4 = 0
BM = TX_BLEND_HIGHLIGHT_2, C1 = 0, C2 = 0, C3 = 0, C4 = 0

TX_BLEND_RENDER indicates that the surface will be rendered on top of the background using the standard RGBT rendering technique. This means that pixels underneath the surface will not be visible unless the surface is at least partially transparent (i.e. T > 0).

TX_BLEND_RENDER ExamplesParameters
TX_BLEND_RENDER BM = TX_BLEND_RENDER, C1 = 255, C2 = 255, C3 = 255, C4 = 0
BM = TX_BLEND_RENDER, C1 = 102, C2 = 204, C3 = 255, C4 = 0
BM = TX_BLEND_RENDER, C1 = 180, C2 = 150, C3 = 20, C4 = 0
BM = TX_BLEND_RENDER, C1 = 0, C2 = 0, C3 = 0, C4 = 0

Regardless of the blend mode, C1, C2, C3 and C4 define the color of the surface. However, the actual interpretation of these bytes differs somewhat between TX_BLEND_RENDER and all other blend modes. When blend mode is TX_BLEND_RENDER, C1, C2 and C3 represent the red (R), green (G) and blue (B) components of the surface's color, while C4 is the transparency (T). See the DT_STYLE_ATTRIBS structure and the dtOutputSetStyleAttribs function for the description of the R, G, B and T parameters. When blend mode is TX_BLEND_INVERT, TX_BLEND_HIGHLIGHT_1 or TX_BLEND_HIGHLIGHT_2, the C1, C2, C3 and C4 bytes are the color values in the corresponding 8-bpp, 24-bpp or 32-bpp memory surface to which the final output is rendered. The number of bytes that are interpreted as color values equals to the number of bytes-per-pixel in the corresponding memory surface. For example, for an 8-bpp memory surface, only the C1 byte is interpreted as a color value (A); all other bytes are ignored and should be set to 0. Similarly, for a 24-bpp memory surface, the C1, C2 and C3 bytes are interpreted as color values (R, G, B) while the C4 byte is ignored and should be set to 0. See the dtOutputSetAsMDC function for more information on the 8-bpp, 24-bpp and 32-bpp memory surfaces.

All color values supplied via the C1, C2, C3 and C4 bytes are in the [0..255] range. The value 0 means minimum intensity; the value 255 means maximum intensity.

Related Functions

txTextGetHighlighter

 

Index