2,186
edits
Changes
→See also
<!--{{languages|Gramplets}}-->{{man warn|Warning:|Technical This section contains technical details about programming Gramplets and is intended for Developers. <br><br>'''If you are interested in using Gramplets, please see the [[Gramps 4Gramps_5.2 Wiki Manual 1_Wiki_Manual_- Gramplets_Gramplets|user manual section on gramplets]]'''.}}
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 = 'init',
gramplet_title=_("Sample Gramplet"),
gramps_target_version="45.01",
help_url="Sample Gramplet"
)
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 place these files in '''your personal [[Gramps_5.0_Wiki_Manual_-_User_Directory|user plugins directory]]''' (usually in ''.gramps/grampsxx/plugins/gramplet/'' ), and then restart Gramps, you 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". You should then see:
[[File:HelloWorldGramplet-40example-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. In this very simple example, a function '''<code>init''' </code> is defined that takes a single argument, <code>gui</code>. 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.
description = _("a program that says 'Hello World'"),
version="0.0.1",
gramps_target_version="45.01",
status = STABLE,
fname="HelloWorld2.py",
gramplet = 'HelloWorldGramplet',
gramplet_title=_("Sample Gramplet"),
help_url="Sample Gramplet5.1_Addons#Addon_List"
)
</pre>
== Register Options ==
* '''<code>GRAMPLET</code>''': the first argument is the keyword GRAMPLET* '''<code>id</code>''': the identifying name of the gramplet, unique among all plugins* '''<code>name</code>''': the translated gramplet's name* '''<code>height</code>''': the minimum (or maximum) height of the gramplet in normal mode* '''<code>fname</code>''': the name of your gramplet file* '''<code>gramplet</code>''': the name of the function or class in fname that creates the gramplet* '''<code>gramplet_title</code>''': the default gramplet title; user changeable in ''Configure View''* '''<code>status</code>''': STABLE or UNSTABLE* '''<code>version</code>''': a string with 2 dots (such as "1.23.14") representing the version number* '''<code>gramps_target_version</code>''': a string with 2 dots representing the version of Gramps that for which this gramplet was written . Only gramplets matching the installed version will be available forinstallation. * '''<code>help_url</code>''': the title of the wiki page that describes the gramplet. <br />If the help_url starts with <code>http://</code> then that fully qualified URL will be used as is. Otherwise, the paths will be interpreted as relative to <code>http://gramps-project.org/wiki/index.php?title=</code> base URL. The base URL will be prepended to the '''help_url''' and may get a language extension (such as <code>/nl</code> ) appended at the end, if the operating language is one of '''nl''' '''fr''' '''sq''' '''mk''' '''de''' '''fi''' '''ru''' '''sk'''. You should '''''not''''' use the <code>_(</code> <code>)</code> translate function around the '''<code>help_url</code>''' string, unless you specifically intend to create web pages named with the translated string.
At the bare minimum, you need to have the above 10 11 options when registering your Gramplets.
In addition, you can use the following as well:
* '''<code>detached_width</code>''': the size in pixels of the minimum and default detached height* '''<code>detached_height</code>''': the size in pixels of the minimum and default detached height* '''<code>expand</code>''': whether or not the Gramplet should expand to fill the column, if it can* '''<code>description</code>''': a description of the grampletGramplet
== Core Methods ==
</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 that compose a Gramplet.
If you wanted to put an arbitrary gtk object into the main area of a Gramplet, then you need to replace the standard textview object with your own. Here is the basic structure:
<pre>
# File: Widget.py
from gettext import gettext as _
from gramps.gen.plug import Gramplet
from 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",
)
</pre>
====Gramps 3.x and older====
<pre>
# File: Widget.py
)
</pre>
===Cairo Clock Example===
Here is an example adding a Cairo Clock (which really keeps time)
* With GTK+3 & Gramps 5.1
** Github code: [https://github.com/gramps-project/addons-source/tree/maintenance/gramps51/ClockGramplet ClockGramplet]
** Manual Download: [https://github.com/gramps-project/addons/blob/master/gramps51/download/ClockGramplet.addon.tgz?raw=true ClockGramplet.addon.tgz]
{{-}}
* '''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()'''
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:
* [httphttps://sourceforgegithub.netcom/pgramps-project/gramps/source/citree/maintenance/gramps34/~/tree/src/plugins/gramplet/ 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.
= See also =
* [[Addons development]] - for Gramps 4.2 and later
** [[Addons development old]] - for Gramps 3.2 to 4.1
* [[Writing a plugin]] - for Gramps version 3.2 and earlier
[[Category:Addons]]
