Statusbar API - Revision history

Frigory: Frigory moved page StatusbarAPI to Statusbar API: Separated words

2016-07-13T05:49:22Z

Frigory moved page StatusbarAPI to Statusbar API: Separated words

← Older revision

Revision as of 05:49, 13 July 2016

Conversion script: link fix

2006-01-22T02:33:47Z

link fix

← Older revision		Revision as of 02:33, 22 January 2006
Line 30:		Line 30:

	SPDesktop *dt;		SPDesktop *dt;
	sp_view_set_statusf_flash (SP_VIEW(desktop), format, ...);		sp_view_set_statusf_flash ([[SP_VIEW]](desktop), format, ...);

	SPEventContext *ec;		[[SPEventContext]] *ec;
	sp_view_set_statusf_flash (SP_VIEW(ec->desktop), format, ...);		sp_view_set_statusf_flash ([[SP_VIEW]](ec->desktop), format, ...);

	SPSelection *sel;		SPSelection *sel;
	sp_view_set_statusf_flash (SP_VIEW(sel->desktop), format, ...);		sp_view_set_statusf_flash ([[SP_VIEW]](sel->desktop), format, ...);

	SPNodePath *nodepath;		[[SPNodePath]] *nodepath;
	sp_view_set_statusf_flash (SP_VIEW(nodepath->desktop), format, ...);		sp_view_set_statusf_flash ([[SP_VIEW]](nodepath->desktop), format, ...);

	=== Other considerations ===		=== Other considerations ===
Line 49:		Line 49:
	=== New Statusbar API ===		=== New Statusbar API ===

	The Statusbar interface has been replaced by Inkscape::MessageStack. MessageStacks have three basic operations:		The Statusbar interface has been replaced by Inkscape::[[MessageStack]]. [[MessageStacks]] have three basic operations:

	* push - places a message atop the stack and returns a message id		* push - places a message atop the stack and returns a message id
Line 57:		Line 57:
	You can get the stack for a particular view via SPView::messageStack().		You can get the stack for a particular view via SPView::messageStack().

	Inkscape::MessageContext is provided to make the first two operations simpler to use. A MessageContext stores a message ID internally, and provides two operations:		Inkscape::[[MessageContext]] is provided to make the first two operations simpler to use. A [[MessageContext]] stores a message ID internally, and provides two operations:

	* set - removes that context's existing message, if any, and pushes a new one		* set - removes that context's existing message, if any, and pushes a new one
	* clear - removes the existing message if there is one		* clear - removes the existing message if there is one

	Typically, separate subsystem/classes/whatever will each maintain their own MessageContexts so they can easily manipulate the MessageStack they share without stepping on each other's toes.		Typically, separate subsystem/classes/whatever will each maintain their own [[MessageContexts]] so they can easily manipulate the [[MessageStack]] they share without stepping on each other's toes.

195.177.212.225: Removed spam

2004-09-24T08:00:14Z

Removed spam

New page

=== When to use the statusbar ===

There are new functions for statusbar display. Please use them where appropriate to make statusbar helpful and informative. The general rules are:

* Whenever there's a change in the status of the program (such as selection change, tool change, etc.) this must be reflected in the statusbar.
* Whenever a command cannot perform its operation, it must state the reason in the statusbar.
* Operations that finish normally do not need to display anything if the result of the operation is easy to see on the canvas. For example, boolean union of shapes does not need to display anything when finished successfully. On the other hand, when a document was successfully saved, it's important enough for the user to know that, so the save command briefly flashes "Document saved." to the statusbar.

=== Statusbar functions ===

void sp_view_set_statusf (SPView *view, const gchar *format, ...);

Sets statusbar message permanently. The format string and the rest of arguments are as in printf(). Not to be used normally, because the message never disappears unless replaced by another message. In the majority of situations, one of the _flash or _error functions should be used instead.

void sp_view_clear_status (SPView *view);

Clears statusbar message permanently. Not to be used normally. In the majority of situations, one of the _flash or _error functions should be used instead.

void sp_view_set_statusf_flash (SPView *view, const gchar *format, ...);

