zim.gui.widgets

module documentation

(source)

This module contains a number of custom gtk widgets that are used in the zim gui modules.

These include base clases for windows and dialogs like Window, Dialog, FileDialog, QuestionDialog, ErrorDialog, and Assistant. Especially the Dialog class contains a number of convenience methods.

An important class is te InputForm which is used extensively in the zim gui to layout forms of input fields etc. And the related specialized input widgets like InputEntry, FileEntry, FolderEntry, LinkEntry, PageEntry and NamespaceEntry. These widgets take care of converting specific object types, proper utf-8 encoding etc.

The remaining classes are various widgets used in the gui: Button, IconButton, IconChooserButton, MenuButton, ImageView, SingleClickTreeView and BrowserTreeView.

Unknown Field: newfield
requires	Requires

Class	`Assistant`	Dialog with multi-page input, sometimes also revert to as a "wizard". Similar to `Gtk.Assistent` separate implementation to allow more flexibility in the dialog layout.
Class	`AssistantPage`	Base class for pages in an `Assistant` dialog.
Class	`BrowserTreeView`	No summary
Class	`ConfigDefinitionPaneState`	Undocumented
Class	`ConfigDefinitionPaneToggle`	Undocumented
Class	`Dialog`	No summary
Class	`ErrorDialog`	No summary
Class	`FileDialog`	File Chooser dialog, that allows to browser the file system and select files or folders. Similar to `Gtk.FileChooserDialog` but inherits from `Dialog` instead.
Class	`FileEntry`	Widget to select a file
Class	`FolderEntry`	Widget to select a folder
Class	`FSPathEntry`	Base class for `FileEntry` and `FolderEntry`, handles input of file system paths.
Class	`HMinimizedTabs`	Undocumented
Class	`HPaned`	Undocumented
Class	`IconButton`	Button with a stock icon, but no label.
Class	`IconChooserButton`	No summary
Class	`ImageView`	Widget to show an image, scales the image and sets proper background.
Class	`InputEntry`	No summary
Class	`InputForm`	This class implements a table with input widgets. It takes care of constructing the widgets and lay them out as a well formatted input form.
Class	`LinkEntry`	Widget entering links in zim pages. This widget accepts either zim page paths, file paths and URLs.
Class	`LogFileDialog`	Simple dialog to show a log file
Class	`MenuButton`	No summary
Class	`MessageDialog`	Convenience wrapper for `Gtk.MessageDialog`, should be used for informational popups without an action.
Class	`MinimizedTabs`	Undocumented
Class	`NamespaceEntry`	Widget to select a zim page path as a namespace
Class	`PageEntry`	Widget to select a zim page path
Class	`PanedClass`	Undocumented
Class	`ProgressDialog`	Dialog to show a progress bar for a operation
Class	`QuestionDialog`	Convenience class to prompt the user with Yes/No answer type of questions.
Class	`SingleClickTreeView`	Sub-class of `Gtk.TreeView` that implements single-click navigation.
Class	`StatusPage`	Widget to use e.g. as a placeholder for an empty view
Class	`uistate_property`	Class for uistate get/set attributes
Class	`VMinimizedTabs`	Undocumented
Class	`VPaned`	Undocumented
Class	`Window`	No summary
Class	`WindowSidePane`	Undocumented
Class	`WindowSidePaneWidget`	Base class for widgets that want to integrate nicely in the `WindowSidePane`
Function	`button_set_statusbar_style`	Undocumented
Function	`decode_markup_text`	No summary
Function	`encode_markup_text`	No summary
Function	`format_title`	Formats a window title (in fact just adds " - Zim" to the end).
Function	`get_window`	Undocumented
Function	`gtk_combobox_set_active_text`	No summary
Function	`gtk_entry_completion_match_func`	Undocumented
Function	`gtk_entry_completion_match_func_startswith`	Undocumented
Function	`gtk_notebook_get_active_page`	Returns the active child widget or `None`
Function	`gtk_popup_at_pointer`	Introduced in Gtk 3.22, so wrap our own to be compatible for 3.18 and up
Function	`gtk_window_set_default_icon`	Function to set the zim icon as the default window icon for all gtk windows in this process.
Function	`help_text_factory`	No summary
Function	`input_table_factory`	Function to help with the layout of widgets in tables.
Function	`populate_popup_add_separator`	No summary
Function	`rotate_pixbuf`	No summary
Function	`ScrolledSourceView`	If GTKSourceView was successfullly loaded, this generates a SourceView and initializes it. Otherwise ScrolledTextView will be used as a fallback.
Function	`ScrolledTextView`	Initializes a `Gtk.TextView` with sane defaults for displaying a piece of multiline text and wraps it in a scrolled window
Function	`ScrolledWindow`	No summary
Function	`strip_boolean_result`	Undocumented
Function	`to_utf8_normalized_casefolded`	Convert text to utf8 normalized and casefolded form. @param text: text string to convert @returns: converted text
Function	`widget_set_css`	Undocumented
Constant	`BOTTOM`	Undocumented
Constant	`BOTTOM_PANE`	Undocumented
Constant	`CANCEL_STR`	Undocumented
Constant	`KEYVAL_ESC`	Undocumented
Constant	`KEYVAL_LEFT`	Undocumented
Constant	`KEYVAL_RIGHT`	Undocumented
Constant	`KEYVALS_ASTERISK`	Undocumented
Constant	`KEYVALS_SLASH`	Undocumented
Constant	`LEFT`	Undocumented
Constant	`LEFT_PANE`	Undocumented
Constant	`OK_STR`	Undocumented
Constant	`PANE_POSITIONS`	Undocumented
Constant	`POSITIONS`	Undocumented
Constant	`RIGHT`	Undocumented
Constant	`RIGHT_PANE`	Undocumented
Constant	`TEST_MODE`	Undocumented
Constant	`TEST_MODE_RUN_CB`	Undocumented
Constant	`TOP`	Undocumented
Constant	`TOP_PANE`	Undocumented
Variable	`GtkSource`	Undocumented
Variable	`logger`	Undocumented
Function	`_do_sync_widget_state`	Undocumented
Function	`_do_sync_widget_state_check_active`	Undocumented
Function	`_gtk_popup_at_pointer_backward`	Undocumented
Function	`_hide`	Undocumented
Function	`_show`	Undocumented
Function	`_sync_widget_state`	Undocumented
Variable	`_ref_cache`	Undocumented

