GtkAction migration - Revision history

Tavmjong: /* Best Practices */

2021-10-06T11:33:48Z

Best Practices

← Older revision		Revision as of 11:33, 6 October 2021
Line 51:		Line 51:
	** InkErrorHandle (Pops up Error Box) (Derived from silly Inkscape::ErrorReporter class.)		** InkErrorHandle (Pops up Error Box) (Derived from silly Inkscape::ErrorReporter class.)
	** Note, a selection does have a link to desktop (which can be nullptr).		** Note, a selection does have a link to desktop (which can be nullptr).
	* Many actions work on a selection. A standard way to find the selection should be used. ~~(Radical idea, a selection could have an action map.)~~ Selections are tied to windows with a special selection tied to the document in command line mode.		* Many actions work on a selection. A standard way to find the selection should be used. Selections are tied to windows with a special selection tied to the document in command line mode.
	** get_document_and_selection(app, &document, &selection);		** get_document_and_selection(app, &document, &selection);
	** app->get_active_selection();		** app->get_active_selection();
	** At the moment we rely on INKSCAPE.action_context_for_document() to create a selection for a document in command-line mode. (INKSCAPE should disappear in the future.)		** At the moment we rely on INKSCAPE.action_context_for_document() to create a selection for a document in command-line mode. (INKSCAPE should disappear in the future.)--
	* When a Verb is converted to an action, remove any related code from "verb.cpp". Comment out the verb in "verbs.h" (so we can track progress in converting).		* When a Verb is converted to an action, remove any related code from "verb.cpp". Comment out the verb in "verbs.h" (so we can track progress in converting).
	* DocumentUndo uses verbs to provide an icon next to the operation in the History dialog. For the moment, one can change any removed verbs to "nullptr". In the future, we may allow one to directly specify an icon.		* DocumentUndo uses verbs to provide an icon next to the operation in the History dialog. For the moment, one can change any removed verbs to "nullptr". In the future, we may allow one to directly specify an icon.
			==== Selection-based actions ====
			Selection-based actions need to deal with two different ways selections are integrated into our code:
			* In command-line mode, a selection is linked to the document.
			* In GUI mode, a selection is linked to the window (via SPDesktop).[1]
			The current method for dealing with selection-based actions is to make them "application" level which depends on the application (InkscapeApplication) tracking which selection is active. This is a bit awkward, particularly due to the complicated interactions between SPDesktop, SPDesktopWindow, SPDocument, InkscapeApplication, etc. And it breaks down if a "stateful" action is needed as in the case of "arc type" in the Arc toolbar since all uses of that action would share the same state.
			''What can be done about this?''
			* We can keep selection-based actions tied to the application, introducing special "window" actions where we need to track state. This means some code duplication.
			* We can tie selection-based actions to selections. These seems that natural thing to do but would require having one special instance of Inkscape::Selection owned by the app (and not the document - which is the current case) so that actions from the command line work. (We need valid actions at the point of parsing the command line which may be before a document is opened.) This would be more feasible after we get rid of Inkscape::ActionContext.
			Note that Gio::Application contains one action_group, other groups cannot be added so we would need code anywhere actions are used to find the correct selection and trigger actions in the linked ActionGroup.
			[1] Different windows showing the same document can have different selections.

	== Shortcuts ==		== Shortcuts ==

Tavmjong: /* Best Practices */

2021-10-06T07:13:23Z

Best Practices

← Older revision		Revision as of 07:13, 6 October 2021
Line 44:		Line 44:
	*** Zoom level		*** Zoom level
	** Document actions:		** Document actions:
	*** Preferences stored inside an Inkscape SVG file, e.g. snapping.		*** Preferences stored inside an Inkscape SVG file, e.g. snapping (snapping preferences were removed from the document in Sept 2021 so are now Window level actions).
	* Actions should not rely on Window (desktop) unless absolutely necessary (e.g. scale by window pixels). This will allow a future GUI free Inkscape version.		* Actions should not rely on Window (desktop) unless absolutely necessary (e.g. scale by window pixels). This will allow a future GUI free Inkscape version.
	* If actions need to relay information to the user, use a standard (to be decided) mechanism to isolate dependency on desktop.		* If actions need to relay information to the user, use a standard (to be decided) mechanism to isolate dependency on desktop.

Tavmjong: /* Verb to Action Migration */

2020-11-02T07:33:18Z

Verb to Action Migration

