2,186
edits
Changes
→See also
<!--{{languages|Gramplets}}-->
{{man warn|Warning:|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_5.1_Wiki_Manual_-_Gramplets|user manual section on gramplets]]'''.}}
gramplet = 'init',
gramplet_title=_("Sample Gramplet"),
gramps_target_version="5.01",
help_url="Sample Gramplet"
)
=== 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="5.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 ==
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()'''
* [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]]
