zim.gui.widgets.Dialog

class documentation

class Dialog(Gtk.Dialog, ConnectorMixin): (source)

View In Hierarchy

Sub-class of Gtk.Dialog with a number of convenience methods to create dialogs. Also takes care of registering dialogs with the main interface object, so plugins can hook into them. Intended as base class for all input dialogs in zim. (See ErrorDialog, QuestionDialog, MessageDialog and FileDialog for other dialog types).

A minimal sub-class should implement a constructor which calls Dialog.__init__() and Dialog.add_form() to defined the dialog, and implements do_response_ok() to handle the result.

The Dialog class takes care of calling ConnecterMixin.disconnect_all() when it is destroyed. So sub-classes can use the ConnectorMixin methods and all callbacks will be cleaned up after the dialog.

Class Method	`unique`	No summary
Method	`__init__`	Constructor.
Method	`add_extra_button`	No summary
Method	`add_form`	Convenience method to construct a form with input widgets and add them to the dialog. See `InputForm.add_inputs()` for details.
Method	`add_help_text`	Adds a label with an info icon in front of it. Intended for informational text in dialogs. @param text: help text
Method	`add_text`	Adds a label to the dialog Also see `add_help_text()` for another style option. @param text: dialog text
Method	`assert_response_ok`	No summary
Method	`do_response`	Undocumented
Method	`do_response_cancel`	Handler called when the user clicks the "Cancel" button.
Method	`do_response_ok`	Handler called when the user clicks the "OK" button (or an equivalent button)
Method	`get_input`	Method used in test suite to get "interactive" inputs
Method	`get_input_enabled`	Undocumented
Method	`on_destroy`	Undocumented
Method	`present`	Undocumented
Method	`response_ok`	Trigger the response signal with response type 'OK'.
Method	`run`	Wrapper for `Gtk.Dialog.run()`, also calls `show_all()` @returns: `self.result`
Method	`save_uistate`	Method when the dialog is about to exit or hide and wants to save the uistate. Sub-classes implementing this method should use it to set additional state parameter in `self.uistate`.
Method	`set_help`	Set the name of the manual page with help for this dialog. Setting this will add a "help" button to the dialog. @param pagename: the manual page name
Method	`set_input`	No summary
Method	`show`	Undocumented
Method	`show_all`	Undocumented
Method	`show_help`	Show a help page @param page: the manual page, if `None` the page as set with `set_help()` is used
Instance Variable	`destroyed`	when `True` the dialog is already destroyed
Instance Variable	`form`	`InputForm` added by `add_form()`
Instance Variable	`help_page`	Undocumented
Instance Variable	`result`	result to be returned by `run()`
Instance Variable	`uistate`	`ConfigDict` to store state of the dialog, persistent per notebook. The size and position of the dialog are stored as automatically in this dict already.
Instance Variable	`vbox`	`Gtk.VBox` for main widgets of the dialog
Instance Variable	`_no_ok_action`	Undocumented

Inherited from ConnectorMixin:

Method	`connectto`	Connect to signals of another object E.g.:
Method	`connectto_all`	Convenience method to combine multiple calls to `connectto()`.
Method	`disconnect_all`	Disconnect all signals that have been connected with `connectto` and friends. Typically called when you want to destroy this object.
Method	`disconnect_from`	Disc all signals that have been connected with `connectto` and friends to a specific object.
Method	`_disconnect_from`	Undocumented
Instance Variable	`_connected_signals`	Undocumented

@classmethod
def unique(klass, handler, *args, **opts): (source)

Constructor which ensures there is only one instance of this dialog at a time. It implements a singleton pattern by installing a weak reference in the handler object. If there is an dialog active which is not yet destroyed, this dialog is returned, otherwise a new dialog is created.

Typically you can use this as:

        dialog = MyDialog.unique(parent, somearg)
        dialog.present()

Parameters
klass	Undocumented
handler	the object constructing the dialog
*args	arguments to pass to the dialog constructor
**opts	arguments to pass to the dialog constructor
Note
when a dialog already existed the arguments provided to this constructor are not used

def __init__(self, parent, title, buttons=Gtk.ButtonsType.OK_CANCEL, button=None, use_default_button=False, help_text=None, help=None, defaultwindowsize=(-1, -1)): (source)

