GwyToolFunc()

void
(*GwyToolFunc) (GwyTool *tool);

Prototype of functions implementing various interactive tool functionality.

Most functions have this prorotype, taking just a single tool argument. They obtain additional information by querying the tool properties and state, e.g. using gwy_tool_get_selection() or gwy_tool_get_changed_flags().

GwyToolSelectionFunc()

void
(*GwyToolSelectionFunc) (GwyTool *tool,
                         gint hint);

GwyToolUpdateFunc()

void
(*GwyToolUpdateFunc) (GwyTool *tool,
                      GwyToolChangedFlags changed);

gwy_register_tool()

GwyToolClass *
gwy_register_tool (const gchar *name);

Registers a new tool.

The function returns a new programatically constructed tool class. It does not do anything useful – in fact, in such state it is not even a valid tool. Provide additional information and functionality using functions such as gwy_tool_class_set_info(), gwy_tool_class_set_basics(), gwy_tool_class_set_functions(), gwy_tool_class_set_updates() or gwy_tool_class_set_format_styles().

The tool name is used for settings but also to construct the class name. For this, the name is transformed to an identifier. Choose a reasonably unique name. It is not possible to have two tools called ‘bad’ and ‘Bad’ or ‘wo-rse’ and ‘wo_rse’.

Registration may return NULL on fatal failures, such as giving " " as the tool name. When a duplicate name is encountered, the function tries to extend the name by a random string to proceed, which is awkward but probably survivable.

gwy_tool_class_set_info()

void
gwy_tool_class_set_info (GwyToolClass *tool_class,
                         const gchar *icon_name,
                         const gchar *title,
                         const gchar *tooltip);

Defines basic information about a tool implementation.

The information is static class properties and have to be set before any object is instantiated. It is expected they are set when a module registers the tool.

Although Gwyddion can handle a missing title or tooltip, users may be consfused. Please specify all the information. By tradition, the strings are translatable but passed untranslated.

gwy_tool_class_set_basics()

void
gwy_tool_class_set_basics (GwyToolClass *tool_class,
                           GwyToolFlags flags,
                           gsize tool_data_size,
                           GwyParamDef *paramdef,
                           gint selection_max_objects);

Defines basic features and behaviours of a tool implementation.

The information is static class properties and have to be set before any object is instantiated. It is expected they are set when a module registers the tool.

The tool data memory is allocated and freed automatically. It can be obtained by the tool implementation by gwy_tool_get_tool_data(). Pass something like sizeof(MyToolGUI).

If setup_selection() passed to gwy_tool_class_set_functions() would only set the maximum number of objects in the selection, which is common, you can instead pass the number here and keep the setup function NULL.

gwy_tool_class_set_functions()

void
gwy_tool_class_set_functions (GwyToolClass *tool_class,
                              GwyToolFunc setup,
                              GwyToolFunc shutdown,
                              GwyToolFunc switch_data);

Defines fundamental functions of a tool implementation.

The information is static class properties and have to be set before any object is instantiated. It is expected they are set when a module registers the tool.

The only mandatory function is switch_data , which also must call gwy_tool_set_layer() upon the data switch (unless switching to no-data), even if it was to the same layer. Data switching is done even if the tool is hidden and has the GWY_TOOL_HIDDEN_INACTIVE flag set. It can avoid expensive computations by only updating various information about the data and leaving computations to until it is shown. However, to receive an update notification with the correct flags set, it needs to remember this by calling gwy_tool_queue_update().

Nevertheless, the only function which reasonable tools may pass as NULL is shutdown if they have no dynamic data.

When switch_data is called, tool functions such as gwy_tool_get_data_view(), gwy_tool_get_file() or gwy_tool_get_data_id() already return the new values. The previous GwyFile still exists (but particular data items may not). Function switch_data is also called when the primary data object is replaced in the file, even though the current data window remains the same in this case.

When shutdown is called, the dialog has not been destroyed yet and the function can still access all its widgets. It also means that widgets persist through shutdown and may still emit signals afterwards. GwyTool makes the entire dialog insensitive prior to calling shutdown , preventing the usual source of such signals: focus-out events occurring during window destruction. If the tool does something clever, it is recommended to disconnect manually connected widget signal handlers in the shutdown functions. There is no needed to disconnect from standard signals such as buttons, dialog response or “item-changed” though.

