/ 
UI-Various-1.00
River stage one • 1 direct dependent • 1 total dependent
/ UI::Various::RichTerm::base

NAME

UI::Various::RichTerm::base - abstract helper class for RichTerm's UI elements

SYNOPSIS

# This module should only be used by the UI::Various::RichTerm UI
# element classes!

ABSTRACT

This module provides some helper functions for the UI elements of the rich console.

DESCRIPTION

The documentation of this module is only intended for developers of the package itself.

All functions of the module will be included as second "base class" (in @ISA). Note that this is not a diamond pattern as this "base class" does not import anything besides Exporter.

Global Definitions

%D

a hash of decoration characters for window borders (W1 to W9 without W5), box borders (B*, b* and c5), check boxes (CL and CR), radio buttons (RL and RR), normal buttons (BL and BR), selected (SL1 and SL0) and underline (UL1 and UL0).

METHODS

The module provides the following common (internal) methods for all UI::Various::RichTerm UI element classes:

_size - determine size of UI element

($width, $height) = $ui_element->_size($string, $content_width);

example:

my ($w, $h) = $self->_size($self->text, $content_width);

parameters:

$string             the string to be analysed
$content_width      preferred width of content

description:

This method determines the width and height of a UI element.

If the UI element has it's own defined (not inherited) widht and/or height, no other calculation is made (no matter if the string will fit or not).

If no own width is defined, the text will be wrapped into lines no longer than the given preferred maximum width and the length of the longest of line is returned. If a sub-string has no word boundary to break it into chunks smaller than $content_width, $content_width is returned even though the string will not really fit when it will be displayed later.)

If no own height is defined, the number of lines of the wrapped string is returned.

returns:

width and height of the string when it will be displayed later

_color_on_off - compute escape sequences needed for colours

($colour_on, $colour_off) = $ui_element->_color_on_off();

example:

my ($col_on, $col_off) = $ui_element->_color_on_off();

description:

This method determines the escape sequences needed to set background and foreground colours, and to switch them off again.

returns:

escape sequence to set the colours and escape sequence to turn them of

_color_simplify - remove unnecessary escape sequences

$simplified = $ui_element->_color_simplify($coloured_text);

example:

$text = $ui_element->_color_simplify($text);

description:

This method removes unnecessary escape sequences from a text. It might cost a bit of performance, but eases debugging of wrong colours.

returns:

simplified text

_format - format text according to given options

$string = $ui_element->_format($prefix, $decoration_before, $effect_before,
                               $text, $effect_after, $decoration_after,
                               $width, $height [, $no_wrap]);
    or

$string = $ui_element->_format($prefix, $decoration_before, $effect_before,
                               \@text, $effect_after, $decoration_after,
                               $width, $height);

example:

my ($w, $h) = $self->_size($self->text, $content_width);
$string = $self->_format('(1) ', '', '[ ', $self->text, ' ]', '', $w, $h);

parameters:

$prefix             text in front of first line
$decoration_before  decoration before content of each line
$effect_before      effect before content of each line
$text               string to be wrapped or reference to wrapped text lines
$effect_after       end of effect after content of each line
$decoration_after   decoration after content of each line
$width              the width returned by _size above
$height             the height returned by _size above
$no_wrap            optional flag to inhibit wrapping of a text string

description:

This method formats the given text into a text box of the previously (_size) determined width and height, decorates it with some additional strings (e.g. to symbolise a button) and a prefix set by its parent. Note that the (latter) prefix is only added to the first line with text, all additional lines gets a blank prefix of the same length.

Also note that the given text can either be a string which is wrapped or a reference to an array of already wrapped strings that only need the final formatting.

The decorations and prefix will cause the resulting text box to be wider than the given width, which only describes the width of the text itself. The effect is sort of a zero-width decoration (applied to the text without padding), usually an ANSI escape sequence.

And as already described under _size above, the layout will be broken if it can't fit. The display of everything is preferred over cutting of possible important parts.

returns:

the rectangular text box for the given string

SEE ALSO

UI::Various

LICENSE

Copyright (C) Thomas Dorner.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See LICENSE file for more details.

AUTHOR

Thomas Dorner <dorner (at) cpan (dot) org>