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.
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:
- 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.
- 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.
- 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.
- 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 AreasWhile 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:
- "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.
- "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 ...
)