Curses:...ontainer(3)

🌸 NAME 🌸

Curses::UI::Container(3) — Create and manipulate container widgets. This is the Curses::UI::Container page from the User Contributed Perl Documentation, and it's basically the group-chat admin for your widgets. 💖

🧬 CLASS HIERARCHY 🧬

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

✨ SYNOPSIS ✨

Okay so here's the vibe-check code, bestie:

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 is a super easy way to manage multiple widgets inside a single "form". Bestie, 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. It's giving widget-herding main character energy. 💅

🎀 STANDARD OPTIONS 🎀

The standard options squad is literally:

• -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 🦋

• -releasefocus — If this option is set, the widgets inside this Container will be part of the focus ordering of the parent widget. This means that when this Container gets the focus, its first widget will be focused. When the focus leaves the last widget inside the Container, it will give the focus back to the parent instead of cycling back to the first widget in this Container. This option is useful to create a sub-class packed with commonly used widgets, making reuse easier. 🦋

💅 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. If you do not need an ID, you may also use an undefined value. The container will automatically create an ID for you.

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 specify the full class name for widgets that are in the Curses::UI hierarchy. It is not necessary to call use CLASS yourself. The add method will call the usemodule method from Curses::UI 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.
• 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, one of the contained widgets will get the focus. The return value of this widget determines what has to be done next. Here are the possible cases:

• The return value is LEAVE_CONTAINER — As soon as a widget returns this value, the container will lose its focus and return the return value and the last pressed key to the caller.
• The return value is STAY_AT_FOCUSPOSITION — The container will not lose focus and the focus will stay at the same widget of the container.
• Any other return value — 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.
• 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.
• 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. No cap. 🌈

👀 SEE ALSO 👀

Curses::UI

💖 AUTHOR 💖

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

Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)

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.

🫶 That's a wrap, bestie — source/version perl v5.42.2, date 2023-07-03. 💖