Difference between revisions of "GEPS 004: My Gramps and Gadgets"

From Gramps
Jump to: navigation, search
m (GEPS 004: Interactive Context Sensitive Data Explorers moved to GEPS 004: My GRAMPS and Gadgets: Focus of GEP has changed, and the Gadgets can do most of the original proposal's goals)
(20 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Proposed changes for enhancing GRAMPS by adding a new document generator that allows a report to be displayed on the screen, with graphical objects such as tables, buttons, text entry, links, etc. This would effectively be able to turn a report into an interface for moving, say, the active person in the main window, or, possibly, for user-defined data entry.
+
{{GEPS-Finished}}
 +
{{man menu|'''This proposal has now been implemented, and is in GRAMPS 3.1 as the Gramplets View'''}}
  
[[Category:GEPS]]
+
Proposed changes for enhancing GRAMPS by adding a new GUI API that allows data to be displayed on the screen, with graphical objects such as tables, buttons, text entry, links, etc. This would effectively be able to turn a user plugin into an interface for moving, say, the active person in the main window, or, possibly, for user-defined data entry. . See [[Gramplets]] for development information, [[Gramps 3.1 Wiki Manual - Gramplets]] for information on using them, and [[Third-party Plugins]] for a list of additional Gramplets.
  
 
== Motivation ==
 
== Motivation ==
  
Allows user to add to the interface, and to use existing reports as extensions to the interface.
+
Allows users to add to the GRAMPS interface. A new page, currently called "Gramplets", would be created that allows for customized "gramplets" that perform various functions (other than tools and reports). This might include: interactive shells, TODO lists, logs, debugging tools, and various "folders" for organizing groups of people, families, or other objects.  
  
 
== Details ==
 
== Details ==
  
In progress... exploring gtk/gdk to see what is available.
+
A prototype is now available for exploration and testing. To activate the prototype, add the following line to your .gramps/keys.ini file in the interface section:
  
== Discussion ==
+
data-views= MyGrampsView,PersonView,RelationshipView,FamilyListView,PedigreeView,EventView,SourceView,PlaceView,MediaView,RepositoryView,NoteView
 +
 
 +
This should be all on one line. You can change the order (and leave some pages out) as well with this key. (You can also add pages multiple times, but that isn't as useful as the active object on one page will change it on another).
 +
 
 +
On start up, the file gramplets.ini is looked for in the user's .gramps subdirectory. If it is not found, a set of gramplets are created, currently a Welcome Message Gramplet and a Stats Gramplet.
 +
 
 +
[[Image:Mygramps.png]]
 +
 
 +
You can drag the Properties button (top left) of each gramplet to move it around the screen. Clicking the Properties will (currently) detach the gramplet from My Gramps and place it in its own window. The window will stay open regardless of page (relationship, pedigree, etc). Closing the detached view will put it back onto the Gramplets view. If you quit Gramps with a open gramplet, when you start gramps again, it will open automatically.
 +
 
 +
[[Image:Detached.png]]
 +
 
 +
You can add new gramplets by right clicking on an open space on Gramplets. You can also change the number of columns by right-clicking an open area on the Gramplets page.
 +
 
 +
=== Gramplets ===
 +
 
 +
What is a GRAMPS gramplet? A GRAMPS gramplet is a view of data that either changes dynamically during the running of GRAMPS, or provides interactivity to your genealogical data. What is the difference between gramplets, reports, quick views, and tools?
 +
 
 +
# Reports provide a static output format of your data, typically for printing
 +
# Quick View provides a typically short, interactive listing derived from your data
 +
# Tools provide a method of processing your data
 +
# Gramplets provide a dynamic view and interface to your data
 +
 
 +
There are currently 9 proof-of-concept gramplets:
 +
 
 +
# Welcome Gramplet
 +
# Top Surnames Gramplet
 +
# Surname Cloud Gramplet
 +
# TODO Gramplet
 +
# Statistics Gramplet
 +
# Python Gramplet
 +
# News Gramplet
 +
# Session Log Gramplet
 +
# Calendar Gramplet
 +
 
 +
This section will describe each gramplet and its proposed functionality
 +
 
 +
==== Welcome Gramplet ====
 +
 
 +
[[Image:Welcomegadget.png]]
 +
 
 +
The welcome gramplet gives an introductory message to new users, and some basic instructions.
 +
 
 +
TODO: add links to parts of manual, links to bring up windows.
 +
 
 +
==== Top Surnames Gramplet ====
 +
 
 +
[[Image:Topgadget.png]]
 +
 
 +
The top surnames gramplet shows the top 10 (by default) used surnames. Double-click a surname to run the Same Surnames Quick View.
 +
 
 +
Change the number of names displayed by editing this section in ~/.gramps/gramplets.ini
 +
 
 +
==== Surname Cloud Gramplet ====
 +
 
 +
[[Image:Surnamecloud.png]]
 +
 
 +
The surname cloud gramplet shows the top 100 (by default) used surnames. Double-click a surname to run the Same Surnames Quick View. Mouse over the name to see percentage and counts.
 +
 
 +
Change the number of names displayed by editing this section in ~/.gramps/gramplets.ini
 +
 
 +
==== TODO Gramplet ====
 +
 
 +
[[Image:Todogadget.png]]
 +
 
 +
The TODO gramplet is free form text. This is persistent between sessions. Open more than one to save different info. Change the title of the gramplet  by editing the section name in ~/.gramps/gramplets.ini
 +
 
 +
==== Statistics Gramplet ====
 +
 
 +
[[Image:Statgadget.png]]
 +
 
 +
The Statistics gramplet runs a copy of the code from the Statistics report.
 +
 
 +
==== Python Gramplet ====
 +
 
 +
[[Image:Pythongadget.png]]
 +
 
 +
The Python gramplet brings up a Python Shell for interpreting python expressions. You can type most any (single line) Python expression. In addition, the environment has been populated with some useful variables, including '''self''' (this Python gramplet), '''Date''', '''uistate''' and '''dbstate'''. The '''Date''' entry is a date object constructor, and can be used for date arithmetic. For example, you might be interested in answering these questions:
 +
 
 +
What was the date 56 years ago:
 +
 
 +
> Date(2007, 12, 31) - 56
 +
1951-12-31
 +
 
 +
How old was someone on Sept 3, 1955 who was born on June 7, 1922:
 +
 
 +
> Date(1955, 9, 3) - Date(1922, 5, 7)
 +
(33, 3, 27)
 +
 
 +
(About 33 years, 3 months, and 27 days). When did they turn 21 years old?
 +
 
 +
> Date(1922, 5, 7) + 21
 +
1943-05-07
 +
 
 +
You can also add years, months, and days:
 +
 
 +
> Date(1980) + (0, 0, 25)
 +
1980-01-26
 +
 
 +
==== News Gramplet ====
 +
 
 +
[[Image:Newsgadget.png]]
 +
 
 +
The News gramplet reads the wiki news page. TODO: add links and formatting.
 +
 
 +
==== Session Log Gramplet ====
 +
 
 +
[[Image:Loggadget.png]]
 +
 
 +
The session log keeps track of activity in this session. By default, it only shows each entry once. Change this behavior by editing this section in ~/.gramps/gramplets.ini. Click a name to change the active person; double-click to bring up the edit page for that person.
 +
 
 +
==== Calendar Gramplet ====
 +
 
 +
[[Image:Calendargadget.png]]
 +
 
 +
The Calendar gramplet shows a monthly calendar, with events marked (in bold day numbers). Double-click a day to run the "On This Day" Quick Report.
 +
 
 +
== Development ==
 +
 
 +
These are all defined in src/plugins/DefaultGramplets.py
 +
 
 +
The simplest gramplet:
 +
 
 +
<pre>
 +
from DataViews import register
 +
 
 +
def init(gui):
 +
    gui.set_text("Hello world!")
  
This type of proposal is discussed on these threads:
+
register(type="gramplet",            # case in-senstitive keyword "gramplet"
 +
        name="Hello World Gramplet", # name, unique among gramplets
 +
        height = 20,              # default size
 +
        content = init,            # function/class; takes guigramplet
 +
        title="Sample Gramplet",    # default title, user changeable
 +
        )
 +
</pre>
  
http://www.nabble.com/A-ScreenDoc-idea-t847639.html
+
Using the Gramplet class, however, provides more functionality. It has a number of method possibilities:
  
http://www.nabble.com/Re:-Interactive-Quick-Reports-(was-Notes-in-V3.0)-p12735768.html
+
#  init- run once, on construction
 +
#  active_changed- run when active-changed is triggered
 +
#  db_changed- run when db-changed is triggered
 +
#  main- run once per db change, main process (a generator-must use yield at least once. '''yield True''' means true that there is more; '''yield False''' means all done)
  
http://www.nabble.com/QuickReports-and-TextBufDoc--tf4537797.html
+
There are methods for saving/loading data, and interacting with the gui. For more details, see [[Gramplets]].
  
http://www.nabble.com/Report-Interface-tf4559738.html
+
== Discussion ==
 +
This type of proposal is discussed on these threads:
 +
*http://www.nabble.com/A-ScreenDoc-idea-t847639.html
 +
*http://www.nabble.com/Re:-Interactive-Quick-Reports-(was-Notes-in-V3.0)-p12735768.html
 +
*http://www.nabble.com/QuickReports-and-TextBufDoc--tf4537797.html
 +
*http://www.nabble.com/Report-Interface-tf4559738.html
  
 
There is also a Feature Request to remind us:
 
There is also a Feature Request to remind us:
 +
*{{bug|1291}} Interactive Context Sensitive Data Explorers
  
http://bugs.gramps-project.org/view.php?id=1291
+
[[Category:GEPS|M]]

Revision as of 01:17, 9 August 2015

Gnome-important.png
GEPS Closed

This GEPS (Gramps Enhancement Proposal) is closed and available in the version of Gramps indicated below.
Do not edit this page. Submit bugs/features to https://gramps-project.org/bugs/.

This proposal has now been implemented, and is in GRAMPS 3.1 as the Gramplets View

Proposed changes for enhancing GRAMPS by adding a new GUI API that allows data to be displayed on the screen, with graphical objects such as tables, buttons, text entry, links, etc. This would effectively be able to turn a user plugin into an interface for moving, say, the active person in the main window, or, possibly, for user-defined data entry. . See Gramplets for development information, Gramps 3.1 Wiki Manual - Gramplets for information on using them, and Third-party Plugins for a list of additional Gramplets.

Motivation

Allows users to add to the GRAMPS interface. A new page, currently called "Gramplets", would be created that allows for customized "gramplets" that perform various functions (other than tools and reports). This might include: interactive shells, TODO lists, logs, debugging tools, and various "folders" for organizing groups of people, families, or other objects.

Details

A prototype is now available for exploration and testing. To activate the prototype, add the following line to your .gramps/keys.ini file in the interface section:

data-views= MyGrampsView,PersonView,RelationshipView,FamilyListView,PedigreeView,EventView,SourceView,PlaceView,MediaView,RepositoryView,NoteView

This should be all on one line. You can change the order (and leave some pages out) as well with this key. (You can also add pages multiple times, but that isn't as useful as the active object on one page will change it on another).

On start up, the file gramplets.ini is looked for in the user's .gramps subdirectory. If it is not found, a set of gramplets are created, currently a Welcome Message Gramplet and a Stats Gramplet.

Mygramps.png

You can drag the Properties button (top left) of each gramplet to move it around the screen. Clicking the Properties will (currently) detach the gramplet from My Gramps and place it in its own window. The window will stay open regardless of page (relationship, pedigree, etc). Closing the detached view will put it back onto the Gramplets view. If you quit Gramps with a open gramplet, when you start gramps again, it will open automatically.

Detached.png

You can add new gramplets by right clicking on an open space on Gramplets. You can also change the number of columns by right-clicking an open area on the Gramplets page.

Gramplets

What is a GRAMPS gramplet? A GRAMPS gramplet is a view of data that either changes dynamically during the running of GRAMPS, or provides interactivity to your genealogical data. What is the difference between gramplets, reports, quick views, and tools?

  1. Reports provide a static output format of your data, typically for printing
  2. Quick View provides a typically short, interactive listing derived from your data
  3. Tools provide a method of processing your data
  4. Gramplets provide a dynamic view and interface to your data

There are currently 9 proof-of-concept gramplets:

  1. Welcome Gramplet
  2. Top Surnames Gramplet
  3. Surname Cloud Gramplet
  4. TODO Gramplet
  5. Statistics Gramplet
  6. Python Gramplet
  7. News Gramplet
  8. Session Log Gramplet
  9. Calendar Gramplet

This section will describe each gramplet and its proposed functionality

Welcome Gramplet

Welcomegadget.png

The welcome gramplet gives an introductory message to new users, and some basic instructions.

TODO: add links to parts of manual, links to bring up windows.

Top Surnames Gramplet

Topgadget.png

The top surnames gramplet shows the top 10 (by default) used surnames. Double-click a surname to run the Same Surnames Quick View.

Change the number of names displayed by editing this section in ~/.gramps/gramplets.ini

Surname Cloud Gramplet

Surnamecloud.png

The surname cloud gramplet shows the top 100 (by default) used surnames. Double-click a surname to run the Same Surnames Quick View. Mouse over the name to see percentage and counts.

Change the number of names displayed by editing this section in ~/.gramps/gramplets.ini

TODO Gramplet

Todogadget.png

The TODO gramplet is free form text. This is persistent between sessions. Open more than one to save different info. Change the title of the gramplet by editing the section name in ~/.gramps/gramplets.ini

Statistics Gramplet

Statgadget.png

The Statistics gramplet runs a copy of the code from the Statistics report.

Python Gramplet

Pythongadget.png

The Python gramplet brings up a Python Shell for interpreting python expressions. You can type most any (single line) Python expression. In addition, the environment has been populated with some useful variables, including self (this Python gramplet), Date, uistate and dbstate. The Date entry is a date object constructor, and can be used for date arithmetic. For example, you might be interested in answering these questions:

What was the date 56 years ago:

> Date(2007, 12, 31) - 56
1951-12-31

How old was someone on Sept 3, 1955 who was born on June 7, 1922:

> Date(1955, 9, 3) - Date(1922, 5, 7)
(33, 3, 27)

(About 33 years, 3 months, and 27 days). When did they turn 21 years old?

> Date(1922, 5, 7) + 21
1943-05-07

You can also add years, months, and days:

> Date(1980) + (0, 0, 25)
1980-01-26

News Gramplet

Newsgadget.png

The News gramplet reads the wiki news page. TODO: add links and formatting.

Session Log Gramplet

Loggadget.png

The session log keeps track of activity in this session. By default, it only shows each entry once. Change this behavior by editing this section in ~/.gramps/gramplets.ini. Click a name to change the active person; double-click to bring up the edit page for that person.

Calendar Gramplet

Calendargadget.png

The Calendar gramplet shows a monthly calendar, with events marked (in bold day numbers). Double-click a day to run the "On This Day" Quick Report.

Development

These are all defined in src/plugins/DefaultGramplets.py

The simplest gramplet:

from DataViews import register

def init(gui):
    gui.set_text("Hello world!")

register(type="gramplet",             # case in-senstitive keyword "gramplet"
         name="Hello World Gramplet", # name, unique among gramplets
         height = 20,               # default size
         content = init,            # function/class; takes guigramplet
         title="Sample Gramplet",     # default title, user changeable
         )

Using the Gramplet class, however, provides more functionality. It has a number of method possibilities:

  1. init- run once, on construction
  2. active_changed- run when active-changed is triggered
  3. db_changed- run when db-changed is triggered
  4. main- run once per db change, main process (a generator-must use yield at least once. yield True means true that there is more; yield False means all done)

There are methods for saving/loading data, and interacting with the gui. For more details, see Gramplets.

Discussion

This type of proposal is discussed on these threads:

There is also a Feature Request to remind us:

  • 1291 Interactive Context Sensitive Data Explorers