NAME

Prima::Drawable::TextBlock - rich text representation

API

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.

F_STYLE

Contains a combination of the fs::XXX constants, such as fs::Bold, fs::Italic etc.

Default value: 0

F_SIZE

Contains the relative font size. The size is relative to the current font size. As such, 0 is a default value, and -2 is the default font decreased by 2 points. Prima::TextView provides no range checking ( but the toolkit does ), so while it is o.k. to set the negative F_SIZE values larger than the default font size, one must be careful when relying on the combined font size value .

If the F_SIZE value is added to the F_HEIGHT constant, then it is treated as font height in pixels rather than font size in points. The macros for these opcodes are named respectively tb::fontSize and tb::fontHeight, while the opcode is the same.

F_ID

All other font properties are collected under an 'ID'. ID is an index in the ::fontPalette property array, which contains font hashes with the other font keys initialized - name, encoding, and pitch. These three fields are required to be defined in the font hash; the other font fields are optional.

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.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

Prima::TextView, Prima::Drawable::Markup, examples/mouse_tale.pl.