The gramps.gui Module

Package init for the gui package.

Gramps

class gramps.gui.grampsgui.Gramps(argparser)

Bases: object

Main class corresponding to a running gramps process.

There can be only one instance of this class per gramps application process. It may spawn several windows and control several databases.

argerrorfunc(string)

About Dialog

About dialog

class gramps.gui.aboutdialog.AuthorParser(author_list, contributor_list)

Bases: xml.sax.handler.ContentHandler

Parse the authors.xml file to show in the About dialog.

The authors.xml file has the same format as the one in the svn2cl package, with an additional title tag in the author element. For example:

<author uid="dallingham" title="author">
  Don Allingham &lt;<html:a href="mailto:don@gramps-project.org">don@gramps-project.org</html:a>&gt;
</author>}

characters(chunk)

Receive notification of character data.

endElement(tag)

Handle the end of an element.

startElement(tag, attrs)

Handle the start of an element.

class gramps.gui.aboutdialog.GrampsAboutDialog(parent)

Bases: gi.repository.Gtk.AboutDialog

Constructors:

AboutDialog(**properties)
new()

get_versions()

Obtain version information of core dependencies

Base Sidebar

class gramps.gui.basesidebar.BaseSidebar(dbstate, uistate)

Bases: object

The base class for all sidebar plugins.

active(cat_num, view_num)

Called when the sidebar is made visible.

get_top()

Return the top container widget for the GUI.

inactive()

Called when the sidebar is hidden.

view_changed(cat_num, view_num)

Called when the active view is changed.

Column Order

Handle the column ordering

class gramps.gui.columnorder.ColumnOrder(config, column_names, widths, on_apply, tree=False)

Bases: gi.repository.Gtk.VBox

Constructors:

VBox(**properties)
new(homogeneous:bool, spacing:int)

Configuration

class gramps.gui.configure.ConfigureDialog(uistate, dbstate, configure_page_funcs, configobj, configmanager, dialogtitle='Preferences', on_close=None)

Bases: gramps.gui.managedwindow.ManagedWindow

Base class for configuration dialogs. They provide a Notebook, to which pages are added with configuration options, and a Cancel and Save button. On save, a config file on which the dialog works, is saved to disk, and a callback called.

add_checkbox(table, label, index, constant, start=1, stop=9, config=None, extra_callback=None)

add_color(table, label, index, constant, config=None, col=0)

add_combo(table, label, index, constant, opts, callback=None, config=None, valueactive=False, setactive=None)

A drop-down list allowing selection from a number of fixed options. :param opts: A list of options. Each option is a tuple containing an integer code and a textual description. If valueactive = True, the constant stores the value, not the position in the list

add_entry(table, label, index, constant, callback=None, config=None, col_attach=0)

add_path_box(table, label, index, entry, path, callback_label, callback_sel, config=None)

Add an entry to give in path and a select button to open a dialog. Changing entry calls callback_label Clicking open button call callback_sel

add_pos_int_entry(table, label, index, constant, callback=None, config=None, col_attach=1, helptext='')

entry field for positive integers

add_radiobox(table, label, index, constant, group, column, config=None)

add_slider(table, label, index, constant, range, callback=None, config=None)

A slider allowing the selection of an integer within a specified range. :param range: A tuple containing the minimum and maximum allowed values.

add_spinner(table, label, index, constant, range, callback=None, config=None)

A spinner allowing the selection of an integer within a specified range. :param range: A tuple containing the minimum and maximum allowed values.

add_text(table, label, index, config=None, line_wrap=True)

done(obj, value)

update_checkbox(obj, constant, config=None)

update_color(obj, constant, color_hex_label)

update_combo(obj, constant)

Parameters:

• obj – the ComboBox object
• constant – the config setting to which the value must be saved

update_entry(obj, constant)

Parameters:

• obj – an object with get_text method
• constant – the config setting to which the text value must be saved

update_int_entry(obj, constant)

Parameters:

• obj – an object with get_text method that should contain an integer
• constant – the config setting to which the integer value must be saved

update_markup_entry(obj, constant)

Parameters:

