Gramplet Interface

A Gramplet is a type of GRAMPS plugin. A Gramplet is a mini-view that is designed to be composed with other Gramplets or Views to create a way to see your Family Tree that is just right for you. In fact, Gramplets can be made
to do just about anything that you want. There are 6 main kinds of plugins:

Reports: output for printing or display

Tools: a method for processing data

Quick View: a list of details based on the current object

Importer: reads a file into your current tree

Exporter: writes a file from your current tree

Gramplets: interactive views for moving, analysing, displaying, etc.

There are two plugin directories: a global/system one, and a
private/personal one. You can easily create a plugin by simply
putting a file in your personal plugin directory (usually in
.gramps/grampsxx/plugins).

Hello World

In teaching programming, a common "first program" is to write a program that says "Hello World".

Let us jump right in and take a look at such a gramplet named HelloWorld.py:

If you place these files your plugins directory, and then either restart GRAMPS or go to Help -> Plugin Status -> Reload, the
you'll be able to create this Gramplet. On the Gramplet View, right-click in an open area and select the "Hello World Gramplet". You should then see:

Explanation

The main work of a Gramplet is performed in a function, or a class. In
this very simple example, a function init is defined that takes
a single argument, gui. The function simply sets the gui's text area
to be "Hello World!", and that's it. It does this just once, and never
changes.

Before a plugin can be used, it needs to be "registered".
You call the register function with a number of
named-arguments. There are a number of named-arguments that you can
provide, including: name, height, content, title, expand, state, and
data. We will explore those in detail, below.

The method main() can be written as a normal Python method, or it can be written to run nicely in parallel with other GRAMPS code. To make it run nicely in parallel, you should issue a yield True every once in a while. For example:

def main(self):
for i in range(5000):
if i % 500 == 0:
yield True
yield False

The True means that there is more to do; False means that there is nothing left to do.

Textual Output Methods

The most common kinds of Gramplets are text-based. There are a number of
methods to assist with handling this text.

set_text(TEXT) - clear and set text to TEXT

append_text(TEXT, scroll_to=POSITION)

POSITION is 'begin' (top), 'end' (bottom) or 'start' (start of append)

clear_text() - clears all text

set_use_markup(BOOLEAN-VALUE)

render_text(TEXT) - for use with A, B, I, U, and TT tags

A for creating links; use tag HREF="url" for URLs, and WIKI="name" for pages on the wiki

B for bold

I for italics

U for underlined

TT for a fixed-width, typewriter font

link(TEXT, LINK-TYPE, DATA) -

TEXT can be any text

LINK-TYPE is:

'Person' - and DATA is a person handle

'PersonList' - and DATA is a list of handles

'Family' - and DATA is a family handle

'Surname' - and DATA is a person

'Given' -

'Filter' - and DATA is either:

'all people' -

'males' - all males

'females' - all females

'people with unknown gender' - people marked as unknown

'people with incomplete names' - people who have a missing surname or given name

'people with missing birth dates' - people who have missing birth dates

In fact, with Python, gtk, and cairo, you can make your own widgets that do pretty much anything and look very nice. Here is an example adding a Cairo Clock (which really keeps time) to GRAMPS: ClockGramplet.addon.tgz

Here it is on the Gramplet view:

and detached:

GUI Options

add_option(OPTION)

OPTION is one of the menu options:

NumberOption

EnumeratedListOption

StringOption

ColorOption

TextOption

BooleanOption

FilterOption

PersonOption

FamilyOption

NoteOption

MediaOption

see src/gen/plug/menu/ for others

build_options()

save_options()

get_option_widget(TEXT)

get_option(TEXT)

Predifined Properties

There are a number of preset properties:

dbstate

dbstate.db

dbstate.db.connect(SIGNAL, METHOD)

dbstate.db.get_person_from_handle(HANDLE)

dbstate.get_active_person()

uistate

Persistance

gui

gui.data

on_load()

on_save()

save_text_to_data()

load_data_to_text()

Advanced Settings

force_update: set True to have the gramplet update, even when minimized

Learning More

To learn more about writing a Gramplet, it is suggested to look at the existing Gramplets. You can see a complete list of the Gramplet source code here: