GtkAction migration

Background: what are actions?

An "action" is a thing that Inkscape can do. In its simplest form, it contains two things:

• The name of the action (e.g., "ObjectFlipHorizontally")
• A pointer to some code that performs the action (e.g., a few lines that flip the object horizontally)

In the Inkscape application, we can attach actions to widgets so that when the user interacts with that widget (e.g. clicks on the "Flip horizontally" button in the toolbar), the action is triggered.

How is this different from GUI events?

GUI elements (buttons etc) provide their own signals (e.g, "clicked") that are emitted in response to user interaction. We then need to connect a callback function to handle that specific GUI event. If we have multiple GUI elements (e.g., a menu item, toolbar button etc) that all do the same thing, we need to hook up the callback function to each of the GUI elements.

With actions, it's a little different: the action has an "activated" signal. We now only need to connect the callback function to that one signal. Each GUI element is now just attached to the action rather than directly to the code that we want to run.

The advantages of actions are as follows:

• Less code to write: we only need one signal handler for the "activate" signal; not multiple handlers for each GUI event
• Easier look-up: Each action is identified by a unique text ID, and so we can access it by name.
• It is trivial to allow actions (with or without arguments) to be called from the command line.
• There is a built in DBus interface.

Background: Action implementations

There are a few different implementations of actions:

GAction or Gio::Action

These are probably the simplest implementation, and the way we "should" be doing this. The Gio::Action class [1] really just defines a name for the action, along with possible states and parameters.

These actions need to be listed in an action-map, which is essentially a table that lists each action and the function that handles its "activate" signal. There is an action map associated with the application (Gtk::Application or Gio::Application) and an action map associated with windows (Gtk::ApplicationWindow). The latter is useful for window dependent functions like zoom level where two different "views" of the same document can have different zoom levels. Another action map can be "manually" attached to a document to handle document level actions (such as snapping preferences).

Migrating widgets

Use the following replacements for old GtkAction-based widgets:

• ege-adjustment-action => SpinButtonToolItem
• SPWidget => Nothing... just put your widget directly in the toolbar

Containers

• ConnectorToolbar
• DropperToolbar

Known bugs

• SpinButtonToolItem: Pressing enter or escape does nothing (it should drop focus to canvas)