• obj – an object with get_text method
• constant – the config setting to which the text value must be saved

update_radiobox(obj, constant)

update_slider(obj, constant)

Parameters:

• obj – the HScale object
• constant – the config setting to which the value must be saved

update_spinner(obj, constant)

Parameters:

• obj – the SpinButton object
• constant – the config setting to which the value must be saved

class gramps.gui.configure.DisplayNameEditor(uistate, dbstate, track, dialog)

Bases: gramps.gui.managedwindow.ManagedWindow

build_menu_names(obj)

close(*obj)

class gramps.gui.configure.GrampsPreferences(uistate, dbstate)

Bases: gramps.gui.configure.ConfigureDialog

add_advanced_panel(configdialog)

add_behavior_panel(configdialog)

add_color_panel(configdialog)

Add the tab to set defaults colors for graph boxes

add_date_panel(configdialog)

add_famtree_panel(configdialog)

add_formats_panel(configdialog)

add_prefix_panel(configdialog)

Add the ID prefix tab to the preferences.

add_researcher_panel(configdialog)

add_text_panel(configdialog)

build_menu_names(obj)

cb_del_fmt_str(obj)

Name format editor Remove button callback

cb_format_tree_select(tree_selection)

Name format editor TreeView callback

Remember the values of the selected row (self.selected_fmt, self.iter) and set the Remove and Edit button sensitivity

cb_grampletbar_close(obj)

Gramplet bar close button preference callback

cb_name_changed(obj)

Preset name format ComboBox callback

cb_name_dialog(obj)

cb_pa_sur_changed(*args)

checkbox patronymic as surname changed, propagate to namedisplayer

check_for_type_changed(obj)

check_for_updates(button)

check_for_updates_changed(obj)

date_calendar_changed(obj)

date_format_changed(obj)

name_changed_check()

Method to check for a name change. Called by Name Edit Dialog.

select_dbpath(*obj)

select_mediapath(*obj)

set_dbpath(*obj)

set_mediapath(*obj)

toggle_hide_previous_addons(obj)

toggle_tag_on_import(obj)

update_gendepth(obj, constant)

Called when the generation depth setting is changed.

update_idformat_entry(obj, constant)

update_surn_height(obj, constant)

GUI Element (DB)

Group common stuff Gramps GUI elements must be able to do when tracking a DB:

• connect to db signals
• listen to db changes to update themself on relevant changes
• determine if the GUI has become out of sync with the db

class gramps.gui.dbguielement.DbGUIElement(database)

Bases: object

Most interaction with the DB should be done via the callman attribute. On initialization, the method _connect_db_signals() is called. Inheriting objects are advised to group the setup of the callman attribute here.

DB Loader

Handling of loading new/existing databases.

class gramps.gui.dbloader.DbLoader(dbstate, uistate)

Bases: gramps.cli.grampscli.CLIDbLoader

check_errors(filename)

Run common error checks and return True if any found.

In this process, a warning dialog can pop up.

do_import(dialog, importer, filename)

import_file()

import_info_text()

On import the importer can construct an info object about the import. If so, this method will return this text, otherwise the empty string is returned

read_file(filename)

This method takes care of changing database, and loading the data. In 3.0 we only allow reading of real databases of filetype ‘x-directory/normal’

This method should only return on success. Returning on failure makes no sense, because we cannot recover, since database has already been changed. Therefore, any errors should raise exceptions.

On success, return with the disabled signals. The post-load routine should enable signals, as well as finish up with other UI goodies.

class gramps.gui.dbloader.GrampsFormatWidget

Bases: gi.overrides.Gtk.ComboBox

Constructors:

ComboBox(**properties)
new()
new_with_area(area:Gtk.CellArea)
new_with_area_and_entry(area:Gtk.CellArea)
new_with_entry()
new_with_model(model:Gtk.TreeModel)
new_with_model_and_entry(model:Gtk.TreeModel)

get_value()

set(format_list)

DB Manager

Provide the management of databases. This includes opening, renaming, creating, and deleting of databases.

class gramps.gui.dbman.DbManager(dbstate, parent=None)

