Changes

Jump to: navigation, search

Gramplets

2,200 bytes added, 17:48, 28 September 2020
m
Hello World, with Class: change help_url example to something less ambiguous
{{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 5Gramps_5.0 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="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>
* '''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 for which this gramplet was written . Only gramplets matching the installed version will be available forinstallation. * '''help_url''': 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&#58;//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 '''help_url''' 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 options when registering your Gramplets.
</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===
In fact, with Python, gtk, and cairo, you can make your own widgets that do pretty much anything and look very nice.
Here is an example adding a Cairo Clock (which really keeps time)* with GTK 2 & Gramps 3.4: [https[File://grampsClockGramplet-addon-addonsexample-50.svn.sourceforge.net/svnroot/grampspng|thumb|400px|right|Clock Gramplet -addons/branches/gramps34/download/ClockGramplet.addonshown detached (Gramps 5.tgz ClockGramplet0.addon.tgz0)]* or with GTK+3 & Gramps 4.2: [https://github.com/gramps-project/addons/blob/master/gramps50/download/ClockGramplet.addon.tgz?raw=true ClockGramplet.addon.tgz]
[[File:ClockGramplet-dashboard-41In fact, with Python, GTK, and cairo, you can make your own widgets that do pretty much anything and look very nice.png|thumb|left|400px|Clock Gramplet - Dashboard view (Gramps 4.1.0)]] [[File:ClockGramplet-addon-example-50.png|thumb|400px|right|Clock Gramplet - shown detached (Gramps 5.0.0)]]
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.
[[Category:Addons]]
4,529
edits

Navigation menu