Changes

Jump to: navigation, search

Gramplets

1,841 bytes added, 00:11, 27 May 2020
GUI Options: just list them all
{{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.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.
[[File:GrampletsDefaultDashboardCategory-40DashboardView-default-gramplets-50.png|400px450px|thumb|right|GrampletDefault Gramplets on Dashboard]]
gramplet = 'init',
gramplet_title=_("Sample Gramplet"),
gramps_target_version="45.01",
help_url="Sample Gramplet"
)
</pre>
You can read more about the gpr.py file in [[Addons_development#Create_a_Gramps_Plugin_Registration_file|Addons development]] and the [httphttps://sourceforgegithub.netcom/pgramps-project/gramps/source/ciblob/master/tree/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.0",
status = STABLE,
fname="HelloWorld2.py",
</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) to Gramps 3.4 : [https://gramps-addons.svn.sourceforge.net/svnroot/gramps-addons/branches/gramps34/download/ClockGramplet.addon.tgz ClockGramplet.addon.tgz] or with GTK+ Gramps 4.0: [https://gramps-addons.svn.sourceforge.net/svnroot/gramps-addons/branches/gramps41/download/ClockGramplet.addon.tgz ClockGramplet.addon.tgz]
Here it is on the [[File:ClockGramplet-addon-example-50.png|thumb|400px|right|Clock Gramplet view:- shown detached (Gramps 5.0.0)]]
[[File:ClockScreenIn fact, with Python, GTK, and cairo, you can make your own widgets that do pretty much anything and look very nice.png|400px|Clock on Gramplet View]]
and detached: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: [Filehttps://github.com/gramps-project/addons/blob/master/gramps51/download/ClockGramplet.png|400px|Clock Gramplet detached]addon.tgz?raw=true ClockGramplet.addon.tgz]{{-}}
== 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()'''
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]* [httphttps://sourceforgegithub.netcom/gramps-project/gramps/tree/maintenance/pgramps42/gramps/sourceplugins/gramplet Gramps 4.2 Gramplets]* [https:/ci/maintenancegithub.com/gramps40gramps-project/~gramps/tree/maintenance/gramps50/gramps/plugins/gramplet/ Gramps 45.0 Gramplets]* [httphttps://sourceforgegithub.netcom/pgramps-project/gramps/sourcetree/maintenance/cigramps51/mastergramps/plugins/gramplet Gramps 5.1 Gramplets]* [https://github.com/gramps-project/gramps/tree/master/gramps/plugins/gramplet/ Gramps Master/Trunk 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]]

Navigation menu