The lower part of the toolbox containing the buttons for functions and tools can be modified from within the program using the toolbox editor → .
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
( → ),
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 name | Function 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).