GIMP menu placeholders (Shallow Thoughts)

GIMP menu placeholders

Someone on the gimp-developers list asked whether there was documentation of GIMP's menu hooks.

I wasn't sure what they meant by "hooks", but GIMP menus do have an interesting feature that plug-in writers should know about: placeholders.

Placeholders let you group similar types of actions together. For instance, iever notice that in the image window's File menu, all the things that Open images are grouped together? There's Open, Open as Layers..., Open Location... and Open Recent. And then there's a group of Save actions all grouped together -- Save, Save As..., Save a Copy... and so forth. That's because there's a placeholder for Open in the File menu, and another placeholder for Save.

When you write your own plug-ins, you can take advantage of these placeholders. For instance, I want my Save/Export clean plug-in to show up next to the other Save menu items, not somewhere else down near the bottom of the menu -- so when I register it, I pass menu = "<Image>/File/Save/" so GIMP knows to group it with the other Save actions, even though it's directly in the File menu, not a submenu called Save..

Pretty slick, huh? But how do you know what placeholders are available?

I took a look at the source. In the menus/ subdirectory are all the menu definitions in XML, and they're pretty straightforward. In image-menu.xml you'll see things like <placeholder name="Open">, <placeholder name="Save">

So to get a list of all the menu placeholders, you just need to find all the " grep '<placeholder' menus/*.xml

That's not actually so useful, though, because it doesn't tell you what submenu contains the placeholder. For instance, Acquire is a placeholder but you need to know that it's actually File->Create->Acquire. So let's be a little more clever.

We want to see <menu lines as well as <placeholders, but not <menuitem since those are just individual menu entries. egrep '<(placeholder|menu) will do that. Then pass it through some sed expressions to clean up the output, loop over all the XML files, and I ended up with:

for f in *.xml; do
  echo $f
  egrep '<(placeholder|menu) ' $f | sed -e 's_<placeholder *name="_** _' -e 's_<menu.*name="__' -e 's_"/*>__'
done

It isn't perfect: a few lines still show up that shouldn't -- but it'll get you the list you need. Fortunately the GIMP developers are very good about things like code formatting, so the identation of the file shows which placeholder is inside which submenu.

I only found placeholders in the image window menu, plus a single placeholder, "Outline", in the selection menu popup. I'm a little confused about that menu file: it seems to duplicate the existing Select menu in the image-menu.xml, except that the placeholder items in question -- feather, sharpen, shrink, grow, and border -- are in a placeholder called Outline in selection-menu.xml, but in a placeholder called Modify in image-menu.xml.

Anyway, here's the full list of placeholders, cleaned up for readability. Placeholders are in bold and followed with an asterisk *.

===== image-menu.xml =====
    File
      Create
        Acquire *
      Open *
      Open Recent
        Files *
      Debug
      Save *
      Export *
      Send *
      Info *
    Context
    Edit
      Undo *
      Cut *
      Copy *
      Paste *
      Paste as
      Buffer
      Clear *
      Fill *
      Stroke *
      Preferences *
    Select
      Modify *
    View
    Image
      New *
      Mode
        Color Profile *
      Precision
      Transform
        Flip *
        Rotate *
      Resize *
      Scale *
      Crop *
      Structure *
      Arrange *
      Guides
    Layer
      New *
      Structure *
      Text *
      Stack
        Select *
        Position *
      Mask
        Modify *
        Properties *
        Selection *
      Transparency
        Modify *
        Selection *
      Transform
        Flip *
        Rotate *
      Properties
        Opacity
        Layer Mode
      Resize *
      Scale *
      Crop *
    Colors
      Invert *
      Auto
      Components
      Desaturate
      Map
        Colormap *
      Info
      Modify *
    Tools
    Filters
      Recently Used
        Plug-Ins *
      Blur
        Motion *
      Enhance
      Distorts
      Light and Shadow
        Light *
        Shadow *
        Glass *
      Noise
      Edge-Detect
      Generic
      Combine
      Artistic
      Decor
      Map
      Render
        Clouds
        Nature
        Pattern
      Web
      Animation
        Animators *
      Menus *
      Languages *
      Extensions *
    Menus *
    Windows
      Recently Closed Docks
      Dockable Dialogs
      Images *
      Docks *
    Help
      Programming *

===== selection-menu.xml =====
    Outline *