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)[source]¶ 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
andexit
. 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 toDefault Text
and is recommended to always be customized, andlabel_ok
, which defaults toOK
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, seeadd_widgets()
for more information.-
activate
()[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Called by the initializer to add all widgets.
Widgets are discovered by searching through the
WIDGETS
class attribute. If a key inWIDGETS
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
()[source]¶ 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)[source]¶ 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 toAre you sure?
.Clicking the confirm button will cause the
confirm
action to trigger, while the cancel button will cause thecancel
action to trigger.-
add_btn_cancel
(label_cancel)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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
andvalue
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
andpercent
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.
-
-
class
peng3d.gui.menus.
AdvancedProgressSubMenu
(name, menu, window, peng, borderstyle=None, font_size=None, font=None, font_color=None, multiline=False, **kwargs)[source]¶ -
addCategory
(*args, **kwargs)[source]¶ Proxy for
addCategory()
.
-
add_progressbar
(label_progressbar)[source]¶ 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
andvalue
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
andpercent
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)[source]¶ Proxy for
deleteCategory()
.
-
updateCategory
(*args, **kwargs)[source]¶ Proxy for
updateCategory()
.
-