[Usability] notification - design proposal

[Sean Middleditch <elanthis awesomeplay com>]

Hello all,

 On the GUI application I'm working on now (mostly for
research/experimentation) I was thinking about adding notification
features utilizing the notification-area tray.  That thing is fairly
heavily abused but, as has been pointed out, there really isn't any
documentation or established models to follow in regards to its usage. 
My attempt here is to propose what I plan on implementing in my app and
gather any feedback on that.  When implemented in my app (which is quite
simple, i might note) it could provide a mini-testground to see if the
model does indeed work well and, if so, perhaps we can finally get
something added to the HIG or elsewhere to make this standard
procedure.  I'd also like to propose some basic API layouts, since a
solid single API is pretty much the only way to make sure all
applications get it implemented the same way.

 The model I'm basing this off of is used already in Apple's Safari for
error messages.  Basically, errors/problems are reported in popups
dialogs, similar to what most apps use now.  However, these popups do
not appear unless the document window they relate to is already
focused.  I.e., if Document A (http://www.gnome.org in Epiphany, say)
has an error (DNS lookup) but currently Document B is focused (that's
what I'm working on) the popups will not appear.  As soon as you focus
Document A, however, they will appear.

 At the same time the user is alerted that there is something wrong.  In
OS X, this is done over the dock.  (Which I don't like from a
design/usability perspective, btw - see my advogato diary for an almost
indepth writeup on why)  In GNOME, this would be done most likely using
the window list and/or Metacity, by coloring the window orange or
whatnot.  (Is there not already facilities for doing this?  Is there a
reason the window list doesn't?  Just not implemented yet?)  I'd also
like to use the notification-area.  

 For the notification area, an icon representing the app would appear. 
Clicking this icon would focus the document window (and, thus, cause the
popup error messages to appear) and remove the notification icon.  Note
that since the icon only appears if the popups are being suppressed, the
icon will never appear if the document window is focused when the error
occurs.  Which is good, becaue the notification icon would be useless in
that case.

 For the API/wrapper I'd like to write for my app (in Python), and what
I would like to see be made a standard part of whichever library is
appropriate (egg at first, probably), a function would be present to
register a dialog into this system.  It will be assumed this dialog is
now already visible/shown.

 The functions would check if the parent window is focused.  If not, it
would attach an event callback to the window, and add the notification
area icon (if one is not already present, in the event of multiple
errors) and add the dialog to a list of pending error dialogs.  The icon
added would when clicked do nothing other than focus the relevant
document window and remove itself.  When the document window is focused
(and the event callback triggered) all the pending error dialogs for
that window would be shown.

 Additionally, the API would have a function to "recall" an error. 
Given the handle of a dialog window, the function would check to see if
the dialog is already shown; if it is, it's destroyed.  If the dialog is
pending, its removed from the pending list.  If the pending list is now
empty, the notification icon is removed.  This allows temporary errors
to auto resolve.  For example, if Evolution were auto-checking mail once
every 10 minutes, and the check fails once (server rebooting after a
kernel update, say), the error dialogs would be added.  I might be
working in a terminal window so I wouldn't get interrupted by popups
stilling my keyboard focus.  If I don't bother to check Evolution until
another 10 minutes pass, when Evolution re-checks the server and
connects successfully, then I'll never be bothered by the error dialogs
at all.

 Note that this API proposal is based on the average simple needs of
most error dialogs.  There may be specific situations where the below
won't work as desired.  I'd like to identify any that we can, and make
any needed API changes to retain the simplicity and ease of use while
allowing more complex situations.  Honestly, tho, I can't think of a
situation off hand that the below doesn't cover.  Unless we want to add
priorities or alert types (i.e., just an icon, or also a non-intrusive
mini-popup?)  A lot of that can be hidden behind the below API, and
things like priorites can be done with API additions without even the
need to deprecate what we already have (since they would just use
defaults).

/* show the dialog if its parent is focused; otherwise, show the
   alert notification icon. */
void gtk_alert_add (GtkDialog* dialog);

/* hide the dialog if shown, or remove it from the pending queue
   if pending.  also remove the notification icon if present. */
void gtk_alert_remove (GtkDialog* dialog);

/* check if a dialog is in the pending alert list.  return 
   true if it is, false if it isn't. */
gbool gtk_alert_is_pending (GtkDialog* dialog);

/* check if any alerts are pending for the given window.  returns
   the number of pending alerts.  0 will be returned if there are
   none. */
gint gtk_alert_pending_count (GtkWindow* window);

/* display the notification alert icon.  icon will focus the
   specified window when clicked and remove the icon.  return
   error if the notification area is not present. */
gint gtk_alert_show_icon (GtkWindow* window);

/* remove the notification icon if shown. */
void gtk_alert_hide_icon (void);
-- 
Sean Middleditch <elanthis awesomeplay com>
AwesomePlay Productions, Inc.