A Gramplet is a type of GRAMPS plugin. A Gramplet is a mini-view that can be made to do just about anything that you want. There are 6 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/plugins).
In teaching programming, a common "first program" is to write a program that says "Hello World". Let's jump right in and take a look at such a gramplet:
def init(gui): gui.set_text("Hello world!") from DataViews import register register(type="gramplet", name="Hello World Gramplet", height = 20, content = init, title="Sample Gramplet", )
If you copy this text into a file in 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:
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". The Gramplet interfaces uses a slightly different method for registering than the other plugins. Here, you import the "register" function from the DataViews module. Then 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
Here is the same functionality again, but this time as a class:
from DataViews import register, Gramplet class HelloWorldGramplet(Gramplet): def init(self): self.set_text("Hello world!") register(type="gramplet", name="Hello World2 Gramplet", height = 20, content = HelloWorldGramplet, title="Sample2 Gramplet", )
This is the recommended method of creating a Gramplet. The following details describe the properties and methods of these classes.
- type: the case-insenstitive keyword "gramplet"
- name: the gramplet's name, unique among gramplets
- tname: the gramplet's name, translated
- height: the minimum or maximum height of the gramplet in normal mode
- content: the function or class name of your code
- title: the default gramplet title; user changeable
- init: run once, on construction
- main: run once per update
- update: don't change this, it calls main
- active_changed: run when active-changed is triggered
- db_changed: run when db-changed is triggered
Don't call main directly; use the update method.
In the db_changed method, you should connect all of the signals that will trigger an update. That typically looks like:
def db_changed(self): self.dbstate.db.connect('person-add', self.update) self.dbstate.db.connect('person-delete', self.update) self.dbstate.db.connect('person-update', self.update) self.dbstate.db.connect('family-add', self.update) self.dbstate.db.connect('family-delete', self.update) self.dbstate.db.connect('family-update', self.update)
Textual Output Methods
The most common kinds of Gramplets are text-based. There are a number of methods to assist with handling this text.
- link(TEXT, LINK-TYPE, OBJECT-HANDLE)
- append_text(TEXT, scroll_to=POSITION)
Tags are the manner in which you format the text.
tag = self.gui.buffer.create_tag("fixed") tag.set_property("font", "Courier 8") ... start, end = self.gui.buffer.get_bounds() self.gui.buffer.apply_tag_by_name("fixed", start, end) self.append_text("", scroll_to="begin")
Occasionally, you might have to dive down to the graphical objects that compose a Gramplet.
- tooltip = TEXT
There are a number of preset properies:
- dbstate.db.connect(SIGNAL, METHOD)
- name = a unique name: a name GRAMPS identifies the plugin with, don't use spaces or strange symbols.
- category = a special constant indicating where the report will be shown. You can use CATEGORY_QR_PERSON to see the report on person editor and view, or CATEGORY_QR_FAMILY to see the report on family editor or view.
- run_func = the function you create in this plugin and that GRAMPS will execute when the user selects your quick report in the menu
- translated_name = the name of the report as it will appear in the menu
- status = is your report Stable or Unstable. Not used at the moment. On distributing GRAMPS we only include stable reports.
- description = a description of what your plugin does. This appears in a tooltip over the menu
- author_name = your name
- author_email= your email, so people can congratulate you with your work, or ask for bug fixes...