peng3d.gui.menus - Menus and Dialogs

Menus are special submenus that act like modal dialogs.

They include glue code that automatically switches back to the previous submenu after they are left. Note that this will cuase the SubMenu.on_enter() method to be called again.

Since these menus are internally implemented as submenus, they are specific to their Menu, which must be active to be able to use the dialog.

Customization

Menus are customizable via several different means.

If you just want to change the appearance or label of a part of the menu, you can use keyword arguments while initializing the class. For example, setting the label_main argument to the string Hello World! the main label or title of the dialog will now display Hello World! instead of its default value. What exact arguments are supported differs from dialog to dialog.

Note that sometimes specific labels are supported, but not used by default. Just setting these to anything may cause GUI components to be rendered that should not be there.

It is also possible for most of these values to be set on-the-fly via properties on the object they belong to.

For example, the DialogSubMenu.label_main property may be set to change the main label even while the dialog is active.

Note that the values accessible via keyword arguments and properties may differ. This depends on the dialog implementing them.

For clarity, these keyword arguments will from now on be called “labels”. This also includes labels that are not strictly text, like the maximum value of a progressbar.

class peng3d.gui.menus.DialogSubMenu(name, menu, window, peng, borderstyle=None, font_size=None, font=None, font_color=None, multiline=False, **kwargs)

Base Dialog Class.

This class acts as a base class for all other dialog submenus.

When the dialog is entered, the prev_submenu attribute will be set to the name of the previous submenu. This attribute is later used when exiting the dialog.

Dialog submenus also support the basic actions used by all submenus, e.g. enter and exit. Additionally, many dialogs also add actions for whenever a label is changed or the dialog is exited through a special means, e.g. pressing a specific button of multiple presented.

If used by itself, it will display a text centered on the screen with a button below it. Clicking the button will cause the dialog to exit and also the additional click_ok action to be fired.

The labels supported by default are label_main, which defaults to Default Text and is recommended to always be customized, and label_ok, which defaults to OK and may be left as-is.

Subclasses may override these defaults by setting the keys of the same name in the DEFAULT_LABELS class attribute. Note that any unchanged labels must also be declared when overwriting any labels, or they may not be displayed.

Widgets and their initializers are stored in the WIDGETS class attribute, see add_widgets() for more information.

activate()

Helper method to enter the dialog.

Calling this method will simply cause the dialog to become the active submenu.

Note that is not necessary to call this method over changeSubMenu(), as the storing of the previous submenu is done elsewhere.

add_btn_ok(label_ok)

Adds an OK button to allow the user to exit the dialog.

This widget can be triggered by setting the label label_ok to a string.

This widget will be mostly centered on the screen, but below the main label by the double of its height.

add_label_main(label_main)

Adds the main label of the dialog.

This widget can be triggered by setting the label label_main to a string.

This widget will be centered on the screen.

add_widgets(**kwargs)

Called by the initializer to add all widgets.

Widgets are discovered by searching through the WIDGETS class attribute. If a key in WIDGETS is also found in the keyword arguments and not none, the function with the name given in the value of the key will be called with its only argument being the value of the keyword argument.

For more complex usage scenarios, it is also possible to override this method in a subclass, but the original method should always be called to ensure compatibility with classes relying on this feature.

exitDialog()

Helper method that exits the dialog.

This method will cause the previously active submenu to activate.

label_main

Property that proxies the label_main label.

Setting this property will cause the label_main_change action to trigger.

Note that trying to access this property if the widget is not used may cause an error.

label_ok

Property that proxies the label_ok label.

Setting this property will cause the label_ok_change action to trigger.

Note that trying to access this property if the widget is not used may cause an error.

class peng3d.gui.menus.ConfirmSubMenu(name, menu, window, peng, borderstyle=None, font_size=None, font=None, font_color=None, multiline=False, **kwargs)

Dialog that allows the user to confirm or cancel an action.

By default, the OK button will be hidden and the label_main will be set to Are you sure?.

Clicking the confirm button will cause the confirm action to trigger, while the cancel button will cause the cancel action to trigger.

add_btn_cancel(label_cancel)

Adds a cancel button to let the user cancel whatever choice they were given.

This widget can be triggered by setting the label label_cancel to a string.

This widget will be positioned slightly below the main label and to the right of the confirm button.

