Difference between revisions of "Gramplets"
(New docs for gramplets) |
|||
Line 47: | Line 47: | ||
[[Media:HelloWorldGramplet.png]] | [[Media:HelloWorldGramplet.png]] | ||
− | === | + | === 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 | ||
Line 87: | Line 87: | ||
== Core Properties == | == Core Properties == | ||
− | * type: the case- | + | * type: the case-insensitive keyword "gramplet" |
* name: the gramplet's name, unique among gramplets | * name: the gramplet's name, unique among gramplets | ||
* tname: the gramplet's name, translated | * tname: the gramplet's name, translated | ||
Line 185: | Line 185: | ||
− | + | Testing: | |
*{{man label|name}} = a unique name: a name GRAMPS identifies the plugin with, don't use spaces or strange symbols. | *{{man label|name}} = a unique name: a name GRAMPS identifies the plugin with, don't use spaces or strange symbols. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
Revision as of 14:33, 30 December 2008
Contents
Gramplet Interface
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).
Hello World
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:
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". 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.
Core Properties
- type: the case-insensitive 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
Core Methods
- 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)
- set_use_markup(BOOLEAN-VALUE)
- render_text(TEXT)
- append_text(TEXT, scroll_to=POSITION)
- clear_text()
- set_text(TEXT)
- no_wrap()
Using Tags
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")
GUI Interface
Occasionally, you might have to dive down to the graphical objects that compose a Gramplet.
- tooltip = TEXT
- gui
- gui.buffer
- gui.textview
- gui.get_container_widget()
GUI Options
- add_option(OPTION)
- build_options()
- save_options()
- get_option_widget(TEXT)
- get_option(TEXT)
Predifined Properties
There are a number of preset properies:
- gui
- gui.data
- dbstate
- dbstate.db
- dbstate.db.connect(SIGNAL, METHOD)
- dbstate.db.get_person_from_handle(HANDLE)
- dbstate.get_active_person()
- dbstate.db
- uistate
Persistance
- gui
- gui.data
- on_load
- on_save
- save_text_to_data()
- load_data_to_text()
Testing:
- name = a unique name: a name GRAMPS identifies the plugin with, don't use spaces or strange symbols.