Bases: gramps.cli.clidbman.CLIDbManager

Database Manager. Opens a database manager window that allows users to create, rename, delete and open databases.

ERROR

alias of ErrorDialog

ICON_MAP = {0: None, 1: 'gtk-dialog-error', 2: 'gramps-lock', 3: 'gtk-open'}

existing_name(name, skippath=None)

Return true if a name is present in the model already. If skippath given, the name of skippath is not considered

run()

Runs the dialog, returning None if nothing has been chosen, or the path and name if something has been selected

Filter Editor

Custom Filter Editor tool.

class gramps.gui.editors.filtereditor.EditFilter(namespace, dbstate, uistate, track, gfilter, filterdb, update=None, selection_callback=None)

Bases: gramps.gui.managedwindow.ManagedWindow

close_window(obj)

draw_rules()

filter_name_changed(obj)

on_add_clicked(obj)

on_delete_clicked(obj)

on_edit_clicked(obj)

on_help_clicked(obj)

Display the relevant portion of Gramps manual

on_ok_clicked(obj)

select_row(obj)

update_rule(old_rule, new_rule)

class gramps.gui.editors.filtereditor.EditRule(namespace, dbstate, uistate, track, filterdb, val, label, update, filter_name)

Bases: gramps.gui.managedwindow.ManagedWindow

close_window(obj)

display_values(class_obj)

expand_collapse()

Expand or collapse the selected parent name node. Return True if change done, False otherwise

on_help_clicked(obj)

Display the relevant portion of Gramps manual.

on_node_selected(obj)

Update the informational display on the right hand side of the dialog box with the description of the selected report.

rule_ok(obj)

select_iter(data)

Workaround to get self.selection to move to iter row. self.selection.select_iter(iter) did not work, so we first select the top_node iter, expand it, and then select_iter.

class gramps.gui.editors.filtereditor.FilterEditor(namespace, filterdb, dbstate, uistate)

Bases: gramps.gui.managedwindow.ManagedWindow

add_new_filter(obj)

build_menu_names(obj)

check_recursive_filters(space, name)

clean_after_rename(space, old_name, new_name)

clone_filter(obj)

close(*obj)

delete_filter(obj)

draw_filters()

edit_filter(obj)

filter_select_row(obj)

get_all_handles()

help_clicked(obj)

Display the relevant portion of Gramps manual

test_clicked(obj)

class gramps.gui.editors.filtereditor.MyBoolean(label=None)

Bases: gi.repository.Gtk.CheckButton

Constructors:

CheckButton(**properties)
new()
new_with_label(label:str)
new_with_mnemonic(label:str)

get_text()

Return the text to save.

It should be the same no matter the present locale (English or numeric types). This class sets this to get_display_text, but when localization is an issue (events/attr/etc types) then it has to be overridden.

set_text(val)

Set the selector state to display the passed value.

class gramps.gui.editors.filtereditor.MyEntry

Bases: gi.repository.Gtk.Entry

Constructors:

Entry(**properties)
new()
new_with_buffer(buffer:Gtk.EntryBuffer)

class gramps.gui.editors.filtereditor.MyFilters(filters, filter_name=None)

Bases: gi.overrides.Gtk.ComboBox

Constructors:

ComboBox(**properties)
new()
new_with_area(area:Gtk.CellArea)
new_with_area_and_entry(area:Gtk.CellArea)
new_with_entry()
new_with_model(model:Gtk.TreeModel)
new_with_model_and_entry(model:Gtk.TreeModel)

get_text()

set_text(val)

class gramps.gui.editors.filtereditor.MyID(dbstate, uistate, track, namespace='Person')

Bases: gi.overrides.Gtk.Box

Constructors:

Box(**properties)
new(orientation:Gtk.Orientation, spacing:int)

button_press(obj)

get_text()

name_from_gramps_id(gramps_id)

obj_name = {'Note': 'Note', 'Person': 'Person', 'Place': 'Place', 'Repository': 'Repository', 'Family': 'Family', 'Source': 'Source', 'Media': 'Media', 'Citation': 'Citation', 'Event': 'Event'}

set_text(val)

