Block header¶

A block's fixed header consists of "tb::BLK_START - 1" integer scalars, each of which is accessible via the corresponding "tb::BLK_XXX" constant. The constants are separated into two logical groups:

        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 first group defines the offset constants that are used to address the values in the block header; the constants lie in the 0 - "tb::BLK_START - 1" range. The second group values line in the "tb::BLK_DATA_START" - "tb::BLK_DATA_END" range. This is done for eventual backward compatibility, if the future development changes the length of the header.

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

Block parameters¶

The scalars after "tb::BLK_START" encode the commands to the block renderer. These commands have their own parameters which follow the command. The length of the command is encoded in the high 16-bit word of the command. The basic command set includes "OP_TEXT", "OP_COLOR", "OP_FONT", "OP_TRANSPOSE", and "OP_CODE". The additional codes are "OP_WRAP" and "OP_MARK", not used in drawing but are special commands to block_wrap.

OP_TEXT - TEXT_OFFSET, TEXT_LENGTH, TEXT_WIDTH

"OP_TEXT" commands to draw a string, from the offset "tb::BLK_TEXT_OFFSET + TEXT_OFFSET", with the length TEXT_LENGTH. The third parameter TEXT_WIDTH contains the width of the text in pixels. The scheme is made for simplification of an imaginary code, that would alter ( insert to, or delete part of ) the text; the updating procedure would not need to traverse all commands in all blocks, but only 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 the "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 the "tb::COLOR_INDEX" flag, in such case it is treated an index in the "::colormap" property array.

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

OP_FONT - KEY, VALUE

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

Relates 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 into account. If FLAGS does not contain "tb::X_EXTEND", then in addition to the block expansion, the current coordinate is also moved to (X,Y). "(OP_TRANSPOSE,0,0,0)" and "(OP_TRANSPOSE,0,0,X_EXTEND)" are identical and are empty operators.

The "X_DIMENSION_FONT_HEIGHT" flag indicates that (X,Y) values must be multiplied by the current font height. Another flag "X_DIMENSION_POINT" does the same but multiplies by the current value of the resolution property divided by 72 ( treats X and Y not as pixel but as 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 rewritten every time a new graphic is invented. For example, see how Prima::PodView implements images and bullet points.

OP_CODE - SUB, PARAMETER

Contains a custom code pointer SUB with a parameter PARAMETER, passed when the 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 the block. The format of the state is the same as of the text block, and the F_ID, F_SIZE, the F_STYLE constants are the same as BLK_FONT_ID, BLK_FONT_SIZE, and BLK_FONT_STYLE.

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

OP_WRAP mode

"OP_WRAP" is only used in the 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 the ignoreImmediateWrap option 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)" command sequence has the same effect as the "(OP_WRAP,WRAP_MODE_OFF)" sequence. If "mode" is WRAP_MODE_ON, wrapping is disabled - all following commands are treated as non-wrappable until the "(OP_WRAP,WRAP_MODE_OFF)" command sequence is met.

OP_MARK PARAMETER, X, Y

"OP_MARK" is only in effect in the 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, for example for saving the geometrical positions during the block wrapping.

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

Rendering methods¶

block_wrap %OPTIONS

"block_wrap" wraps a block into a given width in pixels. It returns one or more text blocks with fully formed headers. The returned blocks are located one below another, providing an illusion that the text itself is wrapped. It does not only traverse the opcodes and sees if the command fits 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 the "OP_WRAP" command brackets. The commands inside these brackets are not wrapped; the "OP_WRAP" commands are removed from the resulting blocks.

"block_wrap" copies all commands and their parameters as is, except the following:

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

- If "OP_TRANSPOSE"'s third parameter, "X_FLAGS" contains the "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. The "X_DIMENSION_PIXEL" has a similar effect but the coordinates are multiplied by the current resolution divided by 72.

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

- "OP_WRAP" is removed from the output.

justify_interspace %OPTIONS

Uses $OPTIONS{width} and $OPTIONS{min_text_to_space_ratio} to try to make inter-word spacing. Returns new block if successful, undef otherwise.

walk BLOCK, %OPTIONS

Cycles through the block opcodes, calls supplied callbacks on each.