gwy_tool_class_set_selection_setup()

void
gwy_tool_class_set_selection_setup (GwyToolClass *tool_class,
                                    GwyToolFunc setup_selection);

Defines the selection setup function for a tool implementation.

The function is called whenever the selection object is switched, with the layer and selection already existing. If the tool needs to set up its selection in a specific manner, this function is the place to do it. Most tools only set the maximum number of selection objects, which can be defined using gwy_tool_class_set_basics() and does not require a dedicated function. If both are set, the maximum number of objects is set before calling setup_selection .

gwy_tool_class_set_updates()

void
gwy_tool_class_set_updates (GwyToolClass *tool_class,
                            GwyToolChangedFlags changes_mask,
                            GwyToolUpdateFunc update,
                            GwyToolSelectionFunc selection_changed);

Defines update functions and behaviour of a tool implementation.

The information is static class properties and have to be set before any object is instantiated. It is expected they are set when a module registers the tool.

The update function is called after GwyTool itself has already processed the change. Possibly a long time after if the tool has the GWY_TOOL_HIDDEN_INACTIVE flag set.

The update functions are not called upon data switching; the tool is already sufficiently notified that everything has changed and no valid data are available in the switch_data() function. Selection adjustments are the only changes not going through the main update function. There are exception, however. If a tool has the GWY_TOOL_HIDDEN_INACTIVE flag set, then upon showing the tool window again, just the main update function is called with GWY_TOOL_CHANGED_SELECTION set (if the selection has changed meanwhile). Similarly, gwy_tool_queue_update() invokes the main update() function.

gwy_tool_class_set_default_size()

void
gwy_tool_class_set_default_size (GwyToolClass *tool_class,
                                 gint width,
                                 gint height);

Sets the default size of an interactive tool's window.

The information is static class properties and have to be set before any object is instantiated. It is expected they are set when a module registers the tool.

As users resize the tool windows, the size is remembered in settings. So this function generally just gives some information whether the window should be tall, wide or something similar when first shown.

gwy_tool_class_set_format_styles()

void
gwy_tool_class_set_format_styles (GwyToolClass *tool_class,
                                  GwyUnitFormatStyle xystyle,
                                  GwyUnitFormatStyle zstyle);

Sets the style of value formats an interactive tool should maintain.

The styles are static class properties and have to be set before any object is instantiated. It is expected they are set when a module registers the tool.

Either style can be set to GWY_UNIT_FORMAT_NONE to disable maintaining the corresponding format automatically. This is also the default behaviour. If a format is not maintained, then the format requesting methods return NULL.

gwy_tool_class_set_data_kinds()

void
gwy_tool_class_set_data_kinds (GwyToolClass *tool_class,
                               const GwyDataKind *data_kinds,
                               guint nkinds);

Defines the kinds of data a tool implementation accepts.

The base class does a reasonable job at guessing suitable data kinds based on the flags passed to gwy_tool_class_set_basics(). For example, GWY_TOOL_NEEDS_MASK implies the tool cannot be active on data kinds that do not support masks, such as scattered (XYZ) data.

Occasionally, the tool can do something useful against the conventions or just disable a small part of functionality for some data kinds, or perhaps reject a data kind that would typically look acceptable. Use then this function to specify exactly the accepted data kinds.

gwy_tool_class_get_name()

const gchar *
gwy_tool_class_get_name (GwyToolClass *tool_class);

Gets the name for a class of interactive tools.

This is the name passed to gwy_register_tool().

gwy_tool_class_get_title()

const gchar *
gwy_tool_class_get_title (GwyToolClass *tool_class);

Gets the window title for a class of interactive tools.

The tool sets the dialog title itself, so this function is rarely needed.

gwy_tool_class_get_icon_name()

const gchar *
gwy_tool_class_get_icon_name (GwyToolClass *tool_class);

Gets the icon name for a class of interactive tools.

gwy_tool_class_get_tooltip()

const gchar *
gwy_tool_class_get_tooltip (GwyToolClass *tool_class);

Gets the tooltip for a class of interactive tools.

gwy_tool_class_get_flags()

GwyToolFlags
gwy_tool_class_get_flags (GwyToolClass *tool_class);