class gramps.gui.editors.filtereditor.MyInteger(min, max)

Bases: gi.repository.Gtk.SpinButton

Constructors:

SpinButton(**properties)
new(adjustment:Gtk.Adjustment=None, climb_rate:float, digits:int)
new_with_range(min:float, max:float, step:float)

get_text()

set_text(val)

class gramps.gui.editors.filtereditor.MyLesserEqualGreater(default=0)

Bases: gi.overrides.Gtk.ComboBox

Constructors:

ComboBox(**properties)
new()
new_with_area(area:Gtk.CellArea)
new_with_area_and_entry(area:Gtk.CellArea)
new_with_entry()
new_with_model(model:Gtk.TreeModel)
new_with_model_and_entry(model:Gtk.TreeModel)

get_text()

set_text(val)

class gramps.gui.editors.filtereditor.MyList(clist, clist_trans, default=0)

Bases: gi.overrides.Gtk.ComboBox

Constructors:

ComboBox(**properties)
new()
new_with_area(area:Gtk.CellArea)
new_with_area_and_entry(area:Gtk.CellArea)
new_with_entry()
new_with_model(model:Gtk.TreeModel)
new_with_model_and_entry(model:Gtk.TreeModel)

get_text()

set_text(val)

class gramps.gui.editors.filtereditor.MyPlaces(places)

Bases: gi.repository.Gtk.Entry

Constructors:

Entry(**properties)
new()
new_with_buffer(buffer:Gtk.EntryBuffer)

class gramps.gui.editors.filtereditor.MySelect(type_class, additional)

Bases: gi.overrides.Gtk.ComboBox

Constructors:

ComboBox(**properties)
new()
new_with_area(area:Gtk.CellArea)
new_with_area_and_entry(area:Gtk.CellArea)
new_with_entry()
new_with_model(model:Gtk.TreeModel)
new_with_model_and_entry(model:Gtk.TreeModel)

get_text()

set_text(val)

class gramps.gui.editors.filtereditor.MySource(dbstate, uistate, track)

Bases: gramps.gui.editors.filtereditor.MyID

Constructors:

Box(**properties)
new(orientation:Gtk.Orientation, spacing:int)

class gramps.gui.editors.filtereditor.ShowResults(db, uistate, track, handle_list, filtname, namespace)

Bases: gramps.gui.managedwindow.ManagedWindow

get_name_id(handle)

sort_val_from_handle(handle)

Navigator

A module that provides pluggable sidebars. These provide an interface to manage pages in the main Gramps window.

class gramps.gui.navigator.Navigator(viewmanager)

Bases: object

A class which defines the graphical representation of the Gramps navigator.

add(title, sidebar, order)

Add a page to the sidebar for a plugin.

cb_close_clicked(button)

Called when the sidebar is closed.

cb_menu_activate(menu, index)

Called when an item in the popup menu is selected.

cb_switch_page(notebook, unused, index)

Called when the user has switched to a new sidebar plugin page.

cb_view_clicked(radioaction, current, cat_num)

Called when a view is selected from the menu.

get_top()

Return the top container widget for the GUI.

load_plugins(dbstate, uistate)

Load the sidebar plugins.

view_changed(cat_num, view_num)

Called when a Gramps view is changed.

Plugin Manager

The core of the Gramps plugin system. This module provides capability to load plugins from specified directories and provide information about the loaded plugins.

Plugins are divided into several categories. These are: reports, tools, importers, exporters, quick reports, and document generators.

class gramps.gui.pluginmanager.GuiPluginManager

Bases: gramps.gen.utils.callback.Callback

PluginManager is a Singleton which manages plugins. It is the gui implementation using a unique BasePluginmanager. This class adds the possibility to hide plugins in the GUI via a config setting

get_hidden_plugin_ids()

Returns copy of the set hidden plugin ids

static get_instance()

Use this function to get the instance of the PluginManager

get_reg_bookitems()

Return list of non hidden reports registered as bookitem

get_reg_docgens()

Return list of registered docgen

get_reg_exporters()

Return list of registered exporters

get_reg_general(category=None)

get_reg_gramplets()

