1.1.10. gui_utilities
This module provides various utility functions specific to the graphical nature of the client application.
1.1.10.1. Data
- GOBJECT_PROPERTY_MAP[source]
The dictionary which maps GObjects to either the names of properties to store text or a tuple which contains a set and get function. If a tuple of two functions is specified the set function will be provided two parameters, the object and the value and the get function will just be provided the object.
1.1.10.2. Functions
- delayed_signal(delay=500)[source]
A decorator to delay the execution of a signal handler to aggregate emission into a single event. This can for example be used to run a handler when a
Gtk.Entry
widget’schanged
signal is emitted but not after every single key press meaning the handler can perform network operations to validate or otherwise process input.Note
The decorated function must be a method. The wrapper installed by this decorator will automatically add an attribute to the class to track invoked instances to ensure the timeout is respected.
New in version 1.14.0.
- Parameters
delay (int) – The delay in milliseconds from the original emission before the handler should be executed.
- glib_idle_add_once(function, *args, **kwargs)[source]
Execute function in the main GTK loop using
GLib.idle_add()
one time. This is useful for threads that need to update GUI data.- Parameters
function (function) – The function to call.
args – The positional arguments to function.
kwargs – The key word arguments to function.
- Returns
The result of the function call.
- glib_idle_add_wait(function, *args, **kwargs)[source]
Execute function in the main GTK loop using
GLib.idle_add()
and block until it has completed. This is useful for threads that need to update GUI data.- Parameters
function (function) – The function to call.
args – The positional arguments to function.
kwargs – The key word arguments to function.
- Returns
The result of the function call.
- glib_idle_add_store_extend(store, things, clear=False, wait=False)[source]
Extend a GTK store object (either
Gtk.ListStore
orGtk.TreeStore
) object usingGLib.idle_add()
. This function is suitable for use in non-main GUI threads for synchronizing data.- Parameters
store (
Gtk.ListStore
,Gtk.TreeStore
) – The GTK storage object to add things to.things (tuple) – The array of things to add to store.
clear (bool) – Whether or not to clear the storage object before adding things to it.
wait (bool) – Whether or not to wait for the operation to complete before returning.
- Returns
Regardless of the wait parameter,
None
is returned.- Return type
None
- gobject_get_value(gobject, gtype=None)[source]
Retrieve the value of a GObject widget. Only objects with corresponding entries present in the
GOBJECT_PROPERTY_MAP
can be processed by this function.
- gobject_set_value(gobject, value, gtype=None)[source]
Set the value of a GObject widget. Only objects with corresponding entries present in the
GOBJECT_PROPERTY_MAP
can be processed by this function.- Parameters
gobject (
GObject.Object
) – The object to set the value for.value – The value to set for the object.
gtype (str) – An explicit type to treat gobject as.
- gobject_signal_accumulator(test=None)[source]
Create an accumulator function for use with GObject signals. All return values will be collected and returned in a list. If provided, test is a callback that will be called with two arguments, the return value from the handler and the list of accumulated return values.
stop = test(retval, accumulated)
- Parameters
test – A callback to test whether additional handler should be executed.
- gobject_signal_blocked(gobject, signal_name)[source]
This is a context manager that can be used with the ‘with’ statement to execute a block of code while signal_name is blocked.
- Parameters
gobject (
GObject.Object
) – The object to block the signal on.signal_name (str) – The name of the signal to block.
- gtk_calendar_get_pydate(gtk_calendar)[source]
Get the Python date from a
Gtk.Calendar
instance. If the day in gtk_calendar is not within the valid range for the specified month, it will be rounded to the closest value (i.e. 0 for unset will become 1 etc.).- Parameters
gtk_calendar (
Gtk.Calendar
) – The calendar to get the date from.- Returns
The date as returned by the calendar’s
get_date()
method.- Return type
- gtk_calendar_set_pydate(gtk_calendar, pydate)[source]
Set the date on a
Gtk.Calendar
instance from a Pythondatetime.date
object.- Parameters
gtk_calendar (
Gtk.Calendar
) – The gtk_calendar to set the date for.pydate (
datetime.date
) – The date to set on the gtk_calendar.
- gtk_combobox_set_entry_completion(combobox)[source]
Add completion for a
Gtk.ComboBox
widget which contains an entry. They combobox’sentry-text-column
property it used to determine which column in its model contains the strings to suggest for completion.New in version 1.14.0.
- Parameters
combobox – The combobox to add completion for.
- Type
Gtk.ComboBox
- gtk_list_store_search(list_store, value, column=0)[source]
Search a
Gtk.ListStore
for a value and return aGtk.TreeIter
to the first match.- Parameters
list_store (
Gtk.ListStore
) – The list store to search.value – The value to search for.
column (int) – The column in the row to check.
- Returns
The row on which the value was found.
- Return type
Gtk.TreeIter
- gtk_listbox_populate_labels(listbox, label_strings)[source]
Formats and adds labels to a listbox. Each label is styled and added as a separate entry.
New in version 1.13.0.
- Parameters
listbox (
Gtk.listbox
) – Gtk Listbox to put the labels in.label_strings (list) – List of strings to add to the Gtk Listbox as labels.
- gtk_listbox_populate_urls(listbox, url_strings, signals=None)[source]
Format and adds URLs to a list box. Each URL is styled and added as a separate entry.
New in version 1.14.0.
Retrieve a menu item from a menu by it’s label. If more than one items share the same label, only the first is returned.
- Parameters
menu (
Gtk.Menu
) – The menu to search for the item in.label (str) – The label to search for in menu.
- Returns
The identified menu item if it could be found, otherwise None is returned.
- Return type
Gtk.MenuItem
Add a new menu item into the existing menu at the path specified in menu_path.
- Parameters
menu (
Gtk.Menu
Gtk.MenuBar
) – The existing menu to add the new item to.menu_path (list) – The labels of submenus to traverse to insert the new item.
menu_item (
Gtk.MenuItem
) – The new menu item to insert.
Create a menu at the given location for an event. This function is meant to be used as the func parameter for the
Gtk.Menu.popup()
method. The event object must be passed in as the first parameter, which can be accomplished usingfunctools.partial()
.- Parameters
event – The event to retrieve the coordinates for.
- gtk_style_context_get_color(sc, color_name, default=None)[source]
Look up a color by it’s name in the
Gtk.StyleContext
specified in sc, and return it as anGdk.RGBA
instance if the color is defined. If the color is not found, default will be returned.- Parameters
sc (
Gtk.StyleContext
) – The style context to use.color_name (str) – The name of the color to lookup.
default (str,
Gdk.RGBA
) – The default color to return if the specified color was not found.
- Returns
The color as an RGBA instance.
- Return type
Gdk.RGBA
- gtk_treesortable_sort_func_numeric(model, iter1, iter2, column_id)[source]
Sort the model by comparing text numeric values with place holders such as 1,337. This is meant to be set as a sorting function using
Gtk.TreeSortable.set_sort_func()
. The user_data parameter must be the column id which contains the numeric values to be sorted.- Parameters
model (
Gtk.TreeSortable
) – The model that is being sorted.iter1 (
Gtk.TreeIter
) – The iterator of the first item to compare.iter2 (
Gtk.TreeIter
) – The iterator of the second item to compare.column_id – The ID of the column containing numeric values.
- Returns
An integer, -1 if item1 should come before item2, 0 if they are the same and 1 if item1 should come after item2.
- Return type
- gtk_treeview_get_column_titles(treeview)[source]
Iterate over a GTK TreeView and return a tuple containing the id and title of each of it’s columns.
- Parameters
treeview (
Gtk.TreeView
) – The treeview instance to retrieve columns from.
- gtk_treeview_selection_to_clipboard(treeview, columns=0)[source]
Copy the currently selected values from the specified columns in the treeview to the users clipboard. If no value is selected in the treeview, then the clipboard is left unmodified. If multiple values are selected, they will all be placed in the clipboard on separate lines.
- gtk_treeview_selection_iterate(treeview)[source]
Iterate over the a treeview’s selected rows.
- Parameters
treeview (
Gtk.TreeView
) – The treeview for which to iterate over.- Returns
The rows which are selected within the treeview.
- Return type
Gtk.TreeIter
- gtk_treeview_set_column_titles(treeview, column_titles, column_offset=0, renderers=None)[source]
Populate the column names of a GTK TreeView and set their sort IDs.
- Parameters
- Returns
A dict of all the
Gtk.TreeViewColumn
objects keyed by their column id.- Return type
- gtk_widget_destroy_children(widget)[source]
Destroy all GTK child objects of widget.
- Parameters
widget (
Gtk.Widget
) – The widget to destroy all the children of.
- show_dialog(message_type, message, parent, secondary_text=None, message_buttons=<enum GTK_BUTTONS_OK of type Gtk.ButtonsType>, use_markup=False, secondary_use_markup=False)[source]
Display a dialog and return the response. The response is dependent on the value of message_buttons.
- Parameters
message_type (
Gtk.MessageType
) – The GTK message type to display.message (str) – The text to display in the dialog.
parent (
Gtk.Window
) – The parent window that the dialog should belong to.secondary_text (str) – Optional subtext for the dialog.
message_buttons (
Gtk.ButtonsType
) – The buttons to display in the dialog box.use_markup (bool) – Whether or not to treat the message text as markup.
secondary_use_markup (bool) – Whether or not to treat the secondary text as markup.
- Returns
The response of the dialog.
- Return type
- show_dialog_exc_socket_error(error, parent, title=None)[source]
Display an error dialog with details regarding a
socket.error
exception that has been raised.- Parameters
error (
socket.error
) – The exception instance that has been raised.parent (
Gtk.Window
) – The parent window that the dialog should belong to.title – The title of the error dialog that is displayed.
- show_dialog_error(*args, **kwargs)[source]
Display an error dialog with
show_dialog()
.
- show_dialog_info(*args, **kwargs)[source]
Display an informational dialog with
show_dialog()
.
- show_dialog_warning(*args, **kwargs)[source]
Display an warning dialog with
show_dialog()
.
- show_dialog_yes_no(*args, **kwargs)[source]
Display a dialog which asks a yes or no question with
show_dialog()
.- Returns
True if the response is Yes.
- Return type
1.1.10.3. Classes
- class GladeDependencies(children=None, top_level=None, name=None)[source]
Bases:
object
A class for defining how objects should be loaded from a GTK Builder data file for use with
GladeGObject
.- children[source]
A tuple of string names or
GladeProxy
instances listing the children widgets to load from the parent.
- class GladeGObjectMeta(*args, **kwargs)[source]
Bases:
type
A meta class that will update the
GladeDependencies.name
value in theGladeGObject.dependencies
attribute of instances if no value is defined.
- class GladeGObject(application)[source]
Bases:
king_phisher.client.gui_utilities._GladeGObject
A base object to wrap GTK widgets loaded from Glade data files. This provides a number of convenience methods for managing the main widget and child widgets. This class is meant to be subclassed by classes representing objects from the Glade data file.
- __init__(application)[source]
- Parameters
application (
Gtk.Application
) – The parent application for this object.
- dependencies = <GladeDependencies name='GladeGObject' >[source]
A
GladeDependencies
instance which defines information for loading the widget from the GTK builder data.
- get_entry_value(entry_name)[source]
Get the value of the specified entry then remove leading and trailing white space and finally determine if the string is empty, in which case return None.
- gobjects[source]
A
FreezableDict
which maps gobjects to their unique GTK Builder id.
- gtk_builder_get(gobject_id, parent_name=None)[source]
Find the child GObject with name gobject_id from the GTK builder.
- objects_load_from_config()[source]
Iterate through
gobjects
and set the GObject’s value from the corresponding value in theconfig
.
- class GladeProxy(destination)[source]
Bases:
object
A class that can be used to load another top level widget from the GTK builder data file in place of a child. This is useful for reusing small widgets as children in larger ones.
- children = ()[source]
A tuple of string names or
GladeProxy
instances listing the children widgets to load from the top level.
- destination[source]
A
GladeProxyDestination
instance describing how this proxied widget should be added to the parent.
- class GladeProxyDestination(method, widget=None, args=None, kwargs=None)[source]
Bases:
object
A class that is used to define how a
GladeProxy
object shall be loaded into a parentGladeGObject
instance. This includes the information such as what container widget in the parent the proxied widget should be added to and what method should be used. The proxied widget will be added to the parent by callingmethod
with the proxied widget as the first argument.- __init__(method, widget=None, args=None, kwargs=None)[source]
- Parameters
method (str) – The method of the container widget to use to add the proxied widget.
widget (str) – The widget name to add the proxied widget to. If this value is
None
, the proxied widget is added to the top level widget.args (tuple) – Position arguments to provide when calling method.
kwargs (dict) – Key word arguments to provide when calling method.