Difference between revisions of "Gramplets"

From Gramps
Jump to: navigation, search
(New docs for gramplets)
 
Line 47: Line 47:
 
[[Media:HelloWorldGramplet.png]]
 
[[Media:HelloWorldGramplet.png]]
  
=== Explaination ===
+
=== 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-insenstitive keyword "gramplet"
+
* 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.
*{{man label|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.
 
*{{man label|run_func}} = the function you create in this plugin and that GRAMPS will execute when the user selects your quick report in the menu
 
* {{man label|translated_name}} = the name of the report as it will appear in the menu
 
* {{man label|status}} = is your report '''Stable''' or '''Unstable'''. Not used at the moment. On distributing GRAMPS we only include stable reports.
 
*{{man label|description}} = a description of what your plugin does. This appears in a tooltip over the menu
 
*{{man label|author_name}} = your name
 
*{{man label|author_email}}= your email, so people can congratulate you with your work, or ask for bug fixes...
 

Revision as of 14:33, 30 December 2008


Gramplet Interface

Gramplet

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:

  1. Reports: output for printing or display
  2. Tools: a method for processing data
  3. Quick View: a list of details based on the current object
  4. Importer: reads a file into your current tree
  5. Exporter writes a file from your current tree
  6. 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:

Media:HelloWorldGramplet.png

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()
  • 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.