218 lines
11 KiB
XML
218 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
|
|
|
<refentry id="libgimpwidgets-GimpHelpUI">
|
|
<refmeta>
|
|
<refentrytitle>GimpHelpUI</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo>LIBGIMPWIDGETS Library</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>GimpHelpUI</refname><refpurpose>Functions for setting <link linkend="GtkTooltips"><type>GtkTooltips</type></link> and help identifier used by GIMP help
|
|
system.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv><title>Synopsis</title>
|
|
|
|
<synopsis>
|
|
|
|
|
|
|
|
<link linkend="void">void</link> (<link linkend="GimpHelpFunc">*GimpHelpFunc</link>) (const <link linkend="gchar">gchar</link> *help_id,
|
|
<link linkend="gpointer">gpointer</link> help_data);
|
|
#define <link linkend="GIMP-HELP-ID:CAPS">GIMP_HELP_ID</link>
|
|
<link linkend="void">void</link> <link linkend="gimp-help-enable-tooltips">gimp_help_enable_tooltips</link> (void);
|
|
<link linkend="void">void</link> <link linkend="gimp-help-disable-tooltips">gimp_help_disable_tooltips</link> (void);
|
|
<link linkend="void">void</link> <link linkend="gimp-standard-help-func">gimp_standard_help_func</link> (const <link linkend="gchar">gchar</link> *help_id,
|
|
<link linkend="gpointer">gpointer</link> help_data);
|
|
<link linkend="void">void</link> <link linkend="gimp-help-connect">gimp_help_connect</link> (<link linkend="GtkWidget">GtkWidget</link> *widget,
|
|
<link linkend="GimpHelpFunc">GimpHelpFunc</link> help_func,
|
|
const <link linkend="gchar">gchar</link> *help_id,
|
|
<link linkend="gpointer">gpointer</link> help_data);
|
|
<link linkend="void">void</link> <link linkend="gimp-help-set-help-data">gimp_help_set_help_data</link> (<link linkend="GtkWidget">GtkWidget</link> *widget,
|
|
const <link linkend="gchar">gchar</link> *tooltip,
|
|
const <link linkend="gchar">gchar</link> *help_id);
|
|
<link linkend="void">void</link> <link linkend="gimp-context-help">gimp_context_help</link> (<link linkend="GtkWidget">GtkWidget</link> *widget);
|
|
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Details</title>
|
|
<refsect2>
|
|
<title><anchor id="GimpHelpFunc"/>GimpHelpFunc ()</title>
|
|
<indexterm><primary>GimpHelpFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*GimpHelpFunc) (const <link linkend="gchar">gchar</link> *help_id,
|
|
<link linkend="gpointer">gpointer</link> help_data);</programlisting>
|
|
<para>
|
|
This is the prototype for all functions you pass as <parameter>help_func</parameter> to the
|
|
various GIMP dialog constructors like <link linkend="gimp-dialog-new"><function>gimp_dialog_new()</function></link>,
|
|
<link linkend="gimp-query-int-box"><function>gimp_query_int_box()</function></link> etc.
|
|
</para>
|
|
|
|
<para>
|
|
Help IDs are textual identifiers the help system uses to figure which
|
|
page to display.
|
|
</para>
|
|
|
|
<para>
|
|
All these dialog constructors functions call <link linkend="gimp-help-connect"><function>gimp_help_connect()</function></link>.
|
|
</para>
|
|
|
|
<para>
|
|
In most cases it will be ok to use <link linkend="gimp-standard-help-func"><function>gimp_standard_help_func()</function></link> which does
|
|
nothing but passing the <parameter>help_id</parameter> string to <link linkend="gimp-help"><function>gimp_help()</function></link>. If your
|
|
plug-in needs some more sophisticated help handling you can provide
|
|
your own <parameter>help_func</parameter> which has to call <link linkend="gimp-help"><function>gimp_help()</function></link> to actually display
|
|
the help.
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>help_id</parameter> :</term>
|
|
<listitem><simpara>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>help_data</parameter> :</term>
|
|
<listitem><simpara>
|
|
|
|
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="GIMP-HELP-ID:CAPS"/>GIMP_HELP_ID</title>
|
|
<indexterm><primary>GIMP_HELP_ID</primary></indexterm><programlisting>#define GIMP_HELP_ID (gimp_help_id_quark ())
|
|
</programlisting>
|
|
<para>
|
|
Since: GIMP 2.2
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-help-enable-tooltips"/>gimp_help_enable_tooltips ()</title>
|
|
<indexterm><primary>gimp_help_enable_tooltips</primary></indexterm><programlisting><link linkend="void">void</link> gimp_help_enable_tooltips (void);</programlisting>
|
|
<para>
|
|
This function calls <link linkend="gtk-tooltips-enable"><function>gtk_tooltips_enable()</function></link>.</para>
|
|
<para>
|
|
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-help-disable-tooltips"/>gimp_help_disable_tooltips ()</title>
|
|
<indexterm><primary>gimp_help_disable_tooltips</primary></indexterm><programlisting><link linkend="void">void</link> gimp_help_disable_tooltips (void);</programlisting>
|
|
<para>
|
|
This function calls <link linkend="gtk-tooltips-disable"><function>gtk_tooltips_disable()</function></link>.</para>
|
|
<para>
|
|
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-standard-help-func"/>gimp_standard_help_func ()</title>
|
|
<indexterm><primary>gimp_standard_help_func</primary></indexterm><programlisting><link linkend="void">void</link> gimp_standard_help_func (const <link linkend="gchar">gchar</link> *help_id,
|
|
<link linkend="gpointer">gpointer</link> help_data);</programlisting>
|
|
<para>
|
|
This is the standard GIMP help function which does nothing but calling
|
|
<link linkend="gimp-help"><function>gimp_help()</function></link>. It is the right function to use in almost all cases.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>help_id</parameter> :</term>
|
|
<listitem><simpara> A unique help identifier.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>help_data</parameter> :</term>
|
|
<listitem><simpara> The <parameter>help_data</parameter> passed to <link linkend="gimp-help-connect"><function>gimp_help_connect()</function></link>.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-help-connect"/>gimp_help_connect ()</title>
|
|
<indexterm><primary>gimp_help_connect</primary></indexterm><programlisting><link linkend="void">void</link> gimp_help_connect (<link linkend="GtkWidget">GtkWidget</link> *widget,
|
|
<link linkend="GimpHelpFunc">GimpHelpFunc</link> help_func,
|
|
const <link linkend="gchar">gchar</link> *help_id,
|
|
<link linkend="gpointer">gpointer</link> help_data);</programlisting>
|
|
<para>
|
|
Note that this function is automatically called by all libgimp dialog
|
|
constructors. You only have to call it for windows/dialogs you created
|
|
"manually".</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>widget</parameter> :</term>
|
|
<listitem><simpara> The widget you want to connect the help accelerator for. Will
|
|
be a <link linkend="GtkWindow"><type>GtkWindow</type></link> in most cases.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>help_func</parameter> :</term>
|
|
<listitem><simpara> The function which will be called if the user presses "F1".
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>help_id</parameter> :</term>
|
|
<listitem><simpara> The <parameter>help_id</parameter> which will be passed to <parameter>help_func</parameter>.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>help_data</parameter> :</term>
|
|
<listitem><simpara> The <parameter>help_data</parameter> pointer which will be passed to <parameter>help_func</parameter>.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-help-set-help-data"/>gimp_help_set_help_data ()</title>
|
|
<indexterm><primary>gimp_help_set_help_data</primary></indexterm><programlisting><link linkend="void">void</link> gimp_help_set_help_data (<link linkend="GtkWidget">GtkWidget</link> *widget,
|
|
const <link linkend="gchar">gchar</link> *tooltip,
|
|
const <link linkend="gchar">gchar</link> *help_id);</programlisting>
|
|
<para>
|
|
The reason why we don't use <link linkend="gtk-tooltips-set-tip"><function>gtk_tooltips_set_tip()</function></link> is that it's
|
|
impossible to set a <parameter>private_tip</parameter> (aka <parameter>help_id</parameter>) without a visible
|
|
<parameter>tooltip</parameter>.
|
|
</para>
|
|
<para>
|
|
This function can be called with <link linkend="NULL:CAPS"><type>NULL</type></link> for <parameter>tooltip</parameter>. Use this feature
|
|
if you want to set a help link for a widget which shouldn't have
|
|
a visible tooltip.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>widget</parameter> :</term>
|
|
<listitem><simpara> The <link linkend="GtkWidget"><type>GtkWidget</type></link> you want to set a <parameter>tooltip</parameter> and/or <parameter>help_id</parameter> for.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>tooltip</parameter> :</term>
|
|
<listitem><simpara> The text for this widget's tooltip (or <literal>NULL</literal>).
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>help_id</parameter> :</term>
|
|
<listitem><simpara> The <parameter>help_id</parameter> for the <link linkend="GtkTipsQuery"><type>GtkTipsQuery</type></link> tooltips inspector.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-context-help"/>gimp_context_help ()</title>
|
|
<indexterm><primary>gimp_context_help</primary></indexterm><programlisting><link linkend="void">void</link> gimp_context_help (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
|
|
<para>
|
|
This function invokes the context help inspector.
|
|
</para>
|
|
<para>
|
|
The mouse cursor will turn turn into a question mark and the user can
|
|
click on any widget of the application which started the inspector.
|
|
</para>
|
|
<para>
|
|
If the widget the user clicked on has a <parameter>help_id</parameter> string attached
|
|
(see <link linkend="gimp-help-set-help-data"><function>gimp_help_set_help_data()</function></link>), the corresponding help page will
|
|
be displayed. Otherwise the help system will ascend the widget hierarchy
|
|
until it finds an attached <parameter>help_id</parameter> string (which should be the
|
|
case at least for every window/dialog).</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>widget</parameter> :</term>
|
|
<listitem><simpara> Any <link linkend="GtkWidget"><type>GtkWidget</type></link> on the screen.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
|
|
</refentry>
|