UI::Di...::Menu(3pm)

📦
version 1.21 · 3 versions
, in ubuntu jammy, ubuntu noble

💖 UI::Dialog::Screen::Menu 💖

okay bestie, so this is the perl doc for UI::Dialog::Screen::Menu — part of the User Contributed Perl Documentation crew, and it's literally a wrapper to screen dialogs. no cap. let's get into it 🫶

✨ NAME ✨

UI::Dialog::Screen::Menu — wrapper to screen dialogs. that's it, that's the name, slay 💅

🌸 SYNOPSIS 🌸

use UI::Dialog::Screen::Menu;

# $d is an existing instance of UI::Dialog

my $screen = new UI::Dialog::Screen::Menu ( dialog => $d );
$screen->add_menu_item("This is the label", sub { print "Hello\n"; });

# $rv is 0 if the user canceled, 1 if any menu item was selected.
my $rv = $screen->run();

so like, $d is an existing instance of UI::Dialog, and $rv is 0 if the user canceled, 1 if any menu item was selected. iconic behaviour honestly 🎀

🦋 ABSTRACT 🦋

UI::Dialog::Screen::Menu is a helper class which enables a clean and modular code flow for menu driven applications using UI::Dialog. Using callbacks assigned to menu items, a reactionary model to scripting with UI::Dialog becomes rapidly easy. it's giving actually organized and we're obsessed ✨

💜 DESCRIPTION 💜

UI::Dialog::Screen::Menu is actually "external" to the UI::Dialog core usage. The class simply wraps around an existing UI::Dialog instance for rendering a menu-driven flow of screens.

Using this class, you define a number of screen instances and assign callbacks to each of the menu items. Once defined, simply call run() (or loop() to execute run() indefinitely). When a user selects one of the menu items, the assigned function will be executed. From within those functions, simply call other UI::Dialog::Screen::Menu instances and that's how you branch your user's experience from one screen to the next. See the EXAMPLES 🧚

🌈 EXPORT 🌈

None

⭐ INHERITS ⭐

None

👑 CONSTRUCTOR 👑

new( %options )

EXAMPLE

# Have UI::Dialog::Screen::Menu use an existing UI::Dialog instance
# to render the user interface.
my $s = new( dialog => $d );

# Also accepts UI::Dialog constructor arguments, so that it can create
# it's own instance of UI::Dialog if none is provided.
my $s = new( title => 'Default Title', backtitle => 'Backtitle',
             width => 65, height => 20, listheight => 5,
             order => [ 'zenity', 'xdialog', 'gdialog' ] );

DESCRIPTION

This is the Class Constructor method. It accepts a list of key => value pairs and uses them as the defaults when interacting with the various widgets. main character energy fr fr 💖

RETURNS

A blessed object reference of the UI::Dialog::Screen::Menu class. 🎀

OPTIONS

The (...)'s after each option indicate the default for the option. An * denotes support by all the widget methods on a per-use policy defaulting to the values decided during object creation.

  • dialog = UI::Dialog (undef)
  • debug = 0,1,2 (0)
  • order = [ zenity, xdialog, gdialog, kdialog, cdialog, whiptail, ascii ] (as indicated)
  • PATH = [ /bin, /usr/bin, /usr/local/bin, /opt/bin ] (as indicated)
  • backtitle = "backtitle" ('') *
  • title = "title" ('') *
  • beepbefore = 0,1 (0) *
  • beepafter = 0,1 (0) *
  • height = \d+ (20) *
  • width = \d+ (65) *
  • listheight = \d+ (5) *

💅 STATE METHODS 💅

run( )

EXAMPLE

my $rv = $s->run();

DESCRIPTION

Render the screen menu immediately. This method blocks until the user input has been received and acted upon. lowkey it just sits there and waits for you, respectfully 🫶

RETURNS

TRUE if the user selected an item from the menu, FALSE otherwise.

loop( )

EXAMPLE

$s->loop();

DESCRIPTION

Calls the run() method immediately. Once run() completes it's execution, the loop() decides whether or not to display again. If the return value of run() is TRUE, the loop() will continue. If the use pressed Cancel (or Escape) or any other action other than one of the menu items; the loop() will end. The loop() will also end if the break_loop() method is called.

RETURNS

TRUE if the user selected an item from the menu, FALSE otherwise.

is_looping( )

EXAMPLE

if ($s->is_looping()) {
    print "Currently in a UI::Dialog::Screen::Menu loop\n";
}

DESCRIPTION

Returns TRUE if the given screen is in a menu loop(), FALSE otherwise. vibe check for your loop bestie ✨

