A '''Gramplet''' is a type of Gramps plugin. Gramplets are 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.

−

= Gramplet Interface =

+

[[File:GrampletsDefault-40.png|400px|thumb|right|Gramplet]]

−

[[Image:Gramplets.png|thumb|right|Gramplet]]

−

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

+

= Gramplet Interface =

−

to do just about anything that you want. There are 6 main kinds of plugins:

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/gramplet/'' ).

−

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 ==

== Hello World ==

−

In teaching programming, a common "first program" is to write a program that

+

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

−

says "Hello World".

+

−

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

+

+

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

+

+

Create a python file named ''HelloWorld.py'' and add the following content:

<pre>

<pre>

# File: HelloWorld.py

# File: HelloWorld.py

def init(gui):

def init(gui):

−

gui.set_text("Hello world!")

+

gui.set_text("Hello world!")

</pre>

</pre>

−

Then an other python file named ''HelloWorld.gpr.py''

+

And create another python file named ''HelloWorld.gpr.py'' with the following content:

<pre>

<pre>

Line 45:

Line 43:

version="0.0.1",

version="0.0.1",

fname="HelloWorld.py",

fname="HelloWorld.py",

−

height = 20,

+

height = 20,

gramplet = 'init',

gramplet = 'init',

−

gramps_target_version="3.2",

gramplet_title=_("Sample Gramplet"),

gramplet_title=_("Sample Gramplet"),

+

gramps_target_version="4.0",

help_url="Sample Gramplet"

help_url="Sample Gramplet"

)

)

</pre>

</pre>

−

You can read more about the gpr.py file in [[Addons development]] and the [http://gramps.svn.sourceforge.net/viewvc/gramps/trunk/src/gen/plug/_pluginreg.py?view=markup source code implementation].

+

You can read more about the gpr.py file in [[Addons development]] and the [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py source code implementation].

−

If you place these files your plugins directory, and then

+

If you place these files in '''your personal plugins directory''' (usually in ''.gramps/grampsxx/plugins/gramplet/'' ), and then restart Gramps, you will 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:

−

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:

+

−

[[Image:HelloWorldGramplet.png]]

+

[[File:HelloWorldGramplet-40.png|thumb|left|Hello World Gramplet]]

+

+

{{-}}

=== Explanation ===

=== Explanation ===

−

The main work of a Gramplet is performed in a function, or a class. In

+

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.

−

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".

+

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.

−

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.

+

== Hello World, with Class ==

== Hello World, with Class ==

Line 83:

Line 71:

<pre>

<pre>

# File: HelloWorld2.py

# File: HelloWorld2.py

−

from gen.plug import Gramplet

+

from gramps.gen.plug import Gramplet

class HelloWorldGramplet(Gramplet):

class HelloWorldGramplet(Gramplet):

Line 97:

Line 85:

description = _("a program that says 'Hello World'"),

description = _("a program that says 'Hello World'"),

version="0.0.1",

version="0.0.1",

−

gramps_target_version="3.2",

+

gramps_target_version="4.0",

status = STABLE,

status = STABLE,

fname="HelloWorld2.py",

fname="HelloWorld2.py",

Line 107:

Line 95:

</pre>

</pre>

−

This is the recommended method of creating a Gramplet. The following details

+

This is the '''recommended method''' of creating a Gramplet. The following details describe the properties and methods of this class.

−

describe the properties and methods of this class.

+

== Register Options ==

== Register Options ==

Line 121:

Line 108:

* '''status''': STABLE or UNSTABLE

* '''status''': STABLE or UNSTABLE

* '''version''': a string with 2 dots (such as "1.23.14") representing the version number

* '''version''': a string with 2 dots (such as "1.23.14") representing the version number

−

* '''gramps_target_version''': a string with 2 dots representing the version of GRAMPS that this gramplet was written for

+

* '''gramps_target_version''': a string with 2 dots representing the version of Gramps that this gramplet was written for

* '''help_url''': the title of the wiki page that describes the gramplet

* '''help_url''': the title of the wiki page that describes the gramplet

Line 146:

Line 133:

Don't call main directly; use the update method.

Don't call main directly; use the update method.

−

In the db_changed method, you should connect all of the signals that

+

In the db_changed method, you should connect all of the signals that will trigger an update. That typically looks like:

−

will trigger an update. That typically looks like:

+

<pre>

<pre>

Line 159:

Line 145:

</pre>

</pre>

−

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:

+

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:

<pre>

<pre>

Line 173:

Line 159:

== Textual Output Methods ==

== Textual Output Methods ==

−

The most common kinds of Gramplets are text-based. There are a number of

+

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

−

methods to assist with handling this text.

+

* '''set_text(TEXT)''' - clear and set text to TEXT

* '''set_text(TEXT)''' - clear and set text to TEXT

Line 232:

Line 217:

== GUI Interface ==

== GUI Interface ==

−

Occasionally, you might have to dive down to the graphical objects that

+

Occasionally, you might have to dive down to the graphical objects that compose a Gramplet.

−

compose a Gramplet.

+

* gui

* gui

Line 245:

Line 229:

# File: Widget.py

# File: Widget.py

from gettext import gettext as _

from gettext import gettext as _

−

from gen.plug import Gramplet

+

from gramps.gen.plug import Gramplet

import gtk

import gtk

Line 265:

Line 249:

fname="Widget.py",

fname="Widget.py",

gramplet = "WidgetGramplet",

gramplet = "WidgetGramplet",

−

gramps_target_version = "3.2",

+

gramps_target_version = "3.4",

gramplet_title=_("Widget"),

gramplet_title=_("Widget"),

)

)