Displays message temporarily for 1 second; when the message disappears, the one that was in the statusbar before it is restored. Use this function for short helpful hints or explanations of non-trivial actions. Examples: "No-break space" when you press ctrl-space in text object; "Closing path" when hitting the anchor in freehand; "Selection cancelled" when pressing Esc cancelled rubberband selection.

void sp_view_set_statusf_error (SPView *view, const gchar *format, ...);

Displays message temporarily for 5 seconds; when the message disappears, the one that was in the statusbar before it is restored. Use this function for most non-fatal error messages (unless they are so important as to warrant a modal messagebox). Examples: "To join, you must have two endnodes selected" when you try to join nodes that are not exactly two endpoints; "To subtract, you must have two objects selected" for the boolean difference operation.

=== Figuring out SPView ===

The only potential difficulty with these functions is figuring out the SPView. How you do this depends on what you have at hand when you call one of these functions. Examples:

SPDesktop *dt;
sp_view_set_statusf_flash (SP_VIEW(desktop), format, ...);

SPEventContext *ec;
sp_view_set_statusf_flash (SP_VIEW(ec->desktop), format, ...);

SPSelection *sel;
sp_view_set_statusf_flash (SP_VIEW(sel->desktop), format, ...);

SPNodePath *nodepath;
sp_view_set_statusf_flash (SP_VIEW(nodepath->desktop), format, ...);

=== Other considerations ===

Please don't forget to enclose all text strings shown to the user into <tt>_("...")</tt> so they can be translated. For this to work, you need to <tt>#include "helper/sp-intl.h"</tt>.

Normally statusbar messages start with a capital letter and end with a full stop. An exception is messages that are "live", i.e. track closely user actions, such as "Move by x, y" when you drag an object; such messages start with a cap but have no full stop at the end.

=== New Statusbar API ===

The Statusbar interface has been replaced by Inkscape::MessageStack. MessageStacks have three basic operations:

* *push* - places a message atop the stack and returns a message id
* *cancel* - removes the message with a given id from the stack
* *flash* - briefly shows a message and removes it automatically after a brief delay

You can get the stack for a particular view via SPView::messageStack().

Inkscape::MessageContext is provided to make the first two operations simpler to use. A MessageContext stores a message ID internally, and provides two operations:

* *set* - removes that context's existing message, if any, and pushes a new one
* *clear* - removes the existing message if there is one

Typically, separate subsystem/classes/whatever will each maintain their own MessageContexts so they can easily manipulate the MessageStack they share without stepping on each other's toes.

222.65.6.173 at 04:53, 14 September 2004

2004-09-14T04:53:35Z

← Older revision		Revision as of 04:53, 14 September 2004
Line 63:		Line 63:

	Typically, separate subsystem/classes/whatever will each maintain their own MessageContexts so they can easily manipulate the MessageStack they share without stepping on each other's toes.		Typically, separate subsystem/classes/whatever will each maintain their own MessageContexts so they can easily manipulate the MessageStack they share without stepping on each other's toes.
	~~[http://vod-solutions.com Your Ultimate video on demand solutions]~~

222.65.6.173 at 04:53, 14 September 2004

2004-09-14T04:53:30Z

← Older revision		Revision as of 04:53, 14 September 2004
Line 63:		Line 63:

	Typically, separate subsystem/classes/whatever will each maintain their own MessageContexts so they can easily manipulate the MessageStack they share without stepping on each other's toes.		Typically, separate subsystem/classes/whatever will each maintain their own MessageContexts so they can easily manipulate the MessageStack they share without stepping on each other's toes.
			[http://vod-solutions.com Your Ultimate video on demand solutions]

222.65.6.173 at 04:51, 14 September 2004

2004-09-14T04:51:19Z

← Older revision		Revision as of 04:51, 14 September 2004
Line 63:		Line 63:

	Typically, separate subsystem/classes/whatever will each maintain their own MessageContexts so they can easily manipulate the MessageStack they share without stepping on each other's toes.		Typically, separate subsystem/classes/whatever will each maintain their own MessageContexts so they can easily manipulate the MessageStack they share without stepping on each other's toes.
	~~[http://vod-solutions.com Your Ultimate video on demand solutions]~~

222.65.6.173 at 04:51, 14 September 2004

2004-09-14T04:51:13Z

New page

Buliabyak: *

2004-01-02T19:25:22Z

New page