Gets the tool flags for a class of interactive tools.

gwy_tool_switch_data()

void
gwy_tool_switch_data (GwyTool *tool,
                      GwyDataView *dataview);

Switches an interactive tool to a new data.

More precisely, the tool switches to a GwyDataView widget showing the new data, where it should set up an appropriate interactive layer. It is possible to switch to no-data; data_view is NULL in such case.

gwy_tool_provide_layer()

GwyVectorLayer *
gwy_tool_provide_layer (GwyTool *tool,
                        GType layer_type);

Provides a suitable layer to set on the current data view by an interactive tool.

The layer may be the very same layer that is already on the data view if the types match. Otherwise it is a new layer. In any case, the reference count is such that it can be passed to gwy_tool_set_layer() (or gwy_data_view_set_interactive_layer(), except that tool implementations should not do it directly).

The function also makes the returned layer editable, unsets focus and resets all properties of the specific layer type. This is the usually how the layer should be set up. Some tools may require additional layer setup, some may even want make the layer non-editable (for example if the tool only allows selecting fixed objects).

gwy_tool_set_layer()

void
gwy_tool_set_layer (GwyTool *tool,
                    GwyVectorLayer *layer,
                    const gchar *name);

Sets the layer an interactive tool uses for the current data view.

Tool implementations must use this function when switching to different data to set the interactive layer on the data view and determine the selection type. The only exception is when switching away from any data (to a NULL data view). They may also use it on other occasions to switch the layer.

Usually, the layer should come from gwy_tool_provide_layer(), but the tool can create it by other means. It should have the necessary properties already set.

Some tools use a single layer type. They just call gwy_tool_set_layer() during the data switch with this fixed type.

Some tools use multiple types. They call gwy_tool_set_layer() during the data switch with a layer of the currently selected type, and also when they want to switch the layer to a different one.

Rarely, a tool can want to adapt to the layer already present (if there is any present). The selection manager tool may be an example. It still must call gwy_tool_set_layer(), but it may do so with the layer already present there. If there is none, it must create one. Support for a layer not being present all all may be added in future, but currently a tool must create an interactive layer.

gwy_tool_show()

void
gwy_tool_show (GwyTool *tool);

Shows the window of an interactive tool.

Depending on the tool class, this may sent a single joint notifications about data and selection changes that occurred while the dialog was hidden to the tool.

If the tool dialog widget does not exist yet, it will be first created and the class dialog setup function called. It may be useful to call the function for already visible tool dialogs because it raises the window with gtk_window_present().

gwy_tool_hide()

void
gwy_tool_hide (GwyTool *tool);

Hides the window of an interactive tool.

Depending on the tool class, this may stop notifications about data and selection changes being sent to the tool (a single notification will be sent when/if it is shown again).

gwy_tool_is_visible()

gboolean
gwy_tool_is_visible (GwyTool *tool);

Reports whether an interactive tool is visible.

gwy_tool_get_tool_data()

gpointer
gwy_tool_get_tool_data (GwyTool *tool);

Gets the implementation data of an interactive tool.

The tool data is specified in gwy_tool_class_set_basics() and is automatically allocated (zero filled) before setup() and freed after shutdown(). Only the tool implementation knows what is inside. It can modify the contents arbitrarily, but may not reallocate or free it.

If the tool data size was given as zero, the function returns NULL.

gwy_tool_get_params()

GwyParams *
gwy_tool_get_params (GwyTool *tool);

Gets the parameter set of an interactive tool.

Tool implementations can behave as if they own the parameter set and alter it freely. Non-tool code should rarely need this function and must not modify the parameters.

If the tool implementation did not register any GwyParamDef using gwy_tool_class_set_basics().

gwy_tool_get_window()

GtkWindow *
gwy_tool_get_window (GwyTool *tool);

Gets the window with the user interface of an interactive tool.

The window alway exists unless the tool is in destruction, but it may be hidden. It is always GwyDialog or its subclass.

Tool implementations can behave as if they own the window and alter it freely. Non-tool code should rarely need this function and restrict itself to gwy_tool_show() and gwy_tool_hide(). In particular, the window may only be destroyed by destroying tool itself.

gwy_tool_get_selection()

