Toolbox Configuration

The lower part of the toolbox containing the buttons for functions and tools can be modified from within the program using the toolbox editor EditToolbox.

It can be also customised by editing file ui/toolbox.xml. This is also the file you should copy to another account or machine to replicate the toolbox configuration there. Similarly to custom keyboard shortcuts, the file located in the user's directory, which usually means ~/.gwyddion (Unix) or Documents and Settings\gwyddion (MS Windows). A good starting point for customisation is the default ui/toolbox.xml file installed with Gwyddion under share/gwyddion.

The number buttons in a row is controlled by the width attribute of the top level element toolbox. To change it to five just change the begining of the file to

<toolbox width='5'>

Expandable and collapsable groups of buttons such as Data Process or Tools are created with tag group. You can create as many or as few groups as you want. Functions of different kinds can placed in one group if you wish. Each group must be identified with a unique id attribute which is, among other things, used to remember which groups were collapsed and which were expanded. The attribute title determines the title:

<group id='proc' title='Data Process' translatable='yes'>

Groups can optionally have a translatable attribute that specifies if the title should be translated. This is most useful for groups present in the default toolbox configuration. When you add custom groups you will probably already give them names in your preferred language.

Individual buttons are created with elements item:

<item type='proc' function='align_rows' icon='gwy_line_level' run='non-interactive'/>

Each item must have the type attribute, defining the function type. Unless the type is 'empty' it must also have a function attribute defining the specific function. Function names can be located in the module browser (InfoModule Browser), where they are listed in Registered functions for each module; or in the on-line module browser. The available function types are listed in the following table:

Type nameFunction kind
empty Empty placeholder that can be used for separation or row alignment.
builtin A built-in function, which includes zooming in and out and 3D view activation. There are exacly four: 'display_3d', 'zoom_in', 'zoom_out' and 'zoom_1_1'.
proc A two-dimensional data (image) processing function. It has prefix proc:: in the module browser.
graph A graph function. It has prefix graph:: in the module browser.
volume A volume data function. It has prefix volume:: in the module browser.
xyz An XYZ data function. It has prefix xyz:: in the module browser.
tool A tool. It has prefix tool:: in the module browser.

Data processing functions (inclduing volume and XYZ) can optionally have a run attribute that specifies how the function should be invoked. When it is set to non-interactive the function is executed immediately, without any dialogue asking for parameters (similar to how pressing Ctrl-F runs the last used image processing function). The opposite is interactive which generally does not need to be specified because it is also the default mode. Note that not all functions can be run in both modes: some simple functions never take any user input, other functions always require user input.

The button icon is specified using the icon attribute. Some module functions have icons predefined (so you do not have to specify it) but not all have because the number of available functions is huge. A Gwyddion stock icon can be used or possibly a Gtk+ stock icon. Note Gwyddion icon names have words separated with underscores while Gtk+ icon names use dashes.

If you cannot choose from the provided set of icons it is also possible to draw your own icon and put it to ~/.gwyddion/pixmaps (or its equivalent on other systems), using the same naming convention as Gwyddion icons. It may be useful to start from the GIMP XCF source images for the icons since they contain individual pieces that can be mixed and matched. If you draw a nice icon you are of course encouraged to submit it for inclusion in Gwyddion.

Since tools are accessible only from the toolbox, not listing a tool in ui/toolbox.xml renders it unavailable. Therefore, a special empty item

<item type='tool'/>

can be used to place all tools that have not been explicitly placed yet to the corresponding position (in a pretty much arbitrary order).