It is currently Wed Dec 13, 2017 4:38 am


Latest GIMP Scripts & Plug-ins

All times are UTC - 5 hours [ DST ]



Post new topic Reply to topic  [ 9 posts ] 
Author Message
 Post subject: Script and Plugin Menu Placement Points for script-fu and python-fu
PostPosted: Thu Jan 28, 2016 2:47 am  (#1) 
Offline
GimpChat Member
User avatar

Joined: Aug 13, 2015
Posts: 312
Location: Somewhere between lost and found.
This will bore to death someone who does not write their own scripts/plugins. In fact, it will bore You to death even if You do! It's meant as a reference, and is probably not worth reading unless You do write scripts and plugins for The GIMP!, and want to "know it all" about doing so. Dont say I didn't warn you. :rasp

Some time ago a short discussion happened here about where, as in different menus, scripts could be assigned to appear. In the course of the discussion, it was noted that there appeared to be some "hidden" locations which could be assigned to, but an exhaustive list of these places was unknown.

Let me say this now. Not every script or plugin should be assigned to appear in an unusual place. People expect them to be under the "Filters" menu. But occasionally, a script or plugin obviously should go elsewhere, the wonderful Path manipulation scripts by offnuts for example. So just because these locations are known, doesn't mean to scatter scripts to hell and gone through the menus!See note on Comment below.

I am not up on scheme syntax, heck I can barely read it let alone write it, so these illustrations are relative to Python.

In the registry section of a plugin, a menu location is assigned. It typically starts with a notation inside < and > brackets. The most used one is <Image>. These alternates are:

Context Menus:
  • <Vectors> This adds Your item to the pop-up menu (right click menu) on the "Path Dialogue".
  • <Palettes> This adds your item to the context menu of the "Palettes Dialogue".
  • <Brushes> This adds your item to the context menu of the "Brushes Dialogue".
  • <Gradients> This leads to the "Gradients Dialogue" context menu.
  • <Channels> This leads to the "Channels Dialogue" context menu. (See note below)
  • <Layers> This leads to the context menu for the "Layer Dialogue".(See Channel note below)
  • <Colormap> This leads to the context menu of the "Colormap Dialogue".
  • <Dynamics> This leads to the "Paint Dynamics Dialogue" context menu.
  • <Buffers> The "Buffers Dialogue" context menu.
  • <Patterns> The "Patterns Dialogue" context menu.
  • <ToolPresets> The "Tool Presets Dialogue" context menu.
  • <Fonts> The "Fonts Dialogue" context menu.

Main Program Menus:

Installing into main menus is done three ways:
  1. Using "<Image>" as Your parent level of placement, and providing only Your script's name afterword, creates a new top level menu which is just a button firing Your script. NOTE: This type of entry should only be used for testing and debugging. If You release Your script PLEASE, PLEASE, PLEASE do not leave it like this! It bothers most people to have their comfortable interface messed with.See note on Comment below.
  2. Using "<Image>/some_non_existent_menu" as Your parent of placement, creates the "some_non_existent_menu" menu, with Your script as a selection. NOTE: While not as big an issue as above, the same warning could apply here. Especially if Your choice of Menu Name isn't conscientious and well thought up. If You release Your script PLEASE, PLEASE, PLEASE seriously reconsider this type of placement! It bothers most people to have their comfortable interface messed with.See note on Comment below.
  3. Using "<Image>/some_existing_menu" as Your parent of placement, inserts Your script into said menu, at the bottom, or in some cases, according to hard coded decisions.
  4. I Lied! There is a fourth way! Some menus are organized into named sections. See the next part for details.

Hidden Locations:
See the Development section which follows as well.

Some, not all, of the main menu selections in The GIMP! are organized into named parts. These parts are usually, but again not always, defined by separation markers in the menu. It took some experimenting, and reading some source code, but I believe I found them all. The "table" below gives the location prefix, the menu it will install to, and a brief explanation of where in the menu it will appear. In all cases, it will appear below the normal items in that section. Entries which simply appear as expected in named sub-menus are not listed below.

    File Menu
  • <Image>/File/Acquire -- File Menu -- Create Sub-Menu -- Top portion of the sub menu. (Doesn't create a sub-menu, but uses the "Create" sub-menu.)
  • <Image>/File/Open -- File Menu -- Top portion of the menu, above the "Open Recent" sub-menu.
  • <Image>/File/Open Recent -- File Menu -- Open Recent sub-menu -- Below the Document History entry.
  • <Image>/File/Open Recent/Files -- File Menu -- Open Recent sub-menu -- Top part, below the last file on the last.
    Edit Menu
  • <Image>/Edit/Undo -- Edit Menu -- Below the Undo History entry.
  • <Image>/Edit/Cut -- Edit Menu -- Below the Cut entry.
  • <Image>/Edit/Copy -- Edit Menu -- Below the Copy Visible entry.
  • <Image>/Edit/Paste -- Edit Menu -- Below the Paste Into entry.
  • <Image>/Edit/Clear -- Edit Menu -- Below the Clear entry.
  • <Image>/Edit/Fill -- Edit Menu -- Below Fill With Pattern entry.
  • <Image>/Edit/Stroke -- Edit Menu -- Below Stroke Path entry.
  • <Image>/Edit/Preferences -- Edit Menu -- Below Units entry.
    Select Menu
  • <Image>/Select/Modify -- Select Menu -- Below Border entry.
    Image Menu
  • <Image>/Image/New -- Image Menu -- Below the Duplicate entry.
  • <Image>/Image/Mode/Color Profile -- Image Menu -- Mode sub-menu -- Below Convert to Color Profile, but above entries added via <Image>/Image/Mode.
  • <Image>/Image/Transform/Flip -- Image Menu -- Transform sub menu -- Below Flip Vertically entry.
  • <Image>/Image/Transform/Rotate -- Image Menu -- Transform sub menu -- Below Rotate 180 entry, but above other plugins simply added to <Image>/Image/Transform.
  • <Image>/Image/Resize -- Image Menu -- Below Print Size entry.
  • <Image>/Image/Scale -- Image Menu -- Below Scale Image.
  • <Image>/Image/Crop -- Image Menu -- Below Zealous Crop entry.
  • <Image>/Image/Structure -- Image Menu -- Below Align Visible Entry.
    Layer Menu
  • <Image>/Layer/New -- Layer Menu -- Below Duplicate Layer entry.
  • <Image>/Layer/Structure -- Layer Menu -- Below Delete Layer
  • <Image>/Layer/Text -- Layer Menu -- Below Text Along Path (Only visible if a text type layer is selected).
  • <Image>/Layer/Stack/Select -- Layer Menu -- Stack sub-menu -- Upper portion of menu.
  • <Image>/Layer/Stack/Position -- Layer Menu -- Stack sub-menu -- Lower portion of menu, but above scripts added by <Image>/Layer/Stack.
  • <Image>/Layer/Mask/Modify -- Layer Menu -- Mask sub-menu -- Below Delete Layer Mask entry.
  • <Image>/Layer/Mask/Properties -- Layer Menu -- Mask sub-menu -- Below Disable Layer Mask entry.
  • <Image>/Layer/Mask/Selection -- Layer Menu -- Mask sub-menu -- Below Intersect with Selection entry, but above scripts added to <Image>/Layer/Mask.
  • <Image>/Layer/Transparency/Modify -- Layer Menu -- Transparency sub-menu -- Below Remove Alpha Channel.
  • <Image>/Layer/Transparency/Selection -- Layer Menu -- Transparency sub-menu -- Below Intersect with Selection, but above scripts added to <Image>/Layer/Transparency.
  • <Image>/Layer/Transform/Flip -- Layer Menu -- Transform sub-menu -- Below Flip Vertically Entry.
  • <Image>/Layer/Transform/Rotate -- Layer Menu -- Transform sub-menu -- Below Arbitrary Rotate, but above scripts added via<Image>/Layer/Transform.
  • <Image>/Layer/Resize -- Layer Menu -- Below Layer to Image Size.
  • <Image>/Layer/Scale -- Layer Menu -- Below Scale Layer.
  • <Image>/Layer/Crop -- Layer Menu -- Below Autocrop Layer entry, above scripts added to <Image>/Layer.
    Colors Menu
  • <Image>/Colors/Invert -- Colors Menu -- Below Value Invert entry.
  • <Image>/Colors/Map/Colormap -- Colors Menu -- Map sub-menu -- Below Set Colormap ... entry.
  • <Image>/Colors/Modify -- Colors Menu -- Lower portion of menu, but above scripts added to <Image>/Colors.
    Filters Menu
  • <Image>/Filters/Light and Shadow/Light -- Filters Menu -- Light and Shadow sub-menu -- Upper third of menu, above first separator.
  • <Image>/Filters/Light and Shadow/Shadow -- Filters Menu -- Light and Shadow sub-menu -- Middle third of menu, above second separator.
  • <Image>/Filters/Light and Shadow/Glass -- Filters Menu -- Light and Shadow sub-menu -- Lower third of menu, below second separator, but above entries in <Image>/Filters/Light and Shadow.
  • <Image>/Filters/Animation/Animators -- Filters Menu -- Animation sub-menu -- Above the first separator.
  • <Image>/Filters/Menus -- Filters Menu -- Appear in the second section down. NOTE: This section is normally reserved for scripts which have created sub-menus of their own for the Filters menu by adding themselves to <Images>/Filters/some menu name. Placing a single script here would be very bad form and liable to incur someone's wrath!See note on Comment below.
  • <Image>/Filters/Languages -- Filters Menu -- Appear in the same section as Python-fu and Script-fu, third section down.
  • <Image>/Filters/Extensions -- Filters Menu -- Appear in the same section as Python-fu and Script-fu, third section down, but towards the bottom of the section.
    Windows Menu
  • <Image>/Windows/Images -- Windows Menu -- Just below the divider after Toolbox, but above the loaded images buttons which appear when images are active.
  • <Image>/Windows/Docks -- Windows Menu -- Just above the divider before the Hide Docks entry.
    Help Menu
  • <Image>/Help/Programming -- Help Menu -- In the same section as the procedure and plug in browsers.

Others of unusual interest:
NOTE: These are for backward compatibility with scripts written for older versions of The GIMP! They should NEVER be used in writting new code!
  • <Toolbox> -- By itself is synonymous with <Image>.
  • <Toolbox>/Xtns -- Synonymous with <Image>/Filters/Extensions. NOTE: Xtns is only valid with <Toolbox>, if used elsewhere, a new sub-menu named Xtns is created.

Development For Scripts/Plugins in Hidden Areas
While creating this document I had to rewrite the register portion of a Python script several times. I would then use 'Filters-> Script-fu -> Refresh Scripts' to update their placement. While this normally works, I found that in many cases it failed when the code was installed outside the Filters menu. Whether this was just sporadic behaviour, or is meant to work this way I do not know as it hasn't come up before, but I had to actually restart The GIMP! for these changes to work. Just an FYI.

Notes:
  • <Channels> - Gimp will error out in Python (and presumably Scheme) if the script/plugin does not take at least a image, and a drawable parameter. It also expects the first param to be the run_type parameter that the various *-fu libraries handle automatically. So if Your script/plugin is a *-fu variety You may ignore this, otherwise You must have it.
  • The following menus seem to be unreachable:
    • Gradient Editor
    • Selection Editor
    • Pointer information
    • Sample Points
    • Colors (the Dialogue)
    • <Image>/Filters/Plug-Ins (A hidden named area)
  • Comment: Note that this is not my own opinion, but is one of the three largest complains I have seen script/plugin users voice. I believe this -- the author wrote it, the author knows where it belongs. The comments were included to help authors avoid complaints, and wasting their time answering such complaints. Not as gospel/policy/or cannon on the issue, but simply food for thought.
    The other two biggies are:
    1. "It doesn't do what I want!" -- Too bad. The Author probably wrote for their own purpose in the first place. If they were kind enough to recode it (sometimes way too often) to provide support for others, then be grateful. If they did not, be grateful anyway, they didn't have to release it in the first place.
    2. "Where is it?" -- Authors should address this one in their release notes/forum threads/or elsewhere. I add code to my scripts to make this information visible in the procedure or plug-in browsers as part of the blurb text.


For those who are truly curious, this information was gleaned through trial and error, and reading some scripts which come with The GIMP!. The trial and error part was after reading a source file at the GIT repository for The GIMP!
Version: 2.8.x series
Branch: Master
Directory: menus
File: image-menu.xml.in
Direct link here.

[EDIT] I added some additional information on the comments in the main document, to the "notes" at the end; and toned done the first one. The purpose of the comments was being misunderstood.

[EDIT] Added a section on an issue had with developing the test code for this document.

_________________
The answer was 42. The question is long forgotten. The computer that solved it is now destroyed.
The MK-2 has been built. Should this be the next question?
(Solve if you can ... ;) )
Image


Last edited by jazzon on Thu Jan 28, 2016 2:12 pm, edited 2 times in total.

Share on Facebook Share on Twitter Share on Orkut Share on Digg Share on MySpace Share on Delicious Share on Technorati
Top
 Post subject: Re: Script and Plugin Menu Placement Points for script-fu and python-f
PostPosted: Thu Jan 28, 2016 3:56 am  (#2) 
Offline
Script Coder
User avatar

Joined: Jun 22, 2010
Posts: 1068
Location: Here and there
In amongst your fervent pleas not to create menu entries that mess with users "comfortable interface" I feel you've missed one very important point.

As there isn't a self-revealing mechanism, Script/Plug-in writers should make it clear exactly where their scripts will bury their menu entries and what those entries are. All too often people have installed scripts and then had to ask for help finding the menu entry.

Kevin


Top
 Post subject: Re: Script and Plugin Menu Placement Points for script-fu and python-f
PostPosted: Thu Jan 28, 2016 4:48 am  (#3) 
Offline
GimpChat Member

Joined: Jan 20, 2013
Posts: 7057
Location: roma, italy
IMO the only important point is the one by Kevin (sorry if I didn't recently follow that rule, like I did in the past).
About putting every filter under Filters + submenu + submenu etc and any Script under Script-Fu + submenu + submenu etc, I disagree: are you REALLY convinced Jazzon that only ONE menu entry for hundreds (thousands?) of filters makes the search easier? I think the opposite, and I changed menu also for existing filters of other people to get a better visibility on my Gimp functionality. And I know other people here did the same.
Anyhow thanks for your effort to help.
I have a different simple suggestion: name the file which contains the created filter in such a way to "address" the user where he/she will be find it or at least where it's searchable under Gimp help.
For some of the "ancient" filters sometimes it's very discouraging look into the Help and not find it.

_________________
Vanitas vanitatum et omnia vanitas.


Top
 Post subject: Re: Script and Plugin Menu Placement Points for script-fu and python-f
PostPosted: Thu Jan 28, 2016 7:34 am  (#4) 
Offline
GimpChat Member
User avatar

Joined: Dec 26, 2014
Posts: 174
Location: Cumbria
jazzon wrote:
...... In fact, it will bore You to death even if You do! ......

On the contrary I found it fascinating, informative and learned something, and so it’s a good day as another piece fits into place in the 100000 piece gimp jigsaw puzzle. I may never place scripts in most of those locations but its good to know how if I want to.

:tyspin jazzon

Steve


Top
 Post subject: Re: Script and Plugin Menu Placement Points for script-fu and python-f
PostPosted: Thu Jan 28, 2016 12:01 pm  (#5) 
Offline
GimpChat Member

Joined: May 16, 2010
Posts: 13984
Location: USA
That is the beauty of GIMP. You can make your menu look however you wish. Whatever is easiest for you to use. :)
When i write a filter i always add the location where the filter can be found in the main topic thread. There is also a tutorial here at Gimp Chat on how to change the location of a filter for your convenience. I do however believe that the exact filter name should be added to it's description code. ie this filter does this - my-filter.scm This will make it loads easier to remove any certain filter you happen to find in the menus and really don't need that particular filter installed.
Of course you can do this via the plug-in browser also but having it included in the filters description makes it faster to recognize an exact filter name.


Top
 Post subject: Re: Script and Plugin Menu Placement Points for script-fu and python-f
PostPosted: Thu Jan 28, 2016 1:07 pm  (#6) 
Offline
GimpChat Member
User avatar

Joined: Aug 13, 2015
Posts: 312
Location: Somewhere between lost and found.
paynekj: Actually I was quoting complaints I have heard from many others. My personal opinion is that the author wrote it, the author knows where is best for it. Those of us who choose to install it, made a choice to install it as the author wrote it.

dinasset: No I don't feel that they should all go into the menu and sub-menu of Filters. That gets way over crowded as it is. I too recode other peoples entry locations to suit my own needs, and I use GURM (A resource manager for The GIMP! to further control the onslaught. But as a script author myself, I feel it is the authors responsibility to not abuse things. If we all put our scripts DIRECTLY into the filters menu, we get just what You described, mayhem. Intelligent use of the various options and sub menus is best, both inside and outside the Filters menu. Apparently my lack of social graces spilled over again. This was simply meant to be an exposition of the extra information, not a critique of techniques. I apologize if it came off that way.

Steve: Just glad to know someone might find the information useful. In truth I didn't expect anyone to actually READ the thing ... :hehe

Rod: I agree about the naming conventions, and the documentation issue. Read on below

To All of those who read it:
Thank You! :jumpclap Feedback, positive or negative, is always welcome. It is only in this way I can improve my writing of these kind of things.

Several have mentioned what I find to be a big problem. The fact that installation locations aren't self revealing. I stole an idea from one of the masters here ofnuts. In each of his register functions he includes a variable named "whereami" or "whereiam" or some such, which translates into the scripts exact location on Your hard drive after install. This becomes part of the "blurb" text in the registration.

I go one further and added an extra line which defines the menu install point, and adds it to the blurb. Most of my plugins have internal names that start with "jaz_" or "jazzon_" (I have probably missed a few along the way), and the files themselves always start with "jazzon-" or "jazzon_", to make locating, managing, and removal easier for the end user.

_________________
The answer was 42. The question is long forgotten. The computer that solved it is now destroyed.
The MK-2 has been built. Should this be the next question?
(Solve if you can ... ;) )
Image


Last edited by jazzon on Fri Jan 29, 2016 9:23 am, edited 1 time in total.

Top
 Post subject: Re: Script and Plugin Menu Placement Points for script-fu and python-f
PostPosted: Thu Jan 28, 2016 5:01 pm  (#7) 
Offline
Script Coder
User avatar

Joined: Oct 25, 2010
Posts: 3726
jazzon wrote:
paynekj: Actually I was quoting complaints I have heard from many others. My personal opinion is that the author wrote it, the author knows where is best for it. Those of us who choose to install it, made a choice to install it as the author wrote it.

dinasset: No I don't feel that they should all go into the menu and sub-menu of Filters. That gets way over crowded as it is. I too recode other peoples entry locations to suit my own needs, and I use GURM (A resource manager for The GIMP! to further control the onslaught. But as a script author myself, I feel it is the authors responsibility to not abuse things. If we all put our scripts DIRECTLY into the filters menu, we get just what You described, mayhem. Intelligent use of the various options and sub menus is best, both inside and outside the Filters menu. Apparently my lack of social graces spilled over again. This was simply meant to be an exposition of the extra information, not a critique of techniques. I apologize if it came off that way.

Steve: Just glad to know someone might find the information useful. In truth I didn't expect anyone to actually READ the thing ... :hehe

Rod: I agree about the naming conventions, and the documentation issue. Read on below

To All of those who read it:
Thank You! :jumpclap Feedback, positive or negative, is always welcome. It is only in this way I can improve my writing of these kind of things.

Several have mentioned what I find to be a big problem. The fact that installation locations aren't self revealing. I stole an idea from one of the masters here offnuts. In each of his register functions he includes a variable named "whereami" or "whereiam" or some such, which translates into the scripts exact location on Your hard drive after install. This becomes part of the "blurb" text in the registration.

I go one further and added an extra line which defines the menu install point, and adds it to the blurb. Most of my plugins have internal names that start with "jaz_" or "jazzon_" (I have probably missed a few along the way), and the files themselves always start with "jazzon-" or "jazzon_", to make locating, managing, and removal easier for the end user.

That's "ofnuts" with a single f and I'm no master.

The variable is "whoami". I got the idea from a discussion here. But it's not an indication of where script/plugin shows up in the menu but a mere indication of what script/plugin file corresponds to this menu. Nice for "maintenance" but that's about it.

By the way to find the menu location of a plugin, just use the very overlooked "Help>Procedure browser".

_________________
Image


Top
 Post subject: Re: Script and Plugin Menu Placement Points for script-fu and python-f
PostPosted: Fri Jan 29, 2016 9:33 am  (#8) 
Offline
GimpChat Member
User avatar

Joined: Aug 13, 2015
Posts: 312
Location: Somewhere between lost and found.
ofnuts wrote:
That's "ofnuts" with a single f and I'm no master.

:gaah :bawl AACK! I have defiled the master! Please forgive me Oh Mighty One! :bowdown :geek

Fixed ;)


ofnuts wrote:
By the way to find the menu location of a plugin, just use the very overlooked "Help>Procedure browser".

I don't use it often, but You are correct it is overlooked often. In fact I rarely see it mentioned, even in these forums.

_________________
The answer was 42. The question is long forgotten. The computer that solved it is now destroyed.
The MK-2 has been built. Should this be the next question?
(Solve if you can ... ;) )
Image


Top
 Post subject: Re: Script and Plugin Menu Placement Points for script-fu and python-f
PostPosted: Sat Jan 30, 2016 9:41 am  (#9) 
Offline
GimpChat Member

Joined: May 16, 2010
Posts: 13984
Location: USA
jazzon wrote:
ofnuts wrote:
That's "ofnuts" with a single f and I'm no master.

:gaah :bawl AACK! I have defiled the master! Please forgive me Oh Mighty One! :bowdown :geek

Fixed ;)


ofnuts wrote:
By the way to find the menu location of a plugin, just use the very overlooked "Help>Procedure browser".

I don't use it often, but You are correct it is overlooked often. In fact I rarely see it mentioned, even in these forums.

Yes i normally just look thru Help>Plug-in Browser to search filter location. :) I didn't realize procedure browser also had that capability.


Top
Post new topic Reply to topic  [ 9 posts ] 

All times are UTC - 5 hours [ DST ]


   Similar Topics   Replies 
No new posts Text script request (random placement)

2

No new posts Attachment(s) Guides to Path (scheme script, now python script more advanced).

28

No new posts Attachment(s) Label Number(s) From Active Path Points (.py script)

4

No new posts Attachment(s) Select guides surrounding active path points (py. script)

18

No new posts Script-Fu Menu

3



* Login  



Powered by phpBB3 © phpBB Group