← Older revision		Revision as of 07:33, 2 November 2020
Line 37:		Line 37:
	=== Best Practices ===		=== Best Practices ===

	* Tie an action to the appropriate map: Application, Window, or Document. (We may add tool dependent maps in the future.) It is not always obvious which map an action should be tied to:		* Tie an action to the appropriate map: Application (app), Window (win), or Document (doc). (We may add tool dependent maps in the future.) It is not always obvious which map an action should be tied to:
	** Application:		** Application:
	*** Global actions:		*** Global actions:

Tavmjong: /* Migrating widgets */

2020-11-02T07:30:56Z

Migrating widgets

← Older revision		Revision as of 07:30, 2 November 2020
Line 57:		Line 57:
	* When a Verb is converted to an action, remove any related code from "verb.cpp". Comment out the verb in "verbs.h" (so we can track progress in converting).		* When a Verb is converted to an action, remove any related code from "verb.cpp". Comment out the verb in "verbs.h" (so we can track progress in converting).
	* DocumentUndo uses verbs to provide an icon next to the operation in the History dialog. For the moment, one can change any removed verbs to "nullptr". In the future, we may allow one to directly specify an icon.		* DocumentUndo uses verbs to provide an icon next to the operation in the History dialog. For the moment, one can change any removed verbs to "nullptr". In the future, we may allow one to directly specify an icon.

			== Shortcuts ==

			Shortcuts for actions can be added in "share/keys/inkscape.xml" or in the Inkscape Preferences dialog. Currently, only actions described in the "Extra Action Data" appear in the dialog. Note that shortcuts use the "Detailed Action Name" which consists of "map name" + "." + "action name" + "(" + argument + ")". Not all actions take arguments.

			Keyboard shortcuts are a bit complicated in Inkscape. GTK normally passes key events to the GTK shortcut code first. We override this and pass it to our own hard-coded event handlers first (otherwise we wouldn't even be able to type in the text tool since we use single letter shortcuts). Each tool has its own handler code and keys can be tied to different actions for different tools. If the hard-coded event handlers don't handle the key event, it gets passed to GTK's shortcut handler and finally our Verb shortcut handler code. The shortcuts handled by GTK (via Gio::Actions) or by our Verb code are global to all tools (and only these can be modified in the Preferences dialog). It is possible to create different "ActionGroups" for each tool and then install/remove the group as the selected tool changes. This would allow one to use preferences to assign different tool dependent actions to different shortcuts. But that will require quite a bit of refactoring and won't solve all problems (actions are triggered once per key-press/key-release so any thing that depends on different actions for key-press vs key-release will still need to be hard coded).

	== Migrating widgets ==		== Migrating widgets ==

Tavmjong: /* Best Practices */

2020-10-30T17:20:42Z

Best Practices

← Older revision		Revision as of 17:20, 30 October 2020
Line 37:		Line 37:
	=== Best Practices ===		=== Best Practices ===

	* Tie an action to the appropriate map: Application, Window, or Document. (We may add tool dependent maps in the future.)		* Tie an action to the appropriate map: Application, Window, or Document. (We may add tool dependent maps in the future.) It is not always obvious which map an action should be tied to:
	* Actions should not rely on Window (desktop) unless absolutely necessary (e.g. scale by window pixels).		** Application:
			*** Global actions:
			*** Actions that operate on selections. There is always a "current selection" that is active. Note: a single document may have multiple independent selections, one for each window. There will also be an active selection in command line mode.
			** Window actions:
			*** Zoom level
			** Document actions:
			*** Preferences stored inside an Inkscape SVG file, e.g. snapping.
			* Actions should not rely on Window (desktop) unless absolutely necessary (e.g. scale by window pixels). This will allow a future GUI free Inkscape version.
	* If actions need to relay information to the user, use a standard (to be decided) mechanism to isolate dependency on desktop.		* If actions need to relay information to the user, use a standard (to be decided) mechanism to isolate dependency on desktop.
	** boolop_display_error_message();		** boolop_display_error_message();

Tavmjong: /* Verb to Action Migration */

2020-10-30T09:42:44Z

Verb to Action Migration

← Older revision		Revision as of 09:42, 30 October 2020
Line 32:		Line 32:

	Inkscape has a custom built ''Verb'' class that duplicates much of the functionality of Actions. This class has some problems, the biggest is that most ''Verb''s require a desktop. This means that they cannot be used in a headless Inkscape. We are in the process of converting Verbs to Actions. This is a long term process as there are many verbs.		Inkscape has a custom built ''Verb'' class that duplicates much of the functionality of Actions. This class has some problems, the biggest is that most ''Verb''s require a desktop. This means that they cannot be used in a headless Inkscape. We are in the process of converting Verbs to Actions. This is a long term process as there are many verbs.

			Actions are defined in the "src/actions" directory. For new actions, please follow the format of existing files. If possible, define all functionality in the actions-xxx.cpp file.

	=== Best Practices ===		=== Best Practices ===

	* Tie an action to the appropriate map: Application, Window, or Document.		* Tie an action to the appropriate map: Application, Window, or Document. (We may add tool dependent maps in the future.)
	* Actions should not rely on Window (desktop) unless absolutely necessary (e.g. scale by window pixels).		* Actions should not rely on Window (desktop) unless absolutely necessary (e.g. scale by window pixels).
	* If actions need to relay information to the user, use a standard (to be decided) mechanism to isolate dependency on desktop.		* If actions need to relay information to the user, use a standard (to be decided) mechanism to isolate dependency on desktop.
Line 45:		Line 47:
	** get_document_and_selection(app, &document, &selection);		** get_document_and_selection(app, &document, &selection);
	** app->get_active_selection();		** app->get_active_selection();
	** At the moment we rely on INKSCAPE.action_context_for_document() to create a selection for a document in command-line mode.		** At the moment we rely on INKSCAPE.action_context_for_document() to create a selection for a document in command-line mode. (INKSCAPE should disappear in the future.)
			* When a Verb is converted to an action, remove any related code from "verb.cpp". Comment out the verb in "verbs.h" (so we can track progress in converting).
			* DocumentUndo uses verbs to provide an icon next to the operation in the History dialog. For the moment, one can change any removed verbs to "nullptr". In the future, we may allow one to directly specify an icon.

	== Migrating widgets ==		== Migrating widgets ==

Tavmjong: /* Migrating widgets */

2020-05-24T05:41:36Z

Migrating widgets

← Older revision		Revision as of 05:41, 24 May 2020
Line 50:		Line 50:
	Use the following replacements for old GtkAction-based widgets:		Use the following replacements for old GtkAction-based widgets:

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

	=== Containers ===		=== Containers ===

Tavmjong: /* Background: Action implementations */

2020-02-26T14:54:48Z

Background: Action implementations

← Older revision		Revision as of 14:54, 26 February 2020
Line 26:		Line 26:

	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).		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).

			Actions are defined in src/actions

			== Verb to Action Migration ==

			Inkscape has a custom built ''Verb'' class that duplicates much of the functionality of Actions. This class has some problems, the biggest is that most ''Verb''s require a desktop. This means that they cannot be used in a headless Inkscape. We are in the process of converting Verbs to Actions. This is a long term process as there are many verbs.

			=== Best Practices ===

			* Tie an action to the appropriate map: Application, Window, or Document.
			* Actions should not rely on Window (desktop) unless absolutely necessary (e.g. scale by window pixels).
			* If actions need to relay information to the user, use a standard (to be decided) mechanism to isolate dependency on desktop.
			** boolop_display_error_message();
			** selection_display_message();
			** InkErrorHandle (Pops up Error Box) (Derived from silly Inkscape::ErrorReporter class.)
			** Note, a selection does have a link to desktop (which can be nullptr).
			* Many actions work on a selection. A standard way to find the selection should be used. (Radical idea, a selection could have an action map.) Selections are tied to windows with a special selection tied to the document in command line mode.
			** get_document_and_selection(app, &document, &selection);
			** app->get_active_selection();
			** At the moment we rely on INKSCAPE.action_context_for_document() to create a selection for a document in command-line mode.

	== Migrating widgets ==		== Migrating widgets ==

Tavmjong: /* GAction or Gio::Action */

2019-04-04T08:09:35Z

GAction or Gio::Action

← Older revision		Revision as of 08:09, 4 April 2019
Line 25:		Line 25:
	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 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.		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 ==		== Migrating widgets ==

Tavmjong: /* How is this different from GUI events? */

2019-04-03T07:57:36Z

How is this different from GUI events?

← Older revision		Revision as of 07:57, 3 April 2019
Line 16:		Line 16:
	* Less code to write: we only need one signal handler for the "activate" signal; not multiple handlers for each GUI event		* 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.		* 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 ==		== Background: Action implementations ==