4,191
edits
Changes
→GUI Options: just list them all
{{man warn|Warning:|This page describes the section contains technical details of about programming Grampletsand is intended for Developers. <br><br>'''If you are interested in using Gramplets, please see the [[Gramps_5.1_Wiki_Manual_-_Gramplets|user manual section on gramplets]]'''.}} A '''Gramplet''' is a type of Gramps 3plugin.1 Wiki Manual Gramplets are mini- view that is designed to be composed with other Grampletsor 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. [[File:DashboardCategory-DashboardView-default-gramplets-50.png|450px|thumb|right|Default Gramplets on Dashboard]].
= Gramplet Interface =
# '''Reports''': output for printing or display
# '''Gramplets''': interactive views for moving, analysing, displaying, etc.
There are two plugin directories: a global/system one, and aprivate/personal one. You can easily create a plugin by simplyputting 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 thatsays "Hello World". Let's us jump right in and take a look at such a grampletnamed ''HelloWorld.py'':
Create a python file named ''HelloWorld.py'' and add the following content:
<pre>
# File: HelloWorld.py
def init(gui):
<pre># File: HelloWorld.gpr.pyregister(typeGRAMPLET, id="grampletHello World Gramplet", name=_("Hello World Gramplet"), tnamedescription =_("a program that says 'Hello World Gramplet'"), status = STABLE, version="0.0.1", fname="HelloWorld.py",
height = 20,
)
</pre>
You can read more about the gpr.py file in [[Addons_development#Create_a_Gramps_Plugin_Registration_file|Addons development]] and the [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py source code implementation]. If you copy this text into a file place these files in '''your personal [[Gramps_5.0_Wiki_Manual_-_User_Directory|user plugins directory]]''' (usually in ''.gramps/grampsxx/plugins/gramplet/'' ), and theneither restart GRAMPS or go to Help -> Plugin Status -> ReloadGramps, theyou'll will be able to create this Gramplet. On the Gramplet '''Dashboard Category View''',right-click in an open area and select the "Hello World Gramplet". Youshould then see:
[[ImageFile:HelloWorldGramplet-example-shown-embeded-on-DashboardCategory-50.png|thumb|400px|left|Hello World Gramplet - example (shown embedded on Dashboard Category View)]] {{-}}
=== Explanation ===
The main work of a Gramplet is performed in a function, or a class. Inthis very simple example, a function '''<code>init''' </code> is defined that takesa single argument, <code>gui</code>. The function simply sets the gui's text areato be "Hello World!", and that's it. It does this just once, and neverchanges.
Before a plugin can be used, it needs to be "registered". The Grampletinterfaces uses a slightly different method for registering than theother plugins. Here, you import the "register" function from theDataViews module. Then you You call the register function with a number ofnamed-arguments. There are a number of named-arguments that you canprovide, including: name, height, content, title, expand, state, anddata. We will explore those in detail, below.
== Hello World, with Class ==
<pre>
# File: HelloWorld2.pyfrom DataViews gramps.gen.plug import register, Gramplet
class HelloWorldGramplet(Gramplet):
def init(self):
self.set_text("Hello world!")
</pre>
<pre># File: HelloWorld2.gpr.pyregister(typeGRAMPLET, id="grampletHello World2 Gramplet", name=_("Hello World2 Gramplet"), tnamedescription =_("a program that says 'Hello World2 GrampletWorld'"), version="0.0.1", gramps_target_version="5.0", status = STABLE, fname="HelloWorld2.py", height = 20, content gramplet = 'HelloWorldGramplet', titlegramplet_title=_("Sample2 Sample Gramplet"), help_url="Sample Gramplet"
)
</pre>
This is the '''recommended method ''' of creating a Gramplet. The following detailsdescribe the properties and methods of this class.
== Register Options ==
* '''typeGRAMPLET''': the case-insensitive first argument is the keyword "gramplet"GRAMPLET* '''nameid''': the identifying name of the gramplet's name, unique among grampletsall plugins* '''tnamename''': the translated gramplet's name, translated* '''height''': the minimum (or maximum ) height of the gramplet in normal mode* '''contentfname''': the name of your gramplet file* '''gramplet''': the name of the function or class name of your codein fname that creates the gramplet* '''titlegramplet_title''': the default gramplet title; user changeablein ''Configure View''* '''status''': STABLE or UNSTABLE* '''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* '''help_url''': the title of the wiki page that describes the gramplet
At the bare minimum, you need to have the above 6 10 options when registering your Gramplets.
In addition, you can use the following as well:
* '''detached_height''': the size in pixels of the minimum and default detached height
* '''expand''': whether or not the Gramplet should expand to fill the column, if it can
* '''versiondescription''': a string with 2 dots (such as "1.23.14") representing description of the version number* '''gramps''': a string with 2 dots representing the version of GRAMPS that this gramplet was written for
== Core Methods ==
The class-based gramplet utilizes the following methods:
* '''init()''': run once, on construction
Don't call main directly; use the update method.
In the db_changed method, you should connect all of the signals thatwill trigger an update. That typically looks like:
<pre>
self.dbstate.db.connect('family-update', self.update)
</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:
<pre>
def main(self):
for i in range(5000):
if i % 500 == 0:
yield True
yield False
</pre>
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 ofmethods to assist with handling this text.
* '''set_text(TEXT)''' - clear and set text to 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
</pre>
== GUI Interface ==* [[Gramplets#Widget_Gramplet_example|Widget Gramplet example]]* [[Gramplets#Cairo_Clock_Example|Cairo Clock Example]]{{stub}}
===Widget Gramplet example===Occasionally, you might have to dive down to the graphical objects thatcompose a Gramplet.
* gui
<pre>
# File: Widget.py
from gettext import gettext as _
from DataViews gramps.gen.plug import Grampletfrom gi.repository import Gtk class WidgetGramplet(Gramplet): def init(self): self.gui.WIDGET = ### Some Widget Constructor ### self.gui.get_container_widget().remove(self.gui.textview) self.gui.get_container_widget().add_with_viewport(self.gui.WIDGET) self.gui.WIDGET.show()</pre> <pre># File: Widget.gpr.py register(GRAMPLET, id= "Widget Gramplet", name=_("Widget Gramplet"), description = _("Widget Gramplet example"), height=100, expand=False, gramplet = 'WidgetGramplet', gramplet_title=_("Widget"), version = '0.0.1', gramps_target_version = "5.1", fname="Widget.py", register )</pre> ====Gramps 3.x and older====<pre># File: Widget.pyfrom gettext import gettext as _from gramps.gen.plug import Gramplet
import gtk
class WidgetGramplet(Gramplet):
def init(self):
self.gui.WIDGET = gtk.WIDGET()### Some Widget Constructor ###
self.gui.get_container_widget().remove(self.gui.textview)
self.gui.get_container_widget().add_with_viewport(self.gui.WIDGET)
self.gui.WIDGET.show()
</pre>
<pre># File: Widget.gpr.pyregister(type="gramplet"GRAMPLET, nameid= "Widget Gramplet", tnamename=_("Widget Gramplet"),
height=100,
expand=False,
)
</pre>
== GUI Options ==
* '''add_option(OPTION)'''
** OPTION is one of the menu optionsin [https://github.com/gramps-project/gramps/tree/master/gramps/gen/plug/menu gramps/gen/plug/menu] eg:
*** NumberOption
*** EnumeratedListOption
*** NoteOption
*** MediaOption
*** see src/gen/plug/menu/ for othersPersonListOption*** PlaceListOption*** SurnameColorOption*** DestinationOption*** StyleOption*** BooleanListOption
* '''build_options()'''
* '''save_options()'''
* '''get_option(TEXT)'''
== Predifined Predefined Properties ==
There are a number of preset properties:
* '''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:
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps34/src/plugins Gramps 3.4 Gramplets]
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps42/gramps/plugins/gramplet Gramps 4.2 Gramplets]
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps50/gramps/plugins/gramplet Gramps 5.0 Gramplets]
* [https://github.com/gramps-project/gramps/tree/maintenance/gramps51/gramps/plugins/gramplet Gramps 5.1 Gramplets]
* [https://github.com/gramps-project/gramps/tree/master/gramps/plugins/gramplet Gramps Master Gramplets]
Click on a filename, to view the source code of that Gramplet.
* [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_gramplet.py master/gramps/gen/plug/_gramplet.py] - Base class for non-graphical gramplet code.
[[Category:Addons]]
[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category: Plugins]]
[[Category:Gramplets]]
