Difference between revisions of "GtkAction migration"

From Inkscape Wiki
Jump to: navigation, search
(Added some notes)
Line 25: Line 25:
 
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.
 
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 ==
+
== Migrating widgets ==
=== Widgets ===
+
Use the following replacements for old GtkAction-based widgets:
 +
 
 
* ege-adjustment-action => SpinButtonToolItem
 
* ege-adjustment-action => SpinButtonToolItem
 +
* SPWidget => Nothing... just put your widget directly in the toolbar
  
 
=== Containers ===
 
=== Containers ===

Revision as of 19:23, 29 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.

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)