Whole document tree
| Gnome Developers' Information | ||
|---|---|---|
| Prev | Chapter 9. Talking to the user: GnomeDialog, GnomeMessageBox, GnomeAppBar, and utility functions. | Next |
9.4. Utility functions if a GnomeApp is available
When these functions return a GtkWidget*, they are returning the created dialog, if any. If no dialog is created they return NULL. In general this is useless, but in special circumstances you might care. You should never modify the settings on the returned dialog, such as how it's destroyed, where it's positioned, etc.; you could confuse the library internals and/or override user preferences.
gnome_app_message() shows a simple message of moderate importance. It will come in a dialog with an OK button, or on the appbar; it will require the user to acknowledge it somehow before it goes away.
This is used for trivial messages that aren't very important; an example might be the little Netscape messages telling which URL is currently being fetched. If the user never sees these messages, it's not a problem; in fact, gnome_app_flash() is not guaranteed to show the user the message (for example, if dialogs are turned off and the GnomeApp has no appbar).
An important error, issued if an operation fails entirely or there's a major problem. This may do something obnoxious like beep, and will probably require user acknowledgement.
Just a warning; not as important as an error, but not as trivial as a flash.
Ask the yes or no question question, and call callback to indicate a response or if the user cancels (deleting the dialog or with control-G from the eventual minibuffer widget).
GnomeReplyCallback is a typedef:
typedef void (* GnomeReplyCallback)(gint reply, gpointer data);
The first argument received in the callback is a number
representing the user's reply. It will be either
GNOME_YES or GNOME_NO. The
callback also receives a data argument, the
same one you passed in to
gnome_app_question().
Keep in mind that the callback is not guaranteed to be called. If the user declines to answer the question --- say, by destroying the dialog via the window manager --- the callback is ignored. This is an area for API improvement; it probably makes sense to call the callback with reply GNOME_USER_CANCELLED or something like that. However, this feature is not implemented yet, so don't assume your callback is going to happen.
This function is just the same as gnome_app_question(), but it creates a modal dialog or appbar prompt, so the user will be unable to interact with other parts of the application until the dialog is dealt with (either the question is answered, or the user cancels by closing the dialog/control-G from the appbar). It's a weakness waiting to be fixed that the modal question handles cancels poorly. (see also comments in the intro on possibly using a GtkObject here.)
These two functions exactly parallel the gnome_app_question() functions, only they ask the user for OK/Cancel instead of Yes/No, and the callback receives GNOME_OK or GNOME_CANCEL.
FIXME rest of the gnome-app-util functions.