NAME

UI::Various::widget - abstract base class for UI elements

SYNOPSIS

    # This module should never be used directly!
    # It is used indirectly via the following:
    use UI::Various;

ABSTRACT

This module is the common abstract base class for all kinds of objects in the UI::Various package aka UI elements or widgets.

DESCRIPTION

All UI::Various::[A-Z]* modules are classes with the following common attributes (inherited from UI::Various::widget):

Attributes

(Usually attributes are sorted alphabetically.)

rw attributes can be read and modified. The later may have some restrictions. (See documentation of specific attribute).

ro attributes can only be read and not modified.

fixed attributes may only be modified before using the widget. (Note that this is mostly not enforced.)

wo attributes can only be initialised and not modified or read later.

optional attributes may be empty or undef.

recommended attributes may be empty or undef, but it is advisable to give them a proper value.

inherited attributes may be undefined, but if they are read, a possible value will be searched for all the hierarchy up to either the main "Window Manager" object or the top-level Window or Dialogue objects. They may still be undefined everywhere, though.

align [rw, optional]

the alignment of a UI element is a digit between 1 and 9, 1 being the lower left corner, 2 the lower centre, 3 the lower right and so on until the 9 in the upper right

Note: Simply look at the keypad of your keyboard as mnemonic.

Also note that the alignment is ignored by the PoorTerm interface.

bg [rw, optional]

the background colour of a UI element can either be the name of the basic 8 colours (black, blue, cyan, green, magenta, red, white, yellow) or a numeric code of 6 hexadecimal digits for the RRGGBB value.

Note that colours in the Curses and RichTerm terminal UIs are restricted to 6 different values of red, green and blue each (rounded to the nearest valid value), and they are completely ignored by the PoorTerm interface.

Also note this TUI restriction is independent of possible actual (maybe additional) restrictions of the colour-set of a terminal. I've not yet found a reliable way to get this information as even the terminfo entries may be wrong (e.g. xterm has an entry of only 8 colours while test with a simple shell script show it apparently can display true colour). The 6^3 == 216 colours is just what most terminal emulations should support (using ANSI escape codes 38 and 48).

Finally note that Curses will probably mess up the standard terminal colours (at least those not being the 8 basic colours) when it exits. I've not yet found a way to reset this. Restricting an application to the 8 basic colours (black, blue, cyan, green, magenta, red, white and yellow) should be always safe.

fg [rw, optional]

the background colour of a UI element can either be the name of the basic 8 colours (black, blue, cyan, green, magenta, red, white, yellow) or a numeric code of 6 hexadecimal digits for the RRGGBB value.

See bg above for the colour restrictions of the terminal UIs.

height [rw, fixed, inherited]

preferred (maximum) height of a UI element in (approximately) characters, should not exceed max_height of main "Window Manager"

Be careful with small height values as this could lead to undisplayed or even discarded UI elements in some of the possible UIs. If this is the main window, the application could be immediately exited!

parent [rw, optional]

a reference to the parent of the current UI element, usually undef for the UI::Various::Main object and defined for everything else

Note that usually this should only be manipulated by methods of UI::Various::container.

width [rw, fixed, inherited]

preferred (maximum) width of a UI element in (approximately) characters, should not exceed max_width of main "Window Manager"

METHODS

Besides the accessors described above the following methods are available in all UI::Various::[A-Z]* classes:

new - constructor

see UI::Various::core::construct

dump - dump internal structure to pretty-printed string

    $dump = $ui_element->dump([$level]);

example:

    print $ui_element->dump;

parameters:

    $level              optional level used for indention

description:

This method returns a string with the pretty-printed internal structure of the UI element without following into the structures of foreign UI packages. The level usually can be omitted and is initialised with 0 in those cases. Indention is two times the level.

returns:

pretty-printed dump of UI element

top - determine top UI element of hierarchy

    $top = $ui_element->top;

example:

    $top = $ui_element->top;
    if ($top) { ... }

description:

This method follows the parent relationship until it reaches the top UI element of the hierarchy and returns it. If the parent relationship has a cycle, an error is created and the method returns undef.

returns:

top UI element

_inherited_access - accessor for common inherited attributes

If a read access can't find a value for the object, it tries getting a value from all ancestors up to the main "Window Manager" object. Otherwise see UI::Various::core::access

_toplevel - return visible toplevel UI element

    $ui_element->_toplevel;

description:

Return the toplevel parent UI element of any UI container. While above top usually returns the UI::Various::Main element this call usually returns a UI::Various::Window or UI::Various::Dialog. In addition it does not have sanity checks.

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>

cpanm UI::Various

perl -MCPAN -e shell
install UI::Various