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

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)

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’s changed 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)

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)

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)

Extend a GTK store object (either Gtk.ListStore or Gtk.TreeStore) object using GLib.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)

Retrieve 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 retrieve the value for.
• gtype (str) – An explicit type to treat gobject as.

Returns:

The value of gobject.

Return type:

str

gobject_set_value(gobject, value, gtype=None)

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)

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)

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)

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:datetime.date

gtk_calendar_set_pydate(gtk_calendar, pydate)

Set the date on a Gtk.Calendar instance from a Python datetime.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)

Add completion for a Gtk.ComboBox widget which contains an entry. They combobox’s entry-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)

Search a Gtk.ListStore for a value and return a Gtk.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)

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)

Format and adds URLs to a list box. Each URL is styled and added as a separate entry.

New in version 1.14.0.

Parameters:

• listbox (Gtk.listbox) – Gtk Listbox to put the labels in.
• url_strings (list) – List of URL strings to add to the Gtk Listbox as labels.
• signals (dict) – A dictionary, keyed by signal names to signal handler functions for the labels added to the listbox.

gtk_menu_get_item_by_label(menu, label)

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

gtk_menu_insert_by_path(menu, menu_path, menu_item)

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.

gtk_menu_position(event, *args)

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 using functools.partial().

Parameters:event – The event to retrieve the coordinates for.

gtk_style_context_get_color(sc, color_name, default=None)

Look up a color by it’s name in the Gtk.StyleContext specified in sc, and return it as an Gdk.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_sync()

Wait while all pending GTK events are processed.

gtk_treesortable_sort_func_numeric(model, iter1, iter2, column_id)

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:

int

gtk_treeview_get_column_titles(treeview)

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)

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.

Parameters:

• treeview (Gtk.TreeView) – The treeview instance to get the selection from.
• column (int, list, tuple) – The column numbers to retrieve the value for.

gtk_treeview_selection_iterate(treeview)

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)

Populate the column names of a GTK TreeView and set their sort IDs.

Parameters:

• treeview (Gtk.TreeView) – The treeview to set column names for.
• column_titles (list) – The names of the columns.
• column_offset (int) – The offset to start setting column names at.
• renderers (list) – A list containing custom renderers to use for each column.

Returns:

A dict of all the Gtk.TreeViewColumn objects keyed by their column id.

Return type:

dict

gtk_widget_destroy_children(widget)

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=<king_phisher.utilities.Mock object>, use_markup=False, secondary_use_markup=False)

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:

int

show_dialog_exc_socket_error(error, parent, title=None)

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)

Display an error dialog with show_dialog().

show_dialog_info(*args, **kwargs)

Display an informational dialog with show_dialog().

show_dialog_warning(*args, **kwargs)

Display an warning dialog with show_dialog().

show_dialog_yes_no(*args, **kwargs)

Display a dialog which asks a yes or no question with show_dialog().

Returns:True if the response is Yes. Return type:bool

which_glade()

Locate the glade data file which stores the UI information in a Gtk Builder format.

Returns:The path to the glade data file. Return type:str

1.1.10.3. Classes

class FileMonitor(path, on_changed)

Bases: object

Monitor a file for changes.

__init__(path, on_changed)

Parameters:

• path (str) – The path to monitor for changes.
• on_changed (function) – The callback function to be called when changes are detected.

class GladeDependencies(children=None, top_level=None, name=None)

Bases: object

A class for defining how objects should be loaded from a GTK Builder data file for use with GladeGObject.

__init__(children=None, top_level=None, name=None)

Initialize self. See help(type(self)) for accurate signature.

children

A tuple of string names or GladeProxy instances listing the children widgets to load from the parent.

name

The string of the name of the top level parent widget to load.

top_level

A tuple of string names listing additional top level widgets to load such as images.

class GladeGObjectMeta(*args, **kwargs)

Bases: type

A meta class that will update the GladeDependencies.name value in the GladeGObject.dependencies attribute of instances if no value is defined.

class assigned_name

Bases: str

A type subclassed from str that is used to define names which have been automatically assigned by this class.

class GladeGObject(application)

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)

Parameters:application (Gtk.Application) – The parent application for this object.

application = None

The parent Gtk.Application instance.

config = None

A reference to the King Phisher client configuration.

config_prefix = ''

A prefix to be used for keys when looking up value in the config.

dependencies = <GladeDependencies name='GladeGObject' >

A GladeDependencies instance which defines information for loading the widget from the GTK builder data.

destroy()

Call destroy() on the top-level GTK Widget.

get_entry_value(entry_name)

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.

Parameters:entry_name (str) – The name of the entry to retrieve text from. Returns:Either the non-empty string or None. Return type:None, str

gobjects = None

A FreezableDict which maps gobjects to their unique GTK Builder id.

gtk_builder = None

A Gtk.Builder instance used to load Glade data with.

gtk_builder_get(gobject_id, parent_name=None)

Find the child GObject with name gobject_id from the GTK builder.

Parameters:

• gobject_id (str) – The object name to look for.
• parent_name (str) – The name of the parent object in the builder data file.

Returns:

The GObject as found by the GTK builder.

Return type:

GObject.Object

hide()

Call hide() on the top-level GTK Widget.

objects_load_from_config()

Iterate through gobjects and set the GObject’s value from the corresponding value in the config.

objects_persist = True

Whether objects should be automatically loaded from and saved to the configuration.

objects_save_to_config()

parent

show()

Call show() on the top-level GTK Widget.

show_all()

Call show_all() on the top-level GTK Widget.

top_gobject = 'gobject'

The name of the attribute to set a reference of the top level GObject to.

class GladeProxy(destination)

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.

__init__(destination)

Initialize self. See help(type(self)) for accurate signature.

children = ()

A tuple of string names or GladeProxy instances listing the children widgets to load from the top level.

destination

A GladeProxyDestination instance describing how this proxied widget should be added to the parent.

name = None

The string of the name of the top level widget to load.

class GladeProxyDestination(method, widget=None, args=None, kwargs=None)

Bases: object

A class that is used to define how a GladeProxy object shall be loaded into a parent GladeGObject 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 calling method with the proxied widget as the first argument.

__init__(method, widget=None, args=None, kwargs=None)

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.

args

Arguments to append after the proxied child instance when calling method.

kwargs

Key word arguments to append after the proxied child instance when calling method.

method

The method of the parent widget that should be called to add the proxied child.

widget

The name of the parent widget for this proxied child.