add_btn_confirm(label_confirm)

Adds a confirm button to let the user confirm whatever action they were presented with.

This widget can be triggered by setting the label label_confirm to a string.

This widget will be positioned slightly below the main label and to the left of the cancel button.

label_cancel

Property that proxies the label_cancel label.

Setting this property will cause the label_cancel_change action to trigger.

Note that trying to access this property if the widget is not used may cause an error.

label_confirm

Property that proxies the label_confirm label.

Setting this property will cause the label_confirm_change action to trigger.

Note that trying to access this property if the widget is not used may cause an error.

class peng3d.gui.menus.TextSubMenu(name, menu, window, peng, borderstyle=None, timeout=10, **kwargs)

Dialog without user interaction that can automatically exit after a certain amount of time.

This dialog accepts the timeout keyword argument, which may be set to any time in seconds to delay before exiting the dialog. A value of -1 will cause the dialog to never exit on its own.

Note that the user will not be able to exit this dialog and may believe the program is hanging if not assured otherwise. It is thus recommended to use the ProgressSubMenu dialog instead, especially for long-running operations.

class peng3d.gui.menus.ProgressSubMenu(name, menu, window, peng, borderstyle=None, font_size=None, font=None, font_color=None, multiline=False, **kwargs)

Dialog without user interaction displaying a progressbar.

By default, the progressbar will range from 0-100, effectively a percentage.

The auto_exit attribute may be set to control whether or not the dialog will exit automatically when the maximum value is reached.

add_progressbar(label_progressbar)

Adds a progressbar and label displaying the progress within a certain task.

This widget can be triggered by setting the label label_progressbar to a string.

The progressbar will be displayed centered and below the main label. The progress label will be displayed within the progressbar.

The label of the progressbar may be a string containing formatting codes which will be resolved via the format() method.

Currently, there are six keys available:

n and value are the current progress rounded to 4 decimal places.

nmin is the minimum progress value rounded to 4 decimal places.

nmax is the maximum progress value rounded to 4 decimal places.

p and percent are the percentage value that the progressbar is completed rounded to 4 decimal places.

By default, the progressbar label will be {percent}% displaying the percentage the progressbar is complete.

auto_exit = False

Controls whether or not the dialog will exit automatically after the maximum value has been reached.

label_progressbar

Property that proxies the label_progressbar label.

Setting this property will cause the progressbar label to be recalculated.

Note that setting this property if the widget has not been initialized may cause various errors to occur.

progress_n

Property that proxies the progress_n label.

Setting this property will cause the progressbar label to be recalculated.

Additionally, if the supplied value is higher than the maximum value and auto_exit is true, the dialog will exit.

progress_nmax

Property that proxies the progress_nmax label.

Setting this property will cause the progressbar label to be recalculated.

Note that setting this property if the widget has not been initialized may cause various errors to occur.

progress_nmin

Property that proxies the progress_nmin label.

Setting this property will cause the progressbar label to be recalculated.

Note that setting this property if the widget has not been initialized may cause various errors to occur.

update_progressbar()

Updates the progressbar by re-calculating the label.

It is not required to manually call this method since setting any of the properties of this class will automatically trigger a re-calculation.

class peng3d.gui.menus.AdvancedProgressSubMenu(name, menu, window, peng, borderstyle=None, font_size=None, font=None, font_color=None, multiline=False, **kwargs)

addCategory(*args, **kwargs)

Proxy for addCategory().

add_progressbar(label_progressbar)

Adds a progressbar and label displaying the progress within a certain task.

This widget can be triggered by setting the label label_progressbar to a string.

The progressbar will be displayed centered and below the main label. The progress label will be displayed within the progressbar.

The label of the progressbar may be a string containing formatting codes which will be resolved via the format() method.

Currently, there are six keys available:

n and value are the current progress rounded to 4 decimal places.

nmin is the minimum progress value rounded to 4 decimal places.

nmax is the maximum progress value rounded to 4 decimal places.

p and percent are the percentage value that the progressbar is completed rounded to 4 decimal places.

By default, the progressbar label will be {percent}% displaying the percentage the progressbar is complete.

deleteCategory(*args, **kwargs)

Proxy for deleteCategory().

updateCategory(*args, **kwargs)

Proxy for updateCategory().