def button_set_statusbar_style(button): (source)

Undocumented

def decode_markup_text(text): (source)

Decode text that was encoded with encode_markup_text() and remove any markup tags.

Parameters
text	markup text
Returns
normal text

def encode_markup_text(text): (source)

Encode text such that it can be used in a piece of markup text without causing errors. Needed for all places where e.g. a label depends on user input and is formatted with markup to show it as bold text.

Parameters
text	label text as string
Returns
encoded text

def format_title(title): (source)

Formats a window title (in fact just adds " - Zim" to the end).

def get_window(widget): (source)

Undocumented

def gtk_combobox_set_active_text(combobox, text): (source)

Opposite of Gtk.ComboBox.get_active_text(). Sets the active item based on a string. Will match this string against the list of options and select the correct index.

Raises
`ValueError`	when the string is not found in the list.

def gtk_entry_completion_match_func(completion, key, iter, column): (source)

Undocumented

def gtk_entry_completion_match_func_startswith(completion, key, iter, column): (source)

Undocumented

def gtk_notebook_get_active_page(nb): (source)

Returns the active child widget or None

def gtk_popup_at_pointer(menu, event=None, button=3): (source)

Introduced in Gtk 3.22, so wrap our own to be compatible for 3.18 and up

def gtk_window_set_default_icon(): (source)

Function to set the zim icon as the default window icon for all gtk windows in this process.

def help_text_factory(text): (source)

Create a label with an "info" icon in front of it. Intended for informational text in dialogs.

Parameters
text	the text to display
Returns
a `Gtk.HBox`

def input_table_factory(inputs, table=None): (source)

Function to help with the layout of widgets in tables.

Only use this function directly if you want a completely custom input form. For standard forms see the InputForm class.

Parameters
inputs	a list of inputs. These inputs should be either a tuple of a string and one or more widgets, a single widget, a string, or `None`. For a tuple the lable will be lined out in the first column followed by all the widgets. If a tuple is given and the first item is `None`, the widget will be lined out in the 2nd column. A single widget will be lined out in line with the lables (this is meant for e.g. checkboxes that have the label behind the checkbox as part of the widget). A string will be put as a label on it's own row. Use of markup is assumed. An input that has a `None` value will result in an empty row in the table, separating field above and below.
table	options `Gtk.Table`, if given inputs will be appended to this table
Returns
a `Gtk.Table`

def populate_popup_add_separator(menu, prepend=False): (source)

Convenience function that adds a Gtk.SeparatorMenuItem to a context menu. Checks if the menu already contains items, if it is empty does nothing. Also if the menu already has a seperator in the required place this function does nothing. This helps with building menus more dynamically.

