Changes

<!--{{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 4.1 Wiki Manual Gramps_{{man version}}_Wiki_Manual_- Gramplets_Gramplets|user manual section on gramplets]]'''.}}

A '''Gramplet''' is a [[Addon_list_legend#Type|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:GrampletsDefaultDashboardCategory-40DashboardView-default-gramplets-52.png|450px|thumb|right|Default Gramplets on Dashboard - With Example Family Tree Open]][[File:Dashboard-category-view-first-open-no-family-tree-loaded-52.png|400px450px|thumb|right|GrampletDefault Gramplets on Dashboard - No Family Tree Loaded]]

Gramplet only operate after being added to a view. Add (or remove and restore) to the [[Gramps_{{man version}}_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 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 many [[Addon_list_legend#Type|types of plugins]]. The 6 most common are:

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_{{man version}}_Wiki_Manual_-_User_Directory|User Directory]] (usually in ''<code>.gramps/grampsxx/plugins/gramplet/</code>'' ).

gramps_target_version="45.02",

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_{{man version}}_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-52.png|thumb|450px|left|Hello World Gramplet- example (shown embedded on Dashboard Category View / Context menu "Add a gramplet" also shown)]]

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.

gramps_target_version="45.02",

help_url="Sample Gramplet5.2_Addons#Addon_List"

* '''<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.

* '''<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

* '''<code>init()</code>''': run once, on construction* '''<code>main()</code>''': run once per update* '''<code>update()</code>''': don't change this, it calls main* '''<code>active_changed()</code>''': run when active-changed is triggered* '''<code>db_changed()</code>''': run when db-changed is triggered* '''<code>set_tooltip(TEXT)</code>''' - tooltip for gramplet  

In the <code>db_changed </code> method, you should connect all of the signals that will trigger an update. That typically looks like:

The method <code>main() </code> can be written as a normal Python method, or it can be written to run nicely in parallel with other Gramps code. To make it run nicely in parallel, you should issue a '''<code>yield True</code>''' every once in a while. For example:

== GUI Interface ==* [[Gramplets#Widget_Gramplet_example|Widget Gramplet example]]* [[Gramplets#Cairo_Clock_Example|Cairo Clock Example]]{{stub}}

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]{{-}}

** OPTION is one of the menu optionsin [https://github.com/gramps-project/gramps/tree/master/gramps/gen/plug/menu gramps/gen/plug/menu] eg:

*** see src/gen/plug/menu/ for othersPersonListOption*** PlaceListOption*** SurnameColorOption*** DestinationOption*** StyleOption*** BooleanListOption

* [httphttps://sourceforgegithub.netcom/pgramps-project/gramps/sourcetree/cimaster/maintenancegramps/plugins/gramplet Gramps Master (development fork) Gramplets]* '''[https://github.com/gramps34gramps-project/~gramps/tree/srcmaintenance/gramps52/gramps/plugins/gramplet/ Gramps 35.4 2 Gramplets]'''* [httphttps://sourceforgegithub.netcom/pgramps-project/gramps/sourcetree/maintenance/gramps51/gramps/ciplugins/maintenancegramplet Gramps 5.1 Gramplets]* [https://github.com/gramps41gramps-project/~gramps/tree/maintenance/gramps50/gramps/plugins/gramplet/ Gramps 45.1 0 Gramplets]* [httphttps://sourceforgegithub.netcom/pgramps-project/gramps/sourcetree/ci/mastermaintenance/treegramps42/gramps/plugins/grampletGramps 4.2 Gramplets]* [https://github.com/gramps-project/gramps/tree/maintenance/gramps34/src/ plugins Gramps Master/Trunk 3.4 Gramplets]