Difference between revisions of "GtkAction migration"

Revision as of 21:49, 27 March 2018

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.

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.

Already migrated

Widgets

ege-adjustment-action => SpinButtonToolItem

Containers

ConnectorToolbar
DropperToolbar

Known bugs

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

@@ Line 1: / Line 1: @@
+== 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.
+== 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 [https://developer.gnome.org/glibmm/2.40/classGio_1_1SimpleAction.html] 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.
 == Already migrated ==
 === Widgets ===