</pre>

</pre>

−

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: [https://gramps-addons.svn.sourceforge.net/svnroot/gramps-addons/branches/gramps32/download/ClockGramplet.addon.tgz ClockGramplet.addon.tgz]

+

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 3.4 : [https://gramps-addons.svn.sourceforge.net/svnroot/gramps-addons/branches/gramps34/download/ClockGramplet.addon.tgz ClockGramplet.addon.tgz]

Here it is on the Gramplet view:

Here it is on the Gramplet view:

−

[[Image:ClockScreen.png|400px|Clock on Gramplet View]]

+

[[File:ClockScreen.png|400px|Clock on Gramplet View]]

and detached:

and detached:

−

[[Image:ClockGramplet.png|400px|Clock Gramplet detached]]

+

[[File:ClockGramplet.png|400px|Clock Gramplet detached]]

−

+

−

== Buttons ==

+

−

+

−

Help button pointed to the page of the wiki manual.

+

−

But you can also try to make your own button:

+

−

+

−

button_box = gtk.HButtonBox()

+

−

button_box.set_layout(gtk.BUTTONBOX_END)

+

−

+

−

help_btn = gtk.Button(stock=gtk.STOCK_HELP)

+

−

help_btn.connect('clicked', self.help_clicked)

+

−

button_box.add(help_btn)

+

−

button_box.set_child_secondary(help_btn, True)

+

−

+

−

def help_clicked(self, obj):

+

−

"""

+

−

Display the relevant portion of Gramps wiki

+

−

"""

+

−

GrampsDisplay.help(webpage='Name_of_page')

+

−

+

−

Note, this may not work for some locales without localized ''Name_of_page/{country_code}'' page. See [[Translating_GRAMPS#Translating_wiki_manual|Translating wiki manual]].

+

== GUI Options ==

== GUI Options ==

Line 322:

Line 285:

* '''get_option(TEXT)'''

* '''get_option(TEXT)'''

−

== Predifined Properties ==

+

== Predefined Properties ==

There are a number of preset properties:

There are a number of preset properties:

Line 350:

Line 313:

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:

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:

Revision as of 17:51, 27 January 2013

A Gramplet is a type of Gramps plugin. Gramplets are 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 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/gramplet/ ).

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:

Create a python file named HelloWorld.py and add the following content:

# File: HelloWorld.py
def init(gui):
gui.set_text("Hello world!")

And create another python file named HelloWorld.gpr.py with the following content:

If you place these files in your personal plugins directory (usually in .gramps/grampsxx/plugins/gramplet/ ), and then restart Gramps, you will 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:

Hello World Gramplet

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 3.4 : 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)

Predefined 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: