<refentry id="gnomeui-gnome-app-util">
<refmeta>
<refentrytitle>gnome-app-util</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOMEUI Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>gnome-app-util</refname><refpurpose>Utility functions for manipulating GnomeApp container widgets.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gnome.h&gt;


<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-message">gnome_app_message</link>               (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *message);
void        <link linkend="gnome-app-flash">gnome_app_flash</link>                 (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *flash);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-error">gnome_app_error</link>                 (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *error);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-warning">gnome_app_warning</link>               (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *warning);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-question">gnome_app_question</link>              (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *question,
                                             <link linkend="GnomeReplyCallback">GnomeReplyCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-question-modal">gnome_app_question_modal</link>        (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *question,
                                             <link linkend="GnomeReplyCallback">GnomeReplyCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-ok-cancel">gnome_app_ok_cancel</link>             (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *message,
                                             <link linkend="GnomeReplyCallback">GnomeReplyCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-ok-cancel-modal">gnome_app_ok_cancel_modal</link>       (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *message,
                                             <link linkend="GnomeReplyCallback">GnomeReplyCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-request-string">gnome_app_request_string</link>        (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *prompt,
                                             <link linkend="GnomeStringCallback">GnomeStringCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-app-request-password">gnome_app_request_password</link>      (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *prompt,
                                             <link linkend="GnomeStringCallback">GnomeStringCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="gdouble">gdouble</link>     (<link linkend="GnomeAppProgressFunc">*GnomeAppProgressFunc</link>)         (<link linkend="gpointer">gpointer</link> data);
void        (<link linkend="GnomeAppProgressCancelFunc">*GnomeAppProgressCancelFunc</link>)   (<link linkend="gpointer">gpointer</link> data);
typedef     <link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link>;
<link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link> <link linkend="gnome-app-progress-timeout">gnome_app_progress_timeout</link>
                                            (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *description,
                                             <link linkend="guint32">guint32</link> interval,
                                             <link linkend="GnomeAppProgressFunc">GnomeAppProgressFunc</link> percentage_cb,
                                             <link linkend="GnomeAppProgressCancelFunc">GnomeAppProgressCancelFunc</link> cancel_cb,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link> <link linkend="gnome-app-progress-manual">gnome_app_progress_manual</link>
                                            (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *description,
                                             <link linkend="GnomeAppProgressCancelFunc">GnomeAppProgressCancelFunc</link> cancel_cb,
                                             <link linkend="gpointer">gpointer</link> data);
void        <link linkend="gnome-app-set-progress">gnome_app_set_progress</link>          (<link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link> key,
                                             <link linkend="gdouble">gdouble</link> percent);
void        <link linkend="gnome-app-progress-done">gnome_app_progress_done</link>         (<link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link> key);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="gnome-app-message">gnome_app_message ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_message               (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *message);</programlisting>
<para>
A simple message, in an OK dialog or the status bar.
Requires confirmation from the user before it goes away.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>message</parameter>&nbsp;:</entry>
<entry> Text of message to be displayed
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-flash">gnome_app_flash ()</title>
<programlisting>void        gnome_app_flash                 (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *flash);</programlisting>
<para>
Flash the message in the statusbar for a few moments; if no
statusbar, do nothing (?). For trivial little status messages,
e.g. "Auto saving..."</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>flash</parameter>&nbsp;:</entry>
<entry> Text of message to be flashed
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-error">gnome_app_error ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_error                 (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *error);</programlisting>
<para>
An important fatal error; if it appears in the statusbar, 
it might <link linkend="gdk-beep">gdk_beep</link>() and require acknowledgement.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> Text of error message to be displayed
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-warning">gnome_app_warning ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_warning               (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *warning);</programlisting>
<para>
A not-so-important error, but still marked better than a flash</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>warning</parameter>&nbsp;:</entry>
<entry> Text of warning message to be displayed
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-question">gnome_app_question ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_question              (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *question,
                                             <link linkend="GnomeReplyCallback">GnomeReplyCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Ask a yes or no question, and call the callback when it's answered.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>question</parameter>&nbsp;:</entry>
<entry> Text of question to be displayed
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-question-modal">gnome_app_question_modal ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_question_modal        (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *question,
                                             <link linkend="GnomeReplyCallback">GnomeReplyCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Ask a yes or no question, and call the callback when it's answered.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>question</parameter>&nbsp;:</entry>
<entry> Text of question to be displayed
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-ok-cancel">gnome_app_ok_cancel ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_ok_cancel             (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *message,
                                             <link linkend="GnomeReplyCallback">GnomeReplyCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>message</parameter>&nbsp;:</entry>
<entry> Text of message to be displayed
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-ok-cancel-modal">gnome_app_ok_cancel_modal ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_ok_cancel_modal       (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *message,
                                             <link linkend="GnomeReplyCallback">GnomeReplyCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>message</parameter>&nbsp;:</entry>
<entry> Text of message to be displayed
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-request-string">gnome_app_request_string ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_request_string        (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *prompt,
                                             <link linkend="GnomeStringCallback">GnomeStringCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>prompt</parameter>&nbsp;:</entry>
<entry> Text of prompt to be displayed
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-request-password">gnome_app_request_password ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_app_request_password      (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *prompt,
                                             <link linkend="GnomeStringCallback">GnomeStringCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry> Pointer to GNOME app object
</entry></row>
<row><entry align="right"><parameter>prompt</parameter>&nbsp;:</entry>
<entry> Text of prompt to be displayed
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
Pointer to dialog widget, or <literal>NULL</literal> if error or message in
status bar.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GnomeAppProgressFunc">GnomeAppProgressFunc ()</title>
<programlisting><link linkend="gdouble">gdouble</link>     (*GnomeAppProgressFunc)         (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GnomeAppProgressCancelFunc">GnomeAppProgressCancelFunc ()</title>
<programlisting>void        (*GnomeAppProgressCancelFunc)   (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GnomeAppProgressKey">GnomeAppProgressKey</title>
<programlisting>typedef gpointer GnomeAppProgressKey;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gnome-app-progress-timeout">gnome_app_progress_timeout ()</title>
<programlisting><link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link> gnome_app_progress_timeout
                                            (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *description,
                                             <link linkend="guint32">guint32</link> interval,
                                             <link linkend="GnomeAppProgressFunc">GnomeAppProgressFunc</link> percentage_cb,
                                             <link linkend="GnomeAppProgressCancelFunc">GnomeAppProgressCancelFunc</link> cancel_cb,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>description</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>interval</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>percentage_cb</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>cancel_cb</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-progress-manual">gnome_app_progress_manual ()</title>
<programlisting><link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link> gnome_app_progress_manual
                                            (<link linkend="GnomeApp">GnomeApp</link> *app,
                                             const <link linkend="gchar">gchar</link> *description,
                                             <link linkend="GnomeAppProgressCancelFunc">GnomeAppProgressCancelFunc</link> cancel_cb,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>app</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>description</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>cancel_cb</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-set-progress">gnome_app_set_progress ()</title>
<programlisting>void        gnome_app_set_progress          (<link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link> key,
                                             <link linkend="gdouble">gdouble</link> percent);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>percent</parameter>&nbsp;:</entry>
<entry>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-app-progress-done">gnome_app_progress_done ()</title>
<programlisting>void        gnome_app_progress_done         (<link linkend="GnomeAppProgressKey">GnomeAppProgressKey</link> key);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry>
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
GnomeApp
</para>
</refsect1>

</refentry>
