Gnome Developers' Information
Prev | Chapter 9. Talking to the user: GnomeDialog, GnomeMessageBox, GnomeAppBar, and utility functions. | Next

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

`GtkWidget *gnome_app_message` ( GnomeApp *app , const gchar *message );

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

`GtkWidget *gnome_app_flash` ( GnomeApp *app , const gchar *flash );

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

`GtkWidget *gnome_app_error` ( GnomeApp *app , const gchar *error );

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.

`GtkWidget *gnome_app_warning` ( GnomeApp *app , const gchar *warning );

Just a warning; not as important as an error, but not as trivial as a flash.

`GtkWidget *gnome_app_question` ( GnomeApp *app , const gchar *question , GnomeReplyCallback callback , gpointer data );

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.

`GtkWidget *gnome_app_question_modal` ( GnomeApp *app , const gchar *question , GnomeReplyCallback callback , gpointer data );

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

`GtkWidget *gnome_app_ok_cancel` ( GnomeApp *app , const gchar *message , GnomeReplyCallback callback , gpointer data );

`GtkWidget *gnome_app_ok_cancel_modal` ( GnomeApp *app , const gchar *message , GnomeReplyCallback callback , gpointer data );

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.

Prev | Home | Next
The abstract message utility functions | Up | Using GnomeDialog directly