Parameters
menu	the `Gtk.Menu` object for the popup
prepend	if `False` append, if `True` prepend

def rotate_pixbuf(pixbuf): (source)

Rotate the pixbuf to match orientation from EXIF info. This is intended for e.g. photos that have EXIF information that shows how the camera was held.

Returns
a new version of the pixbuf or the pixbuf itself.

def ScrolledSourceView(text=None, syntax=None): (source)

If GTKSourceView was successfullly loaded, this generates a SourceView and initializes it. Otherwise ScrolledTextView will be used as a fallback.

Parameters
text	initial text to show in the view
syntax	this will try to enable syntax highlighting for the given language. If None, no syntax highlighting will be enabled.
Returns
a 2-tuple of a window and a view.

def ScrolledTextView(text=None, monospace=False, **kwarg): (source)

Initializes a Gtk.TextView with sane defaults for displaying a piece of multiline text and wraps it in a scrolled window

Parameters
text	initial text to show in the textview
monospace	when `True` the font will be set to monospaced and line wrapping disabled, use this to display log files etc.
**kwarg	arguments passed on to `ScrolledWindow`
Returns
a 2-tuple of the scrolled window and the textview

def ScrolledWindow(widget, hpolicy=Gtk.PolicyType.AUTOMATIC, vpolicy=Gtk.PolicyType.AUTOMATIC, shadow=Gtk.ShadowType.IN): (source)

Wrap widget in a Gtk.ScrolledWindow and return the resulting widget

Parameters
widget	any Gtk widget
hpolicy	the horizontal scrollbar policy
vpolicy	the vertical scrollbar policy
shadow	the shadow type
Returns
a `Gtk.ScrolledWindow`

def strip_boolean_result(ret): (source)

Undocumented

def to_utf8_normalized_casefolded(text): (source)

Convert text to utf8 normalized and casefolded form.

Parameters
text	text string to convert
Returns
converted text

def widget_set_css(widget, name, css): (source)

Undocumented

BOTTOM: str = (source)

Undocumented

Value

'bottom'

BOTTOM_PANE: str = (source)

Undocumented

Value

'bottom_pane'

CANCEL_STR = (source)

Undocumented

Value

_('_Cancel')

KEYVAL_ESC = (source)

Undocumented

Value

Gdk.keyval_from_name('Escape')

KEYVAL_LEFT = (source)

Undocumented

Value

Gdk.keyval_from_name('Left')

KEYVAL_RIGHT = (source)

Undocumented

Value

Gdk.keyval_from_name('Right')

KEYVALS_ASTERISK = (source)

Undocumented

Value

(Gdk.unicode_to_keyval(ord('*')), Gdk.keyval_from_name('KP_Multiply'))

KEYVALS_SLASH = (source)

Undocumented

Value

(Gdk.unicode_to_keyval(ord('\\')),
 Gdk.unicode_to_keyval(ord('/')),
 Gdk.keyval_from_name('KP_Divide'))

LEFT: str = (source)

Undocumented

Value

'left'

LEFT_PANE: str = (source)

Undocumented

Value

'left_pane'

OK_STR = (source)

Undocumented

Value

_('_OK')

PANE_POSITIONS = (source)

Undocumented

Value

((LEFT_PANE, _('Left Side Pane')),
 (RIGHT_PANE, _('Right Side Pane')),
 (BOTTOM_PANE, _('Bottom Pane')),
 (TOP_PANE, _('Top Pane')))

POSITIONS = (source)

Undocumented

Value

((TOP, _('Top')), (BOTTOM, _('Bottom')), (LEFT, _('Left')), (RIGHT, _('Right')))

RIGHT: str = (source)

Undocumented

Value

'right'

RIGHT_PANE: str = (source)

Undocumented

Value

'right_pane'

TEST_MODE: bool = (source)

Undocumented

Value

False

TEST_MODE_RUN_CB = (source)

Undocumented

Value

None

TOP: str = (source)

Undocumented

Value

'top'

TOP_PANE: str = (source)

Undocumented

Value

'top_pane'

GtkSource = (source)

Undocumented

logger = (source)

Undocumented

def _do_sync_widget_state(widget, a, subject): (source)

Undocumented

def _do_sync_widget_state_check_active(widget, *a): (source)

Undocumented

def _gtk_popup_at_pointer_backward(menu, event, button): (source)

Undocumented

def _hide(widget): (source)

Undocumented

def _show(widget): (source)

Undocumented

def _sync_widget_state(widget, subject, check_active=False): (source)

Undocumented

_ref_cache: dict = (source)

Undocumented