Prima::Drawable::TextBlock - rich text representation
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:
tb::BLK_START - 1
tb::BLK_XXX
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.
tb::BLK_DATA_START
tb::BLK_DATA_END
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.
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.
tb::BLK_START
OP_TEXT
OP_COLOR
OP_FONT
OP_TRANSPOSE
OP_CODE
OP_WRAP
OP_MARK
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.
tb::BLK_TEXT_OFFSET + TEXT_OFFSET
Relative to: tb::BLK_TEXT_OFFSET
tb::BLK_TEXT_OFFSET
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.
tb::BACKCOLOR_FLAG
tb::COLOR_INDEX
::colormap
Relative to: tb::BLK_COLOR, tb::BLK_BACKCOLOR.
tb::BLK_COLOR
tb::BLK_BACKCOLOR
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.
tb::F_ID
tb::F_SIZE
tb::F_STYLE
Relates to: tb::BLK_FONT_ID, tb::BLK_FONT_SIZE, tb::BLK_FONT_STYLE.
tb::BLK_FONT_ID
tb::BLK_FONT_SIZE
tb::BLK_FONT_STYLE
Contains a combination of the fs::XXX constants, such as fs::Bold, fs::Italic etc.
fs::XXX
fs::Bold
fs::Italic
Default value: 0
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 .
F_SIZE
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_HEIGHT
tb::fontSize
tb::fontHeight
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.
::fontPalette
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.
tb::X_EXTEND
(OP_TRANSPOSE,0,0,0)
(OP_TRANSPOSE,0,0,X_EXTEND)
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).
X_DIMENSION_FONT_HEIGHT
X_DIMENSION_POINT
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.
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 is only used in the block_wrap method. mode is a flag, selecting the wrapping command.
mode
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_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_OFF)
(OP_WRAP,WRAP_MODE_OFF)
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.
tb::opcode
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.
block_wrap
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.
TEXT_WIDTH
- 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.
X_FLAGS
X_DIMENSION_PIXEL
- OP_MARK's second and third parameters are assigned to the current (X,Y) coordinates.
- OP_WRAP is removed from the output.
Uses $OPTIONS{width} and $OPTIONS{min_text_to_space_ratio} to try to make inter-word spacing. Returns new block if successful, undef otherwise.
$OPTIONS{width}
$OPTIONS{min_text_to_space_ratio}
Cycles through the block opcodes, calls supplied callbacks on each.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima::TextView, Prima::Drawable::Markup, examples/mouse_tale.pl.
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.