<refentry id="streamtuner-st-dialog-api">
<refmeta>
<refentrytitle>st-dialog</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>STREAMTUNER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>st-dialog</refname><refpurpose>functions for outputting messages and displaying simple dialogs.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



<link linkend="void">void</link>        <link linkend="st-notice">st_notice</link>                       (const <link linkend="char">char</link> *format,
                                             ...);
<link linkend="void">void</link>        <link linkend="st-info-dialog">st_info_dialog</link>                  (const <link linkend="char">char</link> *primary,
                                             const <link linkend="char">char</link> *format,
                                             ...);
<link linkend="void">void</link>        <link linkend="st-error-dialog">st_error_dialog</link>                 (const <link linkend="char">char</link> *primary,
                                             const <link linkend="char">char</link> *format,
                                             ...);
<link linkend="char">char</link>*       <link linkend="st-search-dialog">st_search_dialog</link>                (void);
<link linkend="gboolean">gboolean</link>    <link linkend="st-auth-dialog">st_auth_dialog</link>                  (const <link linkend="char">char</link> *default_name,
                                             const <link linkend="char">char</link> *default_password,
                                             <link linkend="char">char</link> **name,
                                             <link linkend="char">char</link> **password,
                                             const <link linkend="char">char</link> *primary,
                                             const <link linkend="char">char</link> *format,
                                             ...);
<link linkend="char">char</link>*       <link linkend="st-dialog-normalize">st_dialog_normalize</link>             (const <link linkend="char">char</link> *str);
<link linkend="void">void</link>        <link linkend="st-warning">st_warning</link>                      (const <link linkend="char">char</link> *format,
                                             ...);
<link linkend="void">void</link>        <link linkend="st-error">st_error</link>                        (const <link linkend="char">char</link> *format,
                                             ...);
<link linkend="int">int</link>         <link linkend="st-question">st_question</link>                     (const <link linkend="char">char</link> *format,
                                             ...);
<link linkend="char">char</link>*       <link linkend="st-prompt">st_prompt</link>                       (<link linkend="gboolean">gboolean</link> hidden,
                                             const <link linkend="char">char</link> *init,
                                             const <link linkend="char">char</link> *format,
                                             ...);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>
These functions provide support for outputting messages to the console
as well as displaying graphical message dialogs.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="st-notice"/>st_notice ()</title>
<indexterm><primary>st_notice</primary></indexterm><programlisting><link linkend="void">void</link>        st_notice                       (const <link linkend="char">char</link> *format,
                                             ...);</programlisting>
<para>
Outputs a formatted streamtuner notice to the standard error output.
</para>
<para>
If you need to output a notice regarding a specific handler, use
<link linkend="st-handler-notice"><function>st_handler_notice()</function></link> instead of this function.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> the parameters to insert into the format string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-info-dialog"/>st_info_dialog ()</title>
<indexterm><primary>st_info_dialog</primary></indexterm><programlisting><link linkend="void">void</link>        st_info_dialog                  (const <link linkend="char">char</link> *primary,
                                             const <link linkend="char">char</link> *format,
                                             ...);</programlisting>
<para>
Displays an informational dialog.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>primary</parameter>&nbsp;:</term>
<listitem><simpara> the primary text, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> the secondary text format, or <literal>NULL</literal>. See the <link linkend="printf"><function>printf()</function></link>
documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> the parameters to insert into the format string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-error-dialog"/>st_error_dialog ()</title>
<indexterm><primary>st_error_dialog</primary></indexterm><programlisting><link linkend="void">void</link>        st_error_dialog                 (const <link linkend="char">char</link> *primary,
                                             const <link linkend="char">char</link> *format,
                                             ...);</programlisting>
<para>
Displays an error dialog.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>primary</parameter>&nbsp;:</term>
<listitem><simpara> the primary text, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> the secondary text format, or <literal>NULL</literal>. See the <link linkend="printf"><function>printf()</function></link>
documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> the parameters to insert into the format string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-search-dialog"/>st_search_dialog ()</title>
<indexterm><primary>st_search_dialog</primary></indexterm><programlisting><link linkend="char">char</link>*       st_search_dialog                (void);</programlisting>
<para>
Prompts the user for a search string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a search string which should be freed after use, or
<literal>NULL</literal> if the user pressed the cancel button.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-auth-dialog"/>st_auth_dialog ()</title>
<indexterm><primary>st_auth_dialog</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    st_auth_dialog                  (const <link linkend="char">char</link> *default_name,
                                             const <link linkend="char">char</link> *default_password,
                                             <link linkend="char">char</link> **name,
                                             <link linkend="char">char</link> **password,
                                             const <link linkend="char">char</link> *primary,
                                             const <link linkend="char">char</link> *format,
                                             ...);</programlisting>
<para>
Prompts the user for a name and password. The name and password
entries will be initialized to <parameter>default_name</parameter> and <parameter>default_password</parameter>,
if provided.
</para>
<para>
The entered name and password will be stored in <parameter>name</parameter> and
<parameter>password</parameter>, and should be freed when no longer needed. If <parameter>name</parameter> is
<literal>NULL</literal>, the name entry will not be made sensitive.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>default_name</parameter>&nbsp;:</term>
<listitem><simpara> a default name, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>default_password</parameter>&nbsp;:</term>
<listitem><simpara> a default password, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> a location to return the entered name, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>password</parameter>&nbsp;:</term>
<listitem><simpara> a location to return the entered password.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>primary</parameter>&nbsp;:</term>
<listitem><simpara> the primary text, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> the secondary text format, or <literal>NULL</literal>. See the <link linkend="printf"><function>printf()</function></link>
documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> the parameters to insert into the format string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if the user pressed the "Authenticate" button,
<literal>FALSE</literal> otherwise. If <literal>FALSE</literal> is returned, <parameter>name</parameter> and <parameter>password</parameter> will
not be set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-dialog-normalize"/>st_dialog_normalize ()</title>
<indexterm><primary>st_dialog_normalize</primary></indexterm><programlisting><link linkend="char">char</link>*       st_dialog_normalize             (const <link linkend="char">char</link> *str);</programlisting>
<para>
Normalizes a string so that it can be used stand-alone as the
secondary string of a dialog.
</para>
<para>
Normalization will remove trailing newlines and convert the string
to a sentence.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> a string to normalize.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a normalized string, which should be freed after use.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-warning"/>st_warning ()</title>
<indexterm><primary>st_warning</primary></indexterm><programlisting><link linkend="void">void</link>        st_warning                      (const <link linkend="char">char</link> *format,
                                             ...);</programlisting>
<warning><para><literal>st_warning</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-error"/>st_error ()</title>
<indexterm><primary>st_error</primary></indexterm><programlisting><link linkend="void">void</link>        st_error                        (const <link linkend="char">char</link> *format,
                                             ...);</programlisting>
<warning><para><literal>st_error</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-question"/>st_question ()</title>
<indexterm><primary>st_question</primary></indexterm><programlisting><link linkend="int">int</link>         st_question                     (const <link linkend="char">char</link> *format,
                                             ...);</programlisting>
<warning><para><literal>st_question</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-prompt"/>st_prompt ()</title>
<indexterm><primary>st_prompt</primary></indexterm><programlisting><link linkend="char">char</link>*       st_prompt                       (<link linkend="gboolean">gboolean</link> hidden,
                                             const <link linkend="char">char</link> *init,
                                             const <link linkend="char">char</link> *format,
                                             ...);</programlisting>
<warning><para><literal>st_prompt</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hidden</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>init</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<link linkend="st-handler-notice"><function>st_handler_notice()</function></link>
</para>
</refsect1>

</refentry>