Return list of non hidden reports registered as bookitem

get_reg_importers()

Return list of registered importers

get_reg_mapservices()

Return list of non hidden registered mapservices

get_reg_quick_reports()

Return list of non hidden registered quick reports

get_reg_reports(gui=True)

Return list of non hidden registered reports :Param gui: bool indicating if GUI reports or CLI reports must be returned

get_reg_sidebars()

Return list of non hidden registered sidebars

get_reg_tools(gui=True)

Return list of non hidden registered tools :Param gui: bool indicating if GUI reports or CLI reports must be returned

get_reg_views()

Return list of non hidden registered views

hide_plugin(id)

Hide plugin with given id. This will hide the plugin so queries do not return it anymore, and write this change to the config. Note that config will then emit a signal

load_icons(icons, dir)

Load icons in the iconfactory of Gramps, so they can be used in the plugin.

The plugin directory must contain the directories scalable, 48x48, 22x22 and 16x16 with the icons, e.g. in dir we have:

• scalable/gramps_myplugin.svg
• 48x48/gramps_myplugin.png
• 22x22/gramps_myplugin.png

Parameters:

• icons (A list of tuples (stock_id, icon_label)) – New stock icons to register. e.g. [(‘gramps_myplugin’, _(‘My Plugin’)), (‘gramps_myplugin_open’, _(‘Open Plugin’))]
• dir (str) – Directory from where to load the icons

load_plugin(pdata)

reload_plugins()

unhide_plugin(id)

Unhide plugin with given id. This will unhide the plugin so queries return it again, and write this change to the config

User

The User class provides basic interaction with the user.

class gramps.gui.user.User(callback=None, error=None, uistate=None)

Bases: gramps.gen.user.User

This class provides a means to interact with the user via GTK. It implements the interface in gen.user.User

begin_progress(title, message, steps)

Start showing a progress indicator to the user.

Parameters:

• title (str) – the title of the progress meter
• message (str) – the message associated with the progress meter
• steps (int) – the total number of steps for the progress meter. a value of 0 indicates that the ending is unknown and the meter should just show activity.

Returns:

none

end_progress()

Stop showing the progress indicator to the user.

info(msg1, infotext, parent=None, monospaced=False)

Calls the GUI InfoDialog

notify_db_error(error)

Notify the user of a DB error.

Parameters:error (str) – the DB error message Returns:none

notify_error(title, error='')

Notify the user of an error.

Parameters:

• title (str) – the title of the error
• error (str) – the error message

Returns:

none

prompt(title, message, accept_label, reject_label)

Prompt the user with a message to select an alternative.

Parameters:

• title (str) – the title of the question, e.g.: “Undo history warning”
• message – the message, e.g.: “Proceeding with the tool will erase the undo history. If you think you may want to revert running this tool, please stop here and make a backup of the DB.”
• accept_label (str) – what to call the positive choice, e.g.: “Proceed”
• reject_label (str) – what to call the negative choice, e.g.: “Stop”

Returns:

the user’s answer to the question

Return type:

bool

step_progress()

Advance the progress meter.

warn(title, warning='')

Warn the user.

Parameters:

• title (str) – the title of the warning
• warning (str) – the warning

Returns:

none

Utils

Utility functions that depend on GUI components or for GUI components

class gramps.gui.utils.CLIDialog

Command-line interface vbox, to keep compatible with Dialog.

connect(signal, callback)

destroy()

set_border_width(width)

set_modal(flag)

set_size_request(width, height)

set_title(title)

set_transient_for(window)

show_all()

vbox = <gramps.gui.utils.CLIVbox instance at 0x2b07e953ab90>

class gramps.gui.utils.CLIVbox

Command-line interface vbox, to keep compatible with Dialog.

add(widget)

set_border_width(width)

set_spacing(spacing)

class gramps.gui.utils.ProgressMeter(title, header='', can_cancel=False, cancel_callback=None, message_area=False, parent=None)

Bases: object

Progress meter class for Gramps.

The progress meter has two modes:

MODE_FRACTION is used when you know the number of steps that will be taken. Set the total number of steps, and then call step() that many times. The progress bar will progress from left to right.

