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.

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

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>