Block header

        BLK_FLAGS
        BLK_WIDTH
        BLK_HEIGHT
        BLK_X
        BLK_Y
        BLK_APERTURE_X
        BLK_APERTURE_Y
        BLK_TEXT_OFFSET

and

        BLK_FONT_ID
        BLK_FONT_SIZE
        BLK_FONT_STYLE
        BLK_COLOR
        BLK_BACKCOLOR

The second group is enclosed in "tb::BLK_DATA_START" - "tb::BLK_DATA_END" range, like the whole header is contained in 0 - "tb::BLK_START - 1" range. This is done for the backward compatibility, if the future development changes the length of the header.

The first group fields define the text block dimension, aperture position and text offset ( remember, the text is stored as one big chunk ). The second defines the initial color and font settings. Prima::TextView needs all fields of every block to be initialized before displaying. block_wrap method can be used for automated assigning of these fields.

Block parameters

OP_TEXT - TEXT_OFFSET, TEXT_LENGTH, TEXT_WIDTH

"OP_TEXT" commands to draw a string, from offset "tb::BLK_TEXT_OFFSET + TEXT_OFFSET", with a length TEXT_LENGTH. The third parameter TEXT_WIDTH contains the width of the text in pixels. Such the two-part offset scheme is made for simplification of an imaginary code, that would alter ( insert to, or delete part of ) the big text chunk; the updating procedure would not need to traverse all commands, but just the block headers.

Relative to: "tb::BLK_TEXT_OFFSET"

OP_COLOR - COLOR

"OP_COLOR" sets foreground or background color. To set the background, COLOR must be or-ed with "tb::BACKCOLOR_FLAG" value. In addition to the two toolkit supported color values ( RRGGBB and system color index ), COLOR can also be or-ed with "tb::COLOR_INDEX" flags, in such case it is an index in "::colormap" property array.

Relative to: "tb::BLK_COLOR", "tb::BLK_BACKCOLOR".

OP_FONT - KEY, VALUE

As the font is a complex property, that itself includes font name, size, direction, etc keys, "OP_FONT" KEY represents one of the three parameters - "tb::F_ID", "tb::F_SIZE", "tb::F_STYLE". All three have different VALUE meaning.

Relative to: "tb::BLK_FONT_ID", "tb::BLK_FONT_SIZE", "tb::BLK_FONT_STYLE".

OP_TRANSPOSE X, Y, FLAGS

Contains a mark for an empty space. The space is extended to the relative coordinates (X,Y), so the block extension algorithms take this opcode in the account. If FLAGS does not contain "tb::X_EXTEND", then in addition to the block expansion, current coordinate is also moved to (X,Y). In this regard, "(OP_TRANSPOSE,0,0,0)" and "(OP_TRANSPOSE,0,0,X_EXTEND)" are identical and are empty operators.

There are formatting-only flags,in effect with block_wrap function. "X_DIMENSION_FONT_HEIGHT" indicates that (X,Y) values must be multiplied to the current font height. Another flag "X_DIMENSION_POINT" does the same but multiplies by current value of resolution property divided by 72 ( basically, treats X and Y not as pixel but point values).

"OP_TRANSPOSE" can be used for customized graphics, in conjunction with "OP_CODE" to assign a space, so the rendering algorithms do not need to be re-written every time the new graphic is invented. As an example, see how Prima::PodView deals with the images.

OP_CODE - SUB, PARAMETER

Contains a custom code pointer SUB with a parameter PARAMETER, passed when a block is about to be drawn. SUB is called with the following format:

        ( $widget, $canvas, $text_block, $font_and_color_state, $x, $y, $parameter);
    

$font_and_color_state ( or $state, through the code ) contains the state of font and color commands in effect, and is changed as the rendering algorithm advances through a block. The format of the state is the same as of text block, so one may notice that for readability F_ID, F_SIZE, F_STYLE constants are paired to BLK_FONT_ID, BLK_FONT_SIZE and BLK_FONT_STYLE.

The SUB code is executed only when the block is about to draw.

OP_WRAP mode

"OP_WRAP" is only in effect in block_wrap method. "mode" is a flag, selecting the wrapping command.

   WRAP_MODE_ON   - default, block commands can be wrapped
   WRAP_MODE_OFF  - cancels WRAP_MODE_ON, commands cannot be wrapped
   WRAP_IMMEDIATE - proceed with immediate wrapping, unless ignoreImmediateWrap options is set
    

block_wrap does not support stacking for the wrap commands, so the "(OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_OFF)" has same effect as "(OP_WRAP,WRAP_MODE_OFF)". If "mode" is WRAP_MODE_ON, wrapping is disabled - all following commands treated an non-wrapable until "(OP_WRAP,WRAP_MODE_OFF)" is met.

OP_MARK PARAMETER, X, Y

"OP_MARK" is only in effect in block_wrap method and is a user command. block_wrap only sets (!) X and Y to the current coordinates when the command is met. Thus, "OP_MARK" can be used for arbitrary reasons, easy marking the geometrical positions that undergo the block wrapping.

As can be noticed, these opcodes are far not enough for the full-weight rich text viewer. However, the new opcodes can be created using "tb::opcode", that accepts the opcode length and returns the new opcode value.

Rendering methods

block_wrap %OPTIONS

"block_wrap" wraps a block into a given width. It returns one or more text blocks with fully assigned headers. The returned blocks are located one below another, providing an illusion that the text itself is wrapped. It does not only traverses the opcodes and sees if the command fit or not in the given width; it also splits the text strings if these do not fit.

By default the wrapping can occur either on a command boundary or by the spaces or tab characters in the text strings. The unsolicited wrapping can be prevented by using "OP_WRAP" command brackets. The commands inside these brackets are not wrapped; "OP_WRAP" commands are removed from the output blocks.

In general, "block_wrap" copies all commands and their parameters as is, ( as it is supposed to do ), but some commands are treated specially:

- "OP_TEXT"'s third parameter, "TEXT_WIDTH", is disregarded, and is recalculated for every "OP_TEXT" met.

- If "OP_TRANSPOSE"'s third parameter, "X_FLAGS" contains "X_DIMENSION_FONT_HEIGHT" flag, the command coordinates X and Y are multiplied to the current font height and the flag is cleared in the output block.

- "OP_MARK"'s second and third parameters assigned to the current (X,Y) coordinates.

- "OP_WRAP" removed from the output.

walk BLOCK, %OPTIONS

Cycles through block opcodes, calls supplied callbacks on each.