overridden in zim.gui.applications.AddApplicationDialog, zim.gui.applications.CustomizeOpenWithDialog, zim.gui.customtools.CustomToolManagerDialog, zim.gui.customtools.EditCustomToolDialog, zim.gui.mainwindow.OpenPageDialog, zim.gui.notebookdialog.AddNotebookDialog, zim.gui.notebookdialog.NotebookDialog, zim.gui.pageview.EditImageDialog, zim.gui.pageview.FindAndReplaceDialog, zim.gui.pageview.InsertDateDialog, zim.gui.pageview.InsertLinkDialog, zim.gui.pageview.MoveTextDialog, zim.gui.pageview.NewFileDialog, zim.gui.pageview.PromptExistingFileDialog, zim.gui.pageview.WordCountDialog, zim.gui.preferencesdialog.PluginConfigureDialog, zim.gui.preferencesdialog.PreferencesDialog, zim.gui.propertiesdialog.PropertiesDialog, zim.gui.recentchangesdialog.RecentChangesDialog, zim.gui.searchdialog.SearchDialog, zim.gui.templateeditordialog.PromptNameDialog, zim.gui.templateeditordialog.TemplateEditorDialog, zim.gui.uiactions.DeletePageDialogBase, zim.gui.uiactions.MovePageDialog, zim.gui.uiactions.NewPageDialog, zim.gui.widgets.Assistant, zim.gui.widgets.FileDialog, zim.gui.widgets.LogFileDialog, zim.plugins.attachmentbrowser.filerenamedialog.FileRenameDialog, zim.plugins.base.imagegenerator.ImageGeneratorDialog, zim.plugins.commandpalette.ZimCommandPaletteDialog, zim.plugins.insertsymbol.InsertSymbolDialog, zim.plugins.linkmap.LinkMapDialog, zim.plugins.quicknote.QuickNoteDialog, zim.plugins.screenshot.InsertScreenshotDialog, zim.plugins.sourceview.InsertCodeBlockDialog, zim.plugins.tableeditor.EditTableDialog, zim.plugins.versioncontrol.SaveVersionDialog, zim.plugins.versioncontrol.TextDialog, zim.plugins.versioncontrol.VersionControlInitDialog, zim.plugins.versioncontrol.VersionsDialog

Constructor.

Parameters
parent	either a parent gtk widget or `None`. Only used to set the dialog on top of the right parent window
title	the dialog title
buttons	a constant controlling what kind of buttons the dialog will have. One of: `None` or `Gtk.ButtonsType.NONE`: for dialogs taking care of constructing the buttons themselves `Gtk.ButtonsType.OK_CANCEL`: Render Ok and Cancel `Gtk.ButtonsType.CLOSE`: Only set a Close button
button	a label to use instead of the default 'Ok' button
use_default_button	Undocumented
help_text	set the help text, see `add_help_text()`
help	pagename for a manual page, see `set_help()`
defaultwindowsize	default window size in pixels

def add_extra_button(self, button, pack_start=True): (source)

Add a button to the action area at the bottom of the dialog. Packs the button in the list of primary buttons (by default these are in the lower right of the dialog)

Parameters
button	the `Gtk.Button` (or other widget)
pack_start	if `True` pack to the left (towards the middle of the dialog), if `False` pack to the right.

def add_form(self, inputs, values=None, depends=None, trigger_response=True, notebook=None): (source)

Convenience method to construct a form with input widgets and add them to the dialog. See InputForm.add_inputs() for details.

Parameters
inputs	list with input definitions
values	initial values for the inputs
depends	dict with dependencies between inputs
trigger_response	if `True` pressing `<Enter>` in the last entry widget will immediatly call `response_ok()`. Set to `False` if more forms will follow in the same dialog.
notebook	Undocumented

def add_help_text(self, text): (source)

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

Parameters
text	help text

def add_text(self, text): (source)

Adds a label to the dialog Also see add_help_text() for another style option.

Parameters
text	dialog text

def assert_response_ok(self): (source)

overridden in zim.gui.widgets.Assistant

Like response_ok(), but raise an error when do_response_ok returns False. Also it explicitly does not handle errors in do_response_ok. Intended for use by the test suite.

Returns
`self.result`
Raises
`AssertionError`	if `do_response_ok` returns `False`

def do_response(self, id): (source)

overridden in zim.gui.pageview.FindAndReplaceDialog, zim.gui.widgets.Assistant, zim.plugins.quicknote.QuickNoteDialog

Undocumented

def do_response_cancel(self): (source)

overridden in zim.gui.preferencesdialog.PreferencesDialog, zim.plugins.tableeditor.EditTableDialog

Handler called when the user clicks the "Cancel" button.

Returns
`True` if the dialog can be destroyed close. Returning `False` will keep the dialog open.
Note
this method is not called when the dialog is closed using e.g. the "[x]" button in the window decoration. It is only used when the user explicitly clicks "Cancel".
Unknown Field: implementation
can be implemented by sub-classes that have an "Cancel" button

def do_response_ok(self): (source)

