Changes

Jump to: navigation, search

Gramplets

3,377 bytes added, 16:17, 17 July 2022
m
no edit summary
<!--{{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]]'''.}}
A '''Gramplet''' is a type of Gramps plugin. Gramplets are mini-view that is views designed to be composed composited 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:DashboardCategory-DashboardView-default-gramplets-50.png|450px|thumb|right|Default Gramplets on Dashboard]]
= Gramplet Interface =
 
Gramplet only operate after being added to a view. Add (or remove and restore) to the [[Gramps_5.1_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|sidebar or bottombar]] of a view by clicking the {{man button|&or;}} (''Down Arrowhead'' button) also known as the '''Gramplet Bar Menu''' at the far top right of the bars titles, and then using one of the options from the drop-down menu. In the Dashboard view, this menu is accessed by right-clicking in-between gramplets in the main view.
 
Gramplet can dramatically degrade the performance of Gramps. Some Gramplets consume huge amounts of memory, processor power and move a lot of data through storage. Don't keep a Gramplet active when it isn't being used!
 
When the view is not active or Gramplet tab is not the foremost in the splitbar, the Gramplet is inactive. A detached (undocked) Gramplet is always active.
= The user interface for a Gramplet Interface =is left completely to the discretion of the developer. Detach/undock a Gramplet to reveal the "Help" button. Explore the Configure options after adding a Gramplet.
== Are Gramplets and 'plug-ins' the same thing? ==
There are 6 main kinds of plugins:
# '''Gramplets''': interactive views for moving, analysing, displaying, etc.
There are two plugin directories: a global/system one, and a private/personal one. You can easily create a plugin by simply putting a file in plugins folder of your personal plugin directory [[Gramps_5.1_Wiki_Manual_-_User_Directory|User Directory]] (usually in ''.gramps/grampsxx/plugins/gramplet/'' ).
== Hello World ==
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&#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 '''<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===
[[File:ClockGramplet-addon-example-50.png|thumb|400px|right|Clock Gramplet - shown detached (Gramps 5.0.0)]]
In fact, with Python, gtkGTK, 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 With GTK 2 +3 & Gramps 35.41** Github code: [https://gramps-addonsgithub.svn.sourceforge.net/svnrootcom/gramps-project/addons-source/branchestree/gramps34maintenance/downloadgramps51/ClockGramplet.addon.tgz ClockGramplet.addon.tgz]* or with GTK+3 & Gramps 4.2* Manual Download: [https://github.com/gramps-project/addons/blob/master/gramps50gramps51/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]]
4,529
edits

Navigation menu