MODE_ACTIVITY is used when you don’t know the number of steps that will be taken. Set up the total number of steps for the bar to get from one end of the bar to the other. Then, call step() as many times as you want. The bar will move from left to right until you stop calling step().

MODE_ACTIVITY = 1

MODE_FRACTION = 0

append_message(text)

Method to add text to message area.

close(widget=None)

Close the progress meter

get_cancelled()

Returns cancelled setting. True if progress meter has been cancelled.

handle_cancel(*args, **kwargs)

Default cancel handler (if enabled).

set_header(text)

set_message(text)

Sets the text of the message area.

set_pass(header='', total=100, mode=0)

Reset for another pass. Provide a new header and define number of steps to be used.

step()

Click the progress bar over to the next value. Be paranoid and insure that it doesn’t go over 100%.

View Manager

Manages the main window and the pluggable views

class gramps.gui.viewmanager.ViewManager(dbstate, view_category_order, user=None)

Bases: gramps.cli.grampscli.CLIManager

Overview

The ViewManager is the session manager of the program. Specifically, it manages the main window of the program. It is closely tied into the Gtk.UIManager to control all menus and actions.

The ViewManager controls the various Views within the Gramps programs. Views are organised in categories. The categories can be accessed via a sidebar. Within a category, the different views are accesible via the toolbar of view menu.

A View is a particular way of looking a information in the Gramps main window. Each view is separate from the others, and has no knowledge of the others.

Examples of current views include:

• Person View
• Relationship View
• Family View
• Source View

The View Manager does not have to know the number of views, the type of views, or any other details about the views. It simply provides the method of containing each view, and has methods for creating, deleting and switching between the views.

abort(obj=None)

Abandon changes and quit.

build_plugin_menu(text, item_list, categories, func)

Builds a new XML description for a menu based on the list of plugindata

check_for_updates()

Check for add-on updates.

clipboard(obj)

Displays the Clipboard

config_view(obj)

Displays the configuration dialog for the active view

display_about_box(obj)

Display the About box.

do_load_plugins()

Loads the plugins at initialization time. The plugin status window is opened on an error if the user has requested.

do_reg_plugins(dbstate, uistate)

Register the plugins at initialization time. The plugin status window is opened on an error if the user has requested.

export_data(obj)

Calls the ExportAssistant to export data

fullscreen_toggle(obj, data=None)

Set the main Granps window fullscreen based on the value of the toggle button. Save the setting in the config file.

get_category(cat_name)

Return the category number from the given category name.

get_views()

Return the view definitions.

goto_page(cat_num, view_num)

Create the page if it doesn’t exist and make it the current page.

import_data(obj)

Imports a file

init_interface()

Initialize the interface.

media_toggle(widget, file_entry)

Toggles media include values in the quick backup dialog.

navigator_toggle(obj, data=None)

Set the sidebar based on the value of the toggle button. Save the results in the configuration settings

post_init_interface(show_manager=True)

Showing the main window is deferred so that ArgHandler can work without it always shown

preferences_activate(obj)

Open the preferences dialog.

process_updates(addon_update_list)

Called when add-on updates are available.

quick_backup(obj)

Make a quick XML back with or without media.

quit(*obj)

Closes out the program, backing up data

redo(obj)

Calls the redo function on the database

reports_clicked(obj)

Displays the Reports dialog

run_book(action)

Run a book.

select_backup_path(widget, path_entry)

Choose a backup folder. Make sure there is one highlighted in right pane, otherwise FileChooserDialog will hang.

tip_of_day_activate(obj)

Display Tip of the day

toolbar_toggle(obj, data=None)

Set the toolbar based on the value of the toggle button. Save the results in the configuration settings

tools_clicked(obj)

Displays the Tools dialog

undo(obj)

Calls the undo function on the database

undo_history(obj)

Displays the Undo history window

undo_history_close()

Closes the undo history

undo_history_update()

This function is called to update both the state of the Undo History menu item (enable/disable) and the contents of the Undo History window.

view_changed(notebook, page, page_num)

Called when the notebook page is changed.