GwySelection *
gwy_tool_get_selection (GwyTool *tool);

Gets the selection of an interactive tool.

The selection may or may not exist. If the tool is active on a data view, a selection generally exists. It does not exist when the tool is has no data view to work on (including in destruction) and during data switching.

Tool implementations can behave as if they own the selection and alter it freely. Non-tool code should rarely need this function.

gwy_tool_get_data_view()

GwyDataView *
gwy_tool_get_data_view (GwyTool *tool);

Gets the data view an interactive tool is active on.

The data view may or may not exist. If the tool is active on a data view, it exists. It does not exist when the tool is has no data view and during it destruction, but during switching it is already set to the new data view.

Tool implementations do not own the data view. They set up interactive layers on it, but other code can chage the data independently.

gwy_tool_get_layer()

GwyVectorLayer *
gwy_tool_get_layer (GwyTool *tool);

Gets the data view layer an interactive tool is active on.

The layer may or may not exist. If the tool is active on a data view, it exists. It does not exist when the tool is has no data view and during it destruction. During switching it is already set to the new data view. However, unless your tool adopts to the layer already present, do not use this function during switching. Use gwy_tool_provide_layer() instead, which ensures the requested layer is present.

gwy_tool_get_data_kind()

GwyDataKind
gwy_tool_get_data_kind (GwyTool *tool);

Gets the data kind corresponding to the data view an interactive tool is active on.

Tool implementations can use this information during data switching, when it is already set to the new data kind. The data kind does not change outside data switching. The data kind can be GWY_FILE_NONE if the tool is not active on any data view, including in destruction.

gwy_tool_get_file()

GwyFile *
gwy_tool_get_file (GwyTool *tool);

Gets the file corresponding to the data view an interactive tool is active on.

Tool implementations can use this information during data switching, when it is already set to the new file. The file does not change outside data switching. The file can be NULL if the tool is not active on any data view, including in destruction.

gwy_tool_get_data_id()

gint
gwy_tool_get_data_id (GwyTool *tool);

Gets the data id corresponding to the data view an interactive tool is active on.

Tool implementations can use this information during data switching, when it is already set to the new id. The id does not change outside data switching. The id can be invalid (negative) if the tool is not active on any data view, including in destruction.

gwy_tool_get_format_xy()

GwyValueFormat *
gwy_tool_get_format_xy (GwyTool *tool);

Gets the lateral coordinate format an interactive tool automatically maintains.

The specific format style is selected with gwy_tool_class_set_format_styles(). The function returns NULL is the style is GWY_UNIT_FORMAT_NONE.

The returned format struct has the same life time as tool itself. Repeated calls return the same format, possibly with different contents.

gwy_tool_get_format_z()

GwyValueFormat *
gwy_tool_get_format_z (GwyTool *tool);

Gets the data value format an interactive tool automatically maintains.

The specific format style is selected with gwy_tool_class_set_format_styles(). The function returns NULL is the style is GWY_UNIT_FORMAT_NONE.

The returned format struct has the same life time as tool itself. Repeated calls return the same format, possibly with different contents.

gwy_tool_get_primary_data()

gpointer
gwy_tool_get_primary_data (GwyTool *tool);

Gets the primary data corresponding to the data view an interactive tool is active on.

The primary data object may not exist. If the tool can be active on non-image data, the primary data object may not be a GwyField even if it exists.

gwy_tool_get_field()

GwyField *
gwy_tool_get_field (GwyTool *tool);

Gets the data field corresponding to the data view an interactive tool is active on.

If the tool is active on something, this function returns non-NULL. For image data, the field is the same as returned by gwy_tool_get_primary_data(). If the tool can be active on non-image data, it returns just the preview field. Essentially, you get

1

gwy_data_view_get_field(gwy_tool_get_data_view(tool));

just with more careful handling of non-existence.

gwy_tool_get_mask()

GwyNield *
gwy_tool_get_mask (GwyTool *tool);

Gets the mask corresponding to the data view an interactive tool is active on.

A mask may not exist, even if the tool sets GWY_TOOL_NEEDS_MASK – it just indicates the data kind supports masking, not that a mask is set right now. If the tool can be active on non-image data, it may not be even possible to set a mask on some data kinds.

gwy_tool_queue_update()