overridden in zim.gui.applications.AddApplicationDialog, zim.gui.customtools.EditCustomToolDialog, zim.gui.exportdialog.ExportDialog, zim.gui.mainwindow.OpenPageDialog, zim.gui.notebookdialog.AddNotebookDialog, zim.gui.notebookdialog.NotebookDialog, zim.gui.pageview.EditImageDialog, zim.gui.pageview.InsertDateDialog, zim.gui.pageview.InsertLinkDialog, zim.gui.pageview.MoveTextDialog, zim.gui.pageview.NewFileDialog, zim.gui.pageview.PromptExistingFileDialog, zim.gui.preferencesdialog.PluginConfigureDialog, zim.gui.preferencesdialog.PreferencesDialog, zim.gui.propertiesdialog.PropertiesDialog, zim.gui.templateeditordialog.PromptNameDialog, zim.gui.uiactions.DeletePageDialog, zim.gui.uiactions.MovePageDialog, zim.gui.uiactions.NewPageDialog, zim.gui.uiactions.TrashPageDialog, zim.gui.widgets.FileDialog, zim.plugins.attachmentbrowser.filerenamedialog.FileRenameDialog, zim.plugins.base.imagegenerator.ImageGeneratorDialog, zim.plugins.commandpalette.ZimCommandPaletteDialog, zim.plugins.insertsymbol.InsertSymbolDialog, zim.plugins.quicknote.QuickNoteDialog, zim.plugins.screenshot.InsertScreenshotDialog, zim.plugins.sourceview.InsertCodeBlockDialog, zim.plugins.tableeditor.EditTableDialog, zim.plugins.versioncontrol.SaveVersionDialog, zim.plugins.versioncontrol.VersionControlInitDialog

Handler called when the user clicks the "OK" button (or an equivalent button)

Returns
`True` if successfull and the dialog can close. Returns `False` if e.g. input is not valid, this will keep the dialog open.
Unknown Field: implementation
must be implemented by sub-classes that have an "OK" button

def get_input(self, key): (source)

Method used in test suite to get "interactive" inputs

def get_input_enabled(self, key): (source)

Undocumented

def on_destroy(self): (source)

Undocumented

def present(self): (source)

Undocumented

def response_ok(self): (source)

Trigger the response signal with response type 'OK'.

def run(self): (source)

overridden in zim.gui.widgets.Assistant, zim.plugins.insertsymbol.InsertSymbolDialog, zim.plugins.quicknote.QuickNoteDialog

Wrapper for Gtk.Dialog.run(), also calls show_all()

Returns
`self.result`

def save_uistate(self): (source)

overridden in zim.gui.pageview.InsertDateDialog, zim.plugins.quicknote.QuickNoteDialog, zim.plugins.versioncontrol.VersionsDialog

Method when the dialog is about to exit or hide and wants to save the uistate. Sub-classes implementing this method should use it to set additional state parameter in self.uistate.

Unknown Field: implementation
can be implemented by sub-classes that have some additional uistate to save

def set_help(self, pagename): (source)

Set the name of the manual page with help for this dialog. Setting this will add a "help" button to the dialog.

Parameters
pagename	the manual page name

def set_input(self, **fields): (source)

overridden in zim.gui.pageview.FindAndReplaceDialog

Method used in test suite to set "interactive" inputs

Parameters
**fields	key value pairs of inputs to set
Raises
`KeyError`	if a key is not recognized
`ValueError`	if the value is of the wrong type and cannot be converted by the widget
`AssertionError`	if a key is recognized, but the input is not enabled for interactive input - e.g. widget insensitive or hidden

def show(self): (source)

overridden in zim.plugins.quicknote.QuickNoteDialog

Undocumented

def show_all(self): (source)

overridden in zim.gui.notebookdialog.NotebookDialog, zim.gui.pageview.NewFileDialog

Undocumented

def show_help(self, page=None): (source)

overridden in zim.gui.notebookdialog.NotebookDialog

Show a help page

Parameters
page	the manual page, if `None` the page as set with `set_help()` is used

destroyed: bool = (source)

when True the dialog is already destroyed

form = (source)

overridden in zim.gui.propertiesdialog.PropertiesDialog, zim.plugins.quicknote.QuickNoteDialog

InputForm added by add_form()

help_page = (source)

Undocumented

result = (source)

overridden in zim.gui.applications.AddApplicationDialog, zim.gui.customtools.EditCustomToolDialog, zim.gui.notebookdialog.AddNotebookDialog, zim.gui.notebookdialog.NotebookDialog, zim.gui.pageview.NewFileDialog, zim.gui.pageview.PromptExistingFileDialog, zim.gui.templateeditordialog.PromptNameDialog, zim.gui.uiactions.TrashPageDialog, zim.gui.widgets.FileDialog, zim.plugins.attachmentbrowser.filerenamedialog.FileRenameDialog, zim.plugins.base.imagegenerator.ImageGeneratorDialog, zim.plugins.commandpalette.ZimCommandPaletteDialog, zim.plugins.sourceview.InsertCodeBlockDialog, zim.plugins.tableeditor.EditTableDialog, zim.plugins.versioncontrol.VersionControlInitDialog

result to be returned by run()

uistate = (source)

overridden in zim.gui.widgets.Assistant, zim.plugins.quicknote.QuickNoteDialog

ConfigDict to store state of the dialog, persistent per notebook. The size and position of the dialog are stored as automatically in this dict already.

vbox = (source)

Gtk.VBox for main widgets of the dialog

_no_ok_action: bool = (source)

overridden in zim.gui.pageview.PromptExistingFileDialog, zim.gui.widgets.Assistant

Undocumented