Man Linux: Main Page and Category List

NAME

       Prima::TextView - rich text browser widget

DESCRIPTION

       Prima::TextView accepts blocks of formatted text, and provides basic
       functionality - scrolling and user selection. The text strings are
       stored as one large text chunk, available by the "::text" and
       "::textRef" properties.  A block of a formatted text is an array with
       fixed-length header and the following instructions.

       A special package "tb::" provides the block constants and simple
       functions for text block access.

   Capabilities
       Prima::TextView is mainly the text block functions and helpers. It
       provides function for wrapping text block, calculating block
       dimensions, drawing and converting coordinates from (X,Y) to a block
       position. Prima::TextView is centered around the text functionality,
       and although any custom graphic of arbitrary complexity can be embedded
       in a text block, the internal coordinate system is used ( TEXT_OFFSET,
       BLOCK ), where TEXT_OFFSET is a text offset from the beginning of a
       block and BLOCK is an index of a block.

       The functionality does not imply any text layout - this is up to the
       class descendants, they must provide they own layout policy. The only
       policy Prima::TextView requires is that blocks’ BLK_TEXT_OFFSET field
       must be strictly increasing, and the block text chunks must not
       overlap. The text gaps are allowed though.

       A text block basic drawing function includes change of color, backColor
       and font, and the painting of text strings. Other types of graphics can
       be achieved by supplying custom code.

   Block header
       A block’s fixed header consists of "tb::BLK_START - 1" integer scalars,
       each of those 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 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
       The scalars, beginning from "tb::BLK_START", represent the commands to
       the renderer.  These commands have their own parameters, that follow
       the command. The length of a command is located in @oplen array, and
       must not be changed. 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 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
           or 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".

           F_STYLE
               Contains a combination of "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 widget’s font size. As such, 0 is a default value, and
               -2 is the widget’s 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 vary when
               relying on the combined font size value .

               If "F_SIZE" value is added to a "F_HEIGHT" constant, then it is
               treated as a 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 a
               index in the "::fontPalette" property array, which contains
               font hashes with the other font keys initialized - name,
               encoding, and pitch. These three are minimal required set, and
               the other font keys can be also selected.

       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 ON_OFF
           "OP_WRAP" is only in effect in block_wrap method. ON_OFF is a
           boolean flag, selecting if the wrapping is turned on or off.
           block_wrap does not support stacking for the wrap commands, so the
           "(OP_WRAP,1,OP_WRAP,1,OP_WRAP,0)" has same effect as "(OP_WRAP,0)".
           If ON_OFF is 1, wrapping is disabled - all following commands
           treated an non-wrapable until "(OP_WRAP,0)" 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
           "block_wrap" is the function, that is used to wrap 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
           especially:

           - "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.

       block_draw CANVAS, BLOCK, X, Y
           The "block_draw" draws BLOCK onto CANVAS in screen coordinates
           (X,Y).  It can not only be used for drawing inside
           begin_paint/end_paint brackets; CANVAS can be an arbitrary
           "Prima::Drawable" descendant.

   Coordinate system methods
       Prima::TextView employs two its own coordinate systems: (X,Y)-document
       and (TEXT_OFFSET,BLOCK)-block.

       The document coordinate system is isometric and measured in pixels. Its
       origin is located into the imaginary point of the beginning of the
       document ( not of the first block! ), in the upper-left point. X
       increases to the right, Y increases downwards.  The block header values
       BLK_X and BLK_Y are in document coordinates, and the widget’s pane
       extents ( regulated by "::paneSize", "::paneWidth" and "::paneHeight"
       properties ) are also in document coordinates.

       The block coordinate system in an-isometric - its second axis, BLOCK,
       is an index of a text block in the widget’s blocks storage,
       "$self->{blocks}", and its first axis, TEXT_OFFSET is a text offset
       from the beginning of the block.

       Below described different coordinate system converters

       screen2point X, Y
           Accepts (X,Y) in the screen coordinates ( O is a lower left widget
           corner ), returns (X,Y) in document coordinates ( O is upper left
           corner of a document ).

       xy2info X, Y
           Accepts (X,Y) is document coordinates, returns (TEXT_OFFSET,BLOCK)
           coordinates, where TEXT_OFFSET is text offset from the beginning of
           a block ( not related to the big text chunk ) , and BLOCK is an
           index of a block.

       info2xy TEXT_OFFSET, BLOCK
           Accepts (TEXT_OFFSET,BLOCK) coordinates, and returns (X,Y) in
           document coordinates of a block.

       text2xoffset TEXT_OFFSET, BLOCK
           Returns X coordinate where TEXT_OFFSET begins in a BLOCK index.

       info2text_offset
           Accepts (TEXT_OFFSET,BLOCK) coordinates and returns the text offset
           with regard to the big text chunk.

       text_offset2info TEXT_OFFSET
           Accepts big text offset and returns (TEXT_OFFSET,BLOCK) coordinates

       text_offset2block TEXT_OFFSET
           Accepts big text offset and returns BLOCK coordinate.

   Text selection
       The text selection is performed automatically when the user selects the
       region with a mouse. The selection is stored in (TEXT_OFFSET,BLOCK)
       coordinate pair, and is accessible via the "::selection" property.  If
       its value is assigned to (-1,-1,-1,-1) this indicates that there is no
       selection. For convenience the "has_selection" method is introduced.

       Also, "get_selected_text" returns the text within the selection (or
       undef with no selection ), and "copy" copies automatically the selected
       text into the clipboard. The latter action is bound to "Ctrl+Insert"
       key combination.

   Event rectangles
       Partly as an option for future development, partly as a hack a concept
       of ’event rectangles’ was introduced. Currently, "{contents}" private
       variable points to an array of objects, equipped with "on_mousedown",
       "on_mousemove", and "on_mouseup" methods. These are called within the
       widget’s mouse events, so the overloaded classes can define the
       interactive content without overloading the actual mouse events ( which
       is although easy but is dependent on Prima::TextView own mouse
       reactions ).

       As an example Prima::PodView uses the event rectangles to catch the
       mouse events over the document links. Theoretically, every ’content’ is
       to be bound with a separate logical layer; when the concept was
       designed, a html-browser was in mind, so such layers can be thought as
       ( in the html world ) links, image maps, layers, external widgets.

       Currently, "Prima::TextView::EventRectangles" class is provided for
       such usage. Its property "::rectangles" contains an array of
       rectangles, and the "contains" method returns an integer value, whether
       the passed coordinates are inside one of its rectangles or not; in the
       first case it is the rectangle index.