void
gwy_tool_queue_update (GwyTool *tool,
                       GwyToolChangedFlags changed);

Pretends data pieces have been changed in an interactive tool.

See gwy_tool_class_set_updates() for a possible use of this function. Another valid use may be treating changes originating elsewhere as updates to data or selection.

Although the function is named queue, unless the tool window is hidden and the GWY_TOOL_HIDDEN_ACTIVE flag unset, the update is immediate. Note that the main update() function is always invoked, not selection_changed().

gwy_tool_set_can_update()

void
gwy_tool_set_can_update (GwyTool *tool,
                         gboolean can_update);

Sets the whether an interactive tool can run update/recalculation.

This is mostly a convenience wrapper for gtk_dialog_set_response_sensitive(), taking into account the instant updates setting as well as tool-specific conditions, such as that a selection is present (these are expressed by can_update ).

The can_update value influences the sensitivity of a Update button with response code GWY_RESPONSE_UPDATE. It does not determine it as long as updates are instant, it remains insensitive.

Upon switching to no-data, the function is automatically called with FALSE argument. However, it is never automatically called with TRUE argument because tools can have additional conditions for Update.

gwy_tool_set_can_apply()

void
gwy_tool_set_can_apply (GwyTool *tool,
                        gboolean can_apply);

Sets the whether an interactive tool can do the Apply action.

This is a convenience wrapper for gtk_dialog_set_response_sensitive().

Upon switching to no-data, the function is automatically called with FALSE argument. However, it is never automatically called with TRUE argument because tools can have additional conditions for Apply.

gwy_tool_is_switching_data()

gboolean
gwy_tool_is_switching_data (GwyTool *tool);

Reports whether an interactive tool is currently switching data.

gwy_tool_enable_deletion()

void
gwy_tool_enable_deletion (GwyTool *tool,
                          GtkTreeView *treeview);

Enables deletion of selection objects by presssing Delete in a tree view diplaying them.

This is a tool implementation helper. Tools can use when they create the GUI to automatically handle deletion of selection objects from a treeview.

gwy_tool_get_qualified_name()

const gchar *
gwy_tool_get_qualified_name (GwyTool *tool);

Provides the qualified name of an interactive tool.

This convenience function return the tool name prefixed with "tool::".

gwy_tool_class_from_name()

GwyToolClass *
gwy_tool_class_from_name (const gchar *name);

Provides the tool class of an interactive tool given its short name.

The name is the same as passed to gwy_register_tool().

gwy_tool_produce_graph_curves()

void
gwy_tool_produce_graph_curves (GwyTool *tool,
                               GwyGraphModel *gmodel,
                               gint target_graph_id,
                               gboolean separate);

Creates output graphs for an interactive tool implementation.

This helper function can create a new graph (duplicating the model), or even multiple graphs with separate being TRUE, or add curves to an existing target graph. It depends on a target graph parameter identified by target_graph_id . If target_graph_id is -1, new graph(s) are always created.

The operation is logged with the current data as the source in the previous case and as an unclear-source operation in the latter case (since the source log cannot be copied then).

New graphs are made visible and have GwyGraphModel:label-visible set to TRUE. The visibility of an existing target graph is unchanged.

If separate is TRUE, the target graph parameter is ignored.

enum GwyToolFlags

Flags specifying features and behaviours of interactive tools.

enum GwyToolChangedFlags

Type of change reported to interactive tool update function.

A tool implementation declares which updates it is interested in with gwy_tool_class_set_updates(). For tools that are not active when hidden, it is common that the update() function can be called with many flags set simultaneously when the tool is shown.

Unless the tool sets the GWY_TOOL_PRIMARY_IS_PRIMARY flag, changes of the preview image are reported as GWY_TOOL_CHANGED_PRIMARY for non-image data instead of GWY_TOOL_CHANGED_PICTURE. If the tool simply calls gwy_tool_get_field() and does something with the data field, this simplifies the logic.

enum GwyHoldSelectionFlags

GwyToolClassPrivate

typedef struct _GwyToolClassPrivate GwyToolClassPrivate;

struct GwyTool

struct GwyTool;

Object representing a set of parameter values.

The GwyTool struct contains no public fields.

struct GwyToolClass

struct GwyToolClass {
};

Class of parameter value sets.