Statusbar API

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 _("...") so they can be translated. For this to work, you need to #include "helper/sp-intl.h".

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.