/ 
Curses-UI-0.63
River stage two • 20 direct dependents • 20 total dependents
/ Curses::UI::Container

NAME

Curses::UI::Container - Create and manipulate container widgets

CLASS HIERARCHY

Curses::UI::Widget
   |
   +----Curses::UI::Container

SYNOPSIS

use Curses::UI;
my $cui = new Curses::UI;
my $win = $cui->add('window_id', 'Window');

my $container = $win->add(
    'mycontainer', 'Container'
);

$container->add(
    'contained', 'SomeWidget',
    .....
);

$container->focus();

DESCRIPTION

A container provides an easy way of managing multiple widgets in a single "form". A lot of Curses::UI functionality is built around containers. The main class Curses::UI itself is a container. A Curses::UI::Window is a container. Some of the widgets are implemented as containers.

STANDARD OPTIONS

-parent, -x, -y, -width, -height, -pad, -padleft, -padright, -padtop, -padbottom, -ipad, -ipadleft, -ipadright, -ipadtop, -ipadbottom, -title, -titlefullwidth, -titlereverse, -onfocus, -onblur

For an explanation of these standard options, see Curses::UI::Widget.

WIDGET-SPECIFIC OPTIONS

Currently this class does not have any specific options.

METHODS

  • new ( )

    Create a new instance of the Curses::UI::Container class.

  • add ( ID, CLASS, OPTIONS )

    This is the main method for this class. Using this method it is easy to add widgets to the container.

    The ID is an identifier that you want to use for the added widget. This may be any string you want.

    The CLASS is the class which you want to add to the container. If CLASS does not contain '::' or CLASS matches 'Dialog::...' then 'Curses::UI' will be prepended to it. This way you do not have to specifiy the full class name for widgets that are in the Curses::UI hierarchy. It is not neccessary to call "use CLASS" yourself. The add method will call the usemodule method (see below) to automatically load the module.

    The hash OPTIONS contains the options that you want to pass on to the new instance of CLASS.

    Example:

    $container->add(
    'myid',                   # ID 
    'Label',                  # CLASS
    -text => 'Hello, world!', # OPTIONS
    -x    => 10,
    -y    => 5,
);

  • delete ( ID )

    This method deletes the contained widget with the given ID from the container.

  • hasa ( CLASS )

    This method returns true if the container contains one or more widgets of the class CLASS.

  • layout ( )

    Layout the Container and all its contained widgets.

  • layout_from_scratch ( )

    This will find the topmost container and call its layout method. This will recursively layout all nested containers.

  • draw ( BOOLEAN )

    Draw the Container and all its contained widgets. If BOOLEAN is true, the screen will not update after drawing. By default this argument is false, so the screen will update after drawing the container.

  • intellidraw ( )

    See Curses::UI::Widget for an explanation of this method.

  • focus ( )

    If the container contains no widgets, this routine will return immediately. Else the container will get focus.

    If the container gets focus, on of the contained widgets will get the focus. The returnvalue of this widget determines what has to be done next. Here are the possible cases:

    * The returnvalue is LEAVE_CONTAINER

    As soon as a widget returns this value, the container
will loose its focus and return the returnvalue and the
last pressed key to the caller.

    * The returnvalue is STAY_AT_FOCUSPOSITION

    The container will not loose focus and the focus will stay
at the same widget of the container.

    * Any other returnvalue

    The focus will go to the next widget in the container.

  • getobj ( ID )

    This method returns the object reference of the contained widget with the given ID.

  • getfocusobj ( )

    This method returns the object reference of the contained widget which currently has the focus.

  • focus_to_object ( ID )

    This method sets the focuspointer to the object with the given ID.

  • set_focusorder ( IDLIST )

    Normally the order in which widgets get focused in a container is determined by the order in which they are added to the container. Use set_focusorder if you want a different focus order. IDLIST contains a list of id's.

  • set_draworder ( IDLIST )

    Normally the order in which widgets are drawn in a container is determined by the order in which they are added to the container. Use set_draworder if you want a different draw order. IDLIST contains a list of id's.

  • rebuild ( )

    This will redraw the Curses::UI::Window widgets (and descendants) that are in the container (internally this method calls ontop (undef, 1)).

  • rebuild_from_scratch ( )

    This will find the topmost container and call its rebuild method. This will recursively rebuild all nested containers.

  • ontop ( WINDOW, BOOLEAN )

    If a container contains a number of Curses::UI::Window widgets (or descendants), the window stack order is remembered. Using the ontop method, the window with the given WINDOW (its id or object reference) can be brought on top of the stack. If WINDOW is undefined, the window that is currently on top will be used.

    If BOOLEAN is true the screen will always be redrawn. If BOOLEAN is false, the screen will only be redrawn if the WINDOW differs from the window that is currently on top.

  • window_is_ontop ( WINDOW )

    This checks if the window that is specified by WINDOW (its id or object reference) is currently on top. Returns a true value if this is the case.

  • returnkeys ( KEYLIST )

    After you have added all the wanted widgets to the container, you can add keybindings to each widget to have the container loose its focus. This is done by the returnkeys method. KEYLIST is a list of keys on which the container must loose focus (see also Curses::UI).

  • loadmodule ( CLASS )

    This will load the module for the CLASS. If loading fails, the program will die.

  • onFocus ( CODEREF )

    This method can be used to set the -onfocus event handler (see above) after initialization of the widget.

  • onBlur ( CODEREF )

    This method can be used to set the -onblur event handler (see above) after initialization of the widget.

DEFAULT BINDINGS

Since interacting is not handled by the container itself, but by the contained widgets, this class does not have any key bindings.

SEE ALSO

Curses::UI,

AUTHOR

Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the same terms as perl itself.