RETURNS

a single SCALAR.

break_loop( )

EXAMPLE

$s->break_loop();

DESCRIPTION

Flags the screen menu to stop looping. This does not close or otherwise clear the screen. This simply flags the loop to exit at the end of it's current run.

RETURNS

None.

🌸 SCREEN METHODS 🌸

add_menu_item( )

EXAMPLE

my $index = $s->add_menu_item( "Menu Item Label", \%some_function );

DESCRIPTION

Append a new item to the menu list. 💖

RETURNS

Returns the list index (starting from 0) of the item that was just appended to the list.

get_menu_items( )

EXAMPLE

my @items = $s->get_menu_items();

DESCRIPTION

Returns an array of hashrefs. Each hash contains a "label" and "func" key/value pairs.

RETURNS

An ARRAY.

del_menu_item( )

EXAMPLE

my $old_item = $d->del_menu_item( $index );

DESCRIPTION

Remove a specific item from the menu, addressed by it's list index (starting from 0), and return the menu item as a hashref.

RETURNS

A HASH containing the 'label' and 'func' of the menu item that was just removed from the menu list.

set_menu_item( )

EXAMPLE

# Modify the 'label' and 'func' for a specific menu item
my $original_item = $s->set_menu_item( $index, $label, $func );

# Modify just the label of a menu item
my $original_item = $s->set_menu_item( $index, $label, undef );

# Modify just the func of a menu item
my $original_item = $s->set_menu_item( $index, undef, $func );

# Effectively do nothing
my $original_item = $s->set_menu_item( $index, undef, undef );

DESCRIPTION

Modify the menu item addressed by the given index (starting from 0). If the 'label' and/or 'func' arguments are undef then the previous value is kept. cute little "only change what you asked me to change" moment, we love a respectful API 🎀

RETURNS

A HASH of the original values for the modified menu item.

🦋 EXAMPLE USAGE 🦋

The below example assumed that $d is an instances of UI::Dialog.

# Create our first screen
my $s1 = new UI::Dialog::Screen::Menu ( dialog => $d );
$s1->add_menu_item( "Just an option", \&some_function );

# Add a menu item that updates it's own label every time
# it is selected.
our $counter = 0;
$s1->add_menu_item
 ( "Counter: ".$counter,
   sub {
     my ($self,$dialog,$index) = @_;
     $counter++;
     $self->set_menu_item($index,"Counter: ".$counter, undef);
   }
 );

# Create a second screen
my $s2 = new UI::Dialog::Screen::Menu ( dialog => $d );
$s2->add_menu_item( "Another item", \&another_function );

# Link the second screen to an option of the first
$s1->add_menu_item( "Goto Screen 2", sub { $s2->loop(); } );

# Start a menu loop and actually display the first screen
$s1->loop();

Users can get to second menu from selecting the third item on the first menu screen. As long as the user continues to select items from the second menu, it will continue to loop. If the user cancels the second screen, the will return to the first which will itself continue to loop. it's giving nested menu inception and honestly? iconic 🌈

💖 SEE ALSO 💖

PERLDOC

  • UI::Dialog
  • UI::Dialog::GNOME
  • UI::Dialog::KDE
  • UI::Dialog::Console
  • UI::Dialog::Screen::Druid
  • UI::Dialog::Backend
  • UI::Dialog::Backend::ASCII
  • UI::Dialog::Backend::CDialog
  • UI::Dialog::Backend::GDialog
  • UI::Dialog::Backend::KDialog
  • UI::Dialog::Backend::Nautilus
  • UI::Dialog::Backend::Whiptail
  • UI::Dialog::Backend::XDialog
  • UI::Dialog::Backend::XOSD
  • UI::Dialog::Backend::Zenity

MAN FILES

dialog(1), whiptail(1), zenity(1), gdialog(1), Xdialog(1), osd_cat(1), kdialog(1) and nautilus(1)

💀 BUGS 💀

Please email the author with any bug reports. Include the name of the module in the subject line. (yes bestie, put the module name in the subject line, they will find you faster, iykyk 🔥)

🌟 AUTHOR 🌟

Kevin C. Krinke, <kevin@krinke.ca>

Copyright (C) 2004-2016  Kevin C. Krinke <kevin@krinke.ca>

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA

and that's the whole page bestie 🫶 this one's from perl v5.28.0, dated 2018-10-27, living in the User Contributed Perl Documentation collection as UI::Di...::Menu(3pm). go build something with a menu in it, you're gonna ate 💅✨

📦 where this page comes from