Improve gui documentation
This commit is contained in:
parent
2e746a21da
commit
5e1cd88bcb
@ -2,7 +2,7 @@
|
||||
Code Documentation
|
||||
##################
|
||||
|
||||
*GRAMPS* provides several general API. The most important is the *gen* module, providing access to all code that can be of interest outside of the GRAMPS program.
|
||||
*Gramps* provides several general API. The most important is the *gen* module, providing access to all code that can be of interest outside of the Gramps program.
|
||||
|
||||
The :mod:`gen` Module
|
||||
=======================
|
||||
@ -22,7 +22,7 @@ Contents:
|
||||
gen/gen_proxy
|
||||
gen/gen_utils
|
||||
|
||||
The GRAMPS Application
|
||||
The Gramps Application
|
||||
========================
|
||||
|
||||
Contents:
|
||||
@ -36,7 +36,7 @@ Contents:
|
||||
relationship
|
||||
simple
|
||||
|
||||
Usefull snippets
|
||||
Useful snippets
|
||||
===================
|
||||
|
||||
Contents:
|
||||
|
@ -154,7 +154,7 @@ Filter Editor
|
||||
:show-inheritance:
|
||||
|
||||
*****************************
|
||||
Gramps Bar
|
||||
Gramplet Bar
|
||||
*****************************
|
||||
.. automodule:: gramps.gui.widgets.grampletbar
|
||||
.. autoclass:: DetachedWindow
|
||||
@ -180,7 +180,7 @@ Navigator
|
||||
:show-inheritance:
|
||||
|
||||
*****************************
|
||||
Plugins Manager
|
||||
Plugin Manager
|
||||
*****************************
|
||||
.. automodule:: gramps.gui.pluginmanager
|
||||
.. autoclass:: GuiPluginManager
|
||||
@ -215,7 +215,7 @@ Utils
|
||||
:show-inheritance:
|
||||
|
||||
*****************************
|
||||
Views Manager
|
||||
View Manager
|
||||
*****************************
|
||||
.. automodule:: gramps.gui.viewmanager
|
||||
.. autoclass:: ViewManager
|
||||
|
@ -157,11 +157,11 @@ def ellipses(text):
|
||||
#
|
||||
#-------------------------------------------------------------------------
|
||||
class AuthorParser(handler.ContentHandler):
|
||||
"""Parse the 'authors.xml file to show in the About dialog.
|
||||
"""Parse the ``authors.xml`` file to show in the About dialog.
|
||||
|
||||
The C{authors.xml} file has the same format as the one in the U{svn2cl
|
||||
<http://ch.tudelft.nl/~arthur/svn2cl/>} package, with an additional
|
||||
C{title} tag in the C{author} element. For example::
|
||||
The ``authors.xml`` file has the same format as the one in the `svn2cl
|
||||
<http://ch.tudelft.nl/~arthur/svn2cl/>`_ package, with an additional
|
||||
``title`` tag in the ``author`` element. For example::
|
||||
|
||||
<author uid="dallingham" title="author">
|
||||
Don Allingham <<html:a href="mailto:don@gramps-project.org">don@gramps-project.org</html:a>>
|
||||
@ -211,11 +211,11 @@ class AuthorParser(handler.ContentHandler):
|
||||
def _get_authors():
|
||||
"""Return all the authors and contributors in a string.
|
||||
|
||||
Parse the C{authors.xml} file if found, or return the default
|
||||
list from L{const} module in case of I/O or parsing failure.
|
||||
Parse the ``authors.xml`` file if found, or return the default
|
||||
list from :mod:`.const` module in case of I/O or parsing failure.
|
||||
|
||||
If the C{authors.xml} file is successfully parsed the I{Authors} and
|
||||
I{Contributors} are grouped separately with an appropriate header.
|
||||
If the ``authors.xml`` file is successfully parsed the *Authors* and
|
||||
*Contributors* are grouped separately with an appropriate header.
|
||||
|
||||
"""
|
||||
try:
|
||||
|
@ -21,7 +21,8 @@
|
||||
# $Id$
|
||||
|
||||
"""
|
||||
Group common stuff GRAMPS GUI elements must be able to do when tracking a 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
|
||||
@ -41,17 +42,13 @@ from gramps.gen.utils.callman import CallbackManager
|
||||
#-------------------------------------------------------------------------
|
||||
class DbGUIElement(object):
|
||||
"""
|
||||
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
|
||||
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.
|
||||
On initialization, the method :meth:`_connect_db_signals` is called.
|
||||
Inheriting objects are advised to group the setup of the callman attribute
|
||||
here.
|
||||
|
||||
.. attribute callman : a `~gen.utils.callman.CallbackManager` object, to
|
||||
be used to track specific changes in the db and set up callbacks
|
||||
.. attribute callman: a :class:`.CallbackManager` object, to be used to
|
||||
track specific changes in the db and set up callbacks
|
||||
"""
|
||||
def __init__(self, database):
|
||||
self.callman = CallbackManager(database)
|
||||
|
@ -22,7 +22,7 @@
|
||||
# $Id$
|
||||
|
||||
"""
|
||||
Date editing module for GRAMPS.
|
||||
Date editing module for Gramps.
|
||||
|
||||
The EditDate provides visual feedback to the user via a pixamp
|
||||
to indicate if the associated GtkEntry box contains a valid date. Green
|
||||
@ -109,7 +109,7 @@ WIKI_HELP_SEC = _('manual|Editing_Dates')
|
||||
class EditDate(ManagedWindow):
|
||||
"""
|
||||
Dialog allowing to build the date precisely, to correct possible
|
||||
limitations of parsing and/or underlying structure of Date.
|
||||
limitations of parsing and/or underlying structure of :class:`.Date`.
|
||||
"""
|
||||
|
||||
def __init__(self, date, uistate, track):
|
||||
@ -228,7 +228,7 @@ class EditDate(ManagedWindow):
|
||||
|
||||
def build_menu_names(self, obj):
|
||||
"""
|
||||
Define the menu entry for the ManagedWindows
|
||||
Define the menu entry for the :class:`.ManagedWindow`
|
||||
"""
|
||||
return (_("Date selection"), None)
|
||||
|
||||
|
@ -692,7 +692,7 @@ class EditRule(ManagedWindow):
|
||||
|
||||
def on_help_clicked(self, obj):
|
||||
"""
|
||||
Display the relevant portion of GRAMPS manual.
|
||||
Display the relevant portion of Gramps manual.
|
||||
"""
|
||||
display_help()
|
||||
|
||||
@ -807,7 +807,7 @@ class EditFilter(ManagedWindow):
|
||||
self.show()
|
||||
|
||||
def on_help_clicked(self, obj):
|
||||
"""Display the relevant portion of GRAMPS manual"""
|
||||
"""Display the relevant portion of Gramps manual"""
|
||||
display_help(webpage=WIKI_HELP_PAGE)
|
||||
|
||||
def close_window(self, obj):
|
||||
@ -1064,7 +1064,7 @@ class FilterEditor(ManagedWindow):
|
||||
return (_("Custom Filter Editor"), _("Custom Filter Editor"))
|
||||
|
||||
def help_clicked(self, obj):
|
||||
"""Display the relevant portion of GRAMPS manual"""
|
||||
"""Display the relevant portion of Gramps manual"""
|
||||
display_help()
|
||||
|
||||
def filter_select_row(self, obj):
|
||||
|
@ -21,7 +21,7 @@
|
||||
# $Id$
|
||||
|
||||
"""
|
||||
The core of the GRAMPS plugin system. This module provides capability to load
|
||||
The core of the Gramps plugin system. This module provides capability to load
|
||||
plugins from specified directories and provide information about the loaded
|
||||
plugins.
|
||||
|
||||
@ -58,13 +58,13 @@ from gramps.gen.const import ICON
|
||||
def base_reg_stock_icons(iconpaths, extraiconsize, items):
|
||||
"""
|
||||
Reusable base to register stock icons in Gramps
|
||||
..attribute iconpaths: list of main directory of the base icon, and
|
||||
extension, eg:
|
||||
[(os.path.join(IMAGE_DIR, 'scalable'), '.svg')]
|
||||
..attribute extraiconsize: list of dir with extra prepared icon sizes and
|
||||
the gtk size to use them for, eg:
|
||||
:param iconpaths: list of main directory of the base icon, and extension,
|
||||
eg:
|
||||
[(os.path.join(IMAGE_DIR, 'scalable'), '.svg')]
|
||||
:param extraiconsize: list of dir with extra prepared icon sizes and the
|
||||
gtk size to use them for, eg:
|
||||
[(os.path.join(IMAGE_DIR, '22x22'), Gtk.IconSize.LARGE_TOOLBAR)]
|
||||
..attribute items: list of icons to register, eg:
|
||||
:param items: list of icons to register, eg:
|
||||
[('gramps-db', _('Family Trees'), Gdk.ModifierType.CONTROL_MASK, 0, '')]
|
||||
"""
|
||||
|
||||
@ -168,20 +168,22 @@ class GuiPluginManager(Callback):
|
||||
|
||||
def load_icons(self, icons, dir):
|
||||
"""
|
||||
Load icons in the iconfactory of gramps, so they can be used in the
|
||||
Load icons in the iconfactory of Gramps, so they can be used in the
|
||||
plugin.
|
||||
|
||||
..attribute icons:
|
||||
New stock icons to register. A list of tuples (stock_id, icon_label),
|
||||
eg:
|
||||
[('gramps_myplugin', _('My Plugin')),
|
||||
('gramps_myplugin_open', _('Open Plugin'))]
|
||||
The plugin directory must contain the directories scalable, 48x48, 22x22
|
||||
and 16x16 with the icons, eg in dir we have:
|
||||
scalable/gramps_myplugin.svg
|
||||
48x48/gramps_myplugin.png
|
||||
22x22/gramps_myplugin.png
|
||||
..attribute dir: directory from where to load the icons
|
||||
|
||||
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
|
||||
|
||||
:param icons: New stock icons to register. e.g.
|
||||
[('gramps_myplugin', _('My Plugin')),
|
||||
('gramps_myplugin_open', _('Open Plugin'))]
|
||||
:type icons: A list of tuples (stock_id, icon_label)
|
||||
:param dir: Directory from where to load the icons
|
||||
:type dir: str
|
||||
"""
|
||||
if win():
|
||||
iconpaths = [
|
||||
|
@ -48,7 +48,7 @@ from .dialog import (WarningDialog, ErrorDialog, DBErrorDialog,
|
||||
class User(user.User):
|
||||
"""
|
||||
This class provides a means to interact with the user via GTK.
|
||||
It implements the interface in gramps.gen.user.User()
|
||||
It implements the interface in :class:`.gen.user.User`
|
||||
"""
|
||||
def __init__(self, callback=None, error=None, uistate=None):
|
||||
user.User.__init__(self, callback, error)
|
||||
@ -59,15 +59,15 @@ class User(user.User):
|
||||
"""
|
||||
Start showing a progress indicator to the user.
|
||||
|
||||
@param title: the title of the progress meter
|
||||
@type title: str
|
||||
@param message: the message associated with the progress meter
|
||||
@type message: str
|
||||
@param steps: 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.
|
||||
@type steps: int
|
||||
@returns: none
|
||||
:param title: the title of the progress meter
|
||||
:type title: str
|
||||
:param message: the message associated with the progress meter
|
||||
:type message: str
|
||||
:param steps: 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.
|
||||
:type steps: int
|
||||
:returns: none
|
||||
"""
|
||||
self._progress = ProgressMeter(title)
|
||||
if steps > 0:
|
||||
@ -94,18 +94,19 @@ class User(user.User):
|
||||
"""
|
||||
Prompt the user with a message to select an alternative.
|
||||
|
||||
@param title: the title of the question, e.g.: "Undo history warning"
|
||||
@type title: str
|
||||
@param 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."
|
||||
@type question: str
|
||||
@param accept_label: what to call the positive choice, e.g.: "Proceed"
|
||||
@type accept_label: str
|
||||
@param reject_label: what to call the negative choice, e.g.: "Stop"
|
||||
@type reject_label: str
|
||||
@returns: the user's answer to the question
|
||||
@rtype: bool
|
||||
:param title: the title of the question, e.g.: "Undo history warning"
|
||||
:type title: str
|
||||
:param 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."
|
||||
:type question: str
|
||||
:param accept_label: what to call the positive choice, e.g.: "Proceed"
|
||||
:type accept_label: str
|
||||
:param reject_label: what to call the negative choice, e.g.: "Stop"
|
||||
:type reject_label: str
|
||||
:returns: the user's answer to the question
|
||||
:rtype: bool
|
||||
"""
|
||||
dialog = QuestionDialog2(title, message, accept_label, reject_label)
|
||||
return dialog.run()
|
||||
@ -114,11 +115,11 @@ class User(user.User):
|
||||
"""
|
||||
Warn the user.
|
||||
|
||||
@param title: the title of the warning
|
||||
@type title: str
|
||||
@param warning: the warning
|
||||
@type warning: str
|
||||
@returns: none
|
||||
:param title: the title of the warning
|
||||
:type title: str
|
||||
:param warning: the warning
|
||||
:type warning: str
|
||||
:returns: none
|
||||
"""
|
||||
WarningDialog(title, warning)
|
||||
|
||||
@ -126,11 +127,11 @@ class User(user.User):
|
||||
"""
|
||||
Notify the user of an error.
|
||||
|
||||
@param title: the title of the error
|
||||
@type title: str
|
||||
@param error: the error message
|
||||
@type error: str
|
||||
@returns: none
|
||||
:param title: the title of the error
|
||||
:type title: str
|
||||
:param error: the error message
|
||||
:type error: str
|
||||
:returns: none
|
||||
"""
|
||||
if self.error_function:
|
||||
self.error_function(title, error)
|
||||
@ -141,9 +142,9 @@ class User(user.User):
|
||||
"""
|
||||
Notify the user of a DB error.
|
||||
|
||||
@param error: the DB error message
|
||||
@type error: str
|
||||
@returns: none
|
||||
:param error: the DB error message
|
||||
:type error: str
|
||||
:returns: none
|
||||
"""
|
||||
DBErrorDialog(error)
|
||||
|
||||
|
@ -109,18 +109,18 @@ class CLIDialog:
|
||||
|
||||
class ProgressMeter(object):
|
||||
"""
|
||||
Progress meter class for GRAMPS.
|
||||
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.
|
||||
Set the total number of steps, and then call :meth:`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.
|
||||
the bar to the other. Then, call :meth:`step` as many times as you want. The
|
||||
bar will move from left to right until you stop calling :meth:`step`.
|
||||
"""
|
||||
|
||||
MODE_FRACTION = 0
|
||||
@ -328,12 +328,14 @@ class SystemFonts(object):
|
||||
|
||||
The bug is described here: https://bugzilla.gnome.org/show_bug.cgi?id=679654
|
||||
|
||||
This code generate a warning:
|
||||
This code generates a warning:
|
||||
/usr/local/lib/python2.7/site-packages/gi/types.py:47:
|
||||
Warning: g_value_get_object: assertion `G_VALUE_HOLDS_OBJECT (value)' failed
|
||||
|
||||
To get a list of fonts, instantiate this class and call get_system_fonts()
|
||||
#TODO GTK3: the underlying bug may be fixed at some point in the future
|
||||
To get a list of fonts, instantiate this class and call
|
||||
:meth:`get_system_fonts`
|
||||
|
||||
.. todo:: GTK3: the underlying bug may be fixed at some point in the future
|
||||
"""
|
||||
|
||||
__FONTS = None
|
||||
@ -383,9 +385,11 @@ def poll_external (args):
|
||||
GLib.timeout_add_seconds, so the arguments are in a tuple because that
|
||||
function takes only a single data argument.
|
||||
|
||||
@proc the process, returned from subprocess.Popen()
|
||||
@errorstrings a dict of possible response values and the corresponding messages to display.
|
||||
@returns bool returned to timeout_add_seconds: should this function be called again?
|
||||
:param proc: the process, returned from subprocess.Popen()
|
||||
:param errorstrings: a dict of possible response values and the
|
||||
corresponding messages to display.
|
||||
:return: bool returned to timeout_add_seconds: should this function be
|
||||
called again?
|
||||
"""
|
||||
(proc, errorstrings) = args
|
||||
resp = proc.poll()
|
||||
@ -402,10 +406,10 @@ def open_file_with_default_application(path):
|
||||
whatever program is configured on the host as the default program for that
|
||||
type of file.
|
||||
|
||||
@param file_path: The path to the file to be opened.
|
||||
Example: "c:\\foo.txt"
|
||||
@type file_path: string
|
||||
@return: nothing
|
||||
:param file_path: The path to the file to be opened.
|
||||
Example: "c:\\foo.txt"
|
||||
:type file_path: string
|
||||
:return: nothing
|
||||
"""
|
||||
|
||||
errstrings = None
|
||||
@ -472,9 +476,9 @@ def is_right_click(event):
|
||||
|
||||
def color_graph_box(alive=False, gender=Person.MALE):
|
||||
"""
|
||||
Returns based on the config the color for graph boxes in hex
|
||||
If gender is None, an empty box is assumed
|
||||
Return type: tuple (hex color fill, hex color border)
|
||||
:return: based on the config the color for graph boxes in hex
|
||||
If gender is None, an empty box is assumed
|
||||
:rtype: tuple (hex color fill, hex color border)
|
||||
"""
|
||||
if gender == Person.MALE:
|
||||
if alive:
|
||||
|
@ -243,19 +243,18 @@ WIKI_HELP_PAGE_MAN = '%s' % URL_MANUAL_PAGE
|
||||
#-------------------------------------------------------------------------
|
||||
class ViewManager(CLIManager):
|
||||
"""
|
||||
Overview
|
||||
========
|
||||
**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.
|
||||
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
|
||||
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.
|
||||
|
||||
|
@ -664,7 +664,7 @@ class DetachedWindow(ManagedWindow):
|
||||
|
||||
def build_menu_names(self, obj):
|
||||
"""
|
||||
Part of the GRAMPS window interface.
|
||||
Part of the Gramps window interface.
|
||||
"""
|
||||
return (self.title, 'Gramplet')
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user