Minor detail for the Plugin Registery's developer documentation?

Could the documentation for paths on the help_url and stock_icon have some detail added?

These appear to be ‘relative’ rather than ‘absolute’ paths. Please define the base paths, the format & delimiters for use in the Gramps registration. (Is a leading delimiter needed?)

For the base path of the stock_icon, it appears to be relative to the location of the .gpr.py file. Is there a way to reference the Gramps app installation instead? (To leverage its collection of stock icons.) Or do the individual stock icon image files need to be duplicated in the addon folder?

The stock_icon does not include the file extentsion. Gramps seems to prefer a .png over a .svg of the base name file. Is there a mime fallback order?

For the base path of the help_url, it appears to be relative to the https://www.gramps-project.org/wiki/index.php/wiki path. Is there a way to reference relative to the plugin registration file? And, since GitHub tends to include Readme.md markdown files in each project, could Gramps open that document if included in the addon folder?

Under Attributes for GRAMPLET plugins

 help_url
The URL where documentation for the URL can be found

Under Attributes for VIEW plugins

 stock_icon
The icon in the toolbar or sidebar used to select the view

https://gramps-project.org/api_5_1_x/gen/gen_plug.html#module-gramps.gen.plug._pluginreg

The help_url allows two options, if it starts with “http://”, then the url is used in its entirety. If it doesn’t, then it prepends the string provided with
http://gramps-project.org/wiki/index.php?title=

I don’t know how Gtk looks for icons by extension, but I see that both .svg and .png at least work. svg has the ability to display in correct scale, png does not, although that doesn’t seem to matter since we only use icons for views anyway and the scale is always the same.
You can use default icons installed by Gramps just by naming them, or other system/Theme icons that come standard with Gtk.
Addons can use non-Gramps and non-system icons only if the gpr.py file includes the code to append an additional icon path to the search places. For instance, Graphview has the following code:

        fname = os.path.join(USER_PLUGINS, 'GraphView')
        icons = Gtk.IconTheme().get_default()
        icons.append_search_path(fname)

The addon could use a different icon path by building it differently.

1 Like

Thank you!

Do you know who has edit rights for the Sphinx content management system used for the API docs? Can I request contributor access?.. or do I need to file a MantisBT request instead, specifying the content expansion?

Thanks for those leads & elucidations.

The file extension logic is explained a bit in the source code. The icon image file is expected to be: 1) local, relative to the plugin folder, or; 2) among the core icons in the Gramps installation folder.

There is a separate Path parameter for the icon. A parameter passed there changes the search path for this icon. Cannot tell yet if it appends, prefixes or replaces the existing search directories path for icons. (My guess would be prefix. That would give an ‘override’ opportunity. But it could easily be ‘replaces’… same override although with fewer failback possibilities.)

The icon file can be inside the local folder or, based on the target thumbnail resolution, it looks for folder named for the thumbnail scale, then fails back to a scalable.

It prefers a PNG over a scalable SVG because of the savings in rendering overhead.

I wonder (if a programmer decided on a fixed unique thumbnail size) whether Gramps is smart enough to look for a folder name of the target resolution? i.e., if my thumbnail is pre-defined at 137 pixels square, whether Gramps looks for a 137x137 subfolder that contains a PNG rather than using the SVG file in the “scalable” subfolder?

Looks like Sphinx is not a “content management system” but a “documentation generator” and from what I can find manually built and uploaded by the webmaster ( @gramps-project ) as mentioned here and build instructions here.

2 Likes

Ahhh … so I’d need to find the documents from which Sphinx generates the gen_plug documentation page, create a PR, then wait for the wiki to update to 5.2, or the PR to be merged to Master and discover how to have a single page regenerated from master?

Nah. Maybe I can do the PR portion but gain access to manually update the Sphinx generated page?

@emyoulation Sphinx documentation sources are docstrings of classes and functions and modules e.g. for PluginData:

1 Like

The code indicate an icondir parameter where I’ve been able to get the register to notice the image file placed in that specific subfolder. But it ignores the subfolder hierarchy intimated by documentation… the subfolders named scalable, 16x16, 22x22, 48x48.

And the Gtk docs suggest that the iconsize for the Toolbar is likely set at the “large toolbar” needing 24x24 icons while the Navigation sidebar looks like a “small toolbar” needing 16x16 variants. (Dunno where 22x22 is used!) [Evidently 24x24 is a bordered 22x22]

I have not discovered even a single example addon registration file using the icondir parameter. Are we sure it will work with Windoze… or ANY of the OSes?

See:
https://gramps-project.org/api_5_1_x/_modules/gramps/gen/plug/_pluginreg.html#PluginData

    def _get_icons(self):
        return self._icons

    def _set_icons(self, icons):
        if not isinstance(icons, list):
            raise ValueError('Plugin must have icons as a list')
        self._icons = icons

    def _get_icondir(self):
        return self._icondir

    def _set_icondir(self, icondir):
        self._icondir = icondir

Regarding “icondir”, I did not realize it was even a parameter until you pointed it out. Goes to show that Gramps has lots of abilities not obvious to everyone (or even someone who thinks he is pretty familiar with the code).
See gramps/pluginmanager.py at b43b6bdd6d8a90404a5655589679ee1931bd1b3c · gramps-project/gramps · GitHub for the code that uses this.
It appears that this works just like the lines I copied from GraphView in that it adds the suggested dir to the Gtk icon search path. I don’t see any reason why this should not work.

I found no mention of Gtk searching sub-directories of additional items in the search path, unless the search path is a whole theme, so I’m not too surprised if they don’t work.
See Gtk.IconTheme - Classes - Gtk 3.0
The way we use this it only loads the specific icon directly from the indicated path “legacy feature”. I can tell this feature of Gramps was written quite a while ago, and probably never used since.

1 Like

Glad to know I’m finding new things to be tested!

I tried path variations for a couple hours last night and only got it to recognize one single folder level. Wouldn’t do a folder 2 levels deep or find anything but 1 file.

Will probably use inkscape to make distinctively different family of icons for the resolutions and see if it is polling locations in the way implied. (I strongly suspect that it is not correctly selecting resolution contextually… just scaling one of the variants. But which one?)