signals.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>destroy_data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>connect_flags</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="g-signal-connect-closure">g_signal_connect_closure ()</title>
<programlisting><link linkend="gulong">gulong</link>      g_signal_connect_closure        (<link linkend="gpointer">gpointer</link> instance,
                                             const <link linkend="gchar">gchar</link> *detailed_signal,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gboolean">gboolean</link> after);</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>instance</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>detailed_signal</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>closure</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>after</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="g-signal-connect-closure-by-id">g_signal_connect_closure_by_id ()</title>
<programlisting><link linkend="gulong">gulong</link>      g_signal_connect_closure_by_id  (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gboolean">gboolean</link> after);</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>instance</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>signal_id</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>detail</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>closure</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>after</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="g-signal-handler-block">g_signal_handler_block ()</title>
<programlisting>void        g_signal_handler_block          (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="gulong">gulong</link> handler_id);</programlisting>
<para>
<link linkend="g-signal-handler-block">g_signal_handler_block</link>() blocks a handler of an
instance so it will not be called during any signal emissions
unless it is unblocked again. Thus "blocking" a signal handler
means to temporarily deactive it, a signal handler has to be
unblocked exactly the same amount of times it has been blocked
before to become active again.
The <parameter>handler_id</parameter> passed into <link linkend="g-signal-handler-block">g_signal_handler_block</link>() has
to be a valid signal handler id, connected to a signal of
<parameter>instance</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>instance</parameter>&nbsp;:</entry>
<entry>	The instance to block the signal handler of.
</entry></row>
<row><entry align="right"><parameter>handler_id</parameter>&nbsp;:</entry>
<entry>	Handler id of the handler to be blocked.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-signal-handler-unblock">g_signal_handler_unblock ()</title>
<programlisting>void        g_signal_handler_unblock        (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="gulong">gulong</link> handler_id);</programlisting>
<para>
<link linkend="g-signal-handler-unblock">g_signal_handler_unblock</link>() undoes the effect of a previous
<link linkend="g-signal-handler-block">g_signal_handler_block</link>() call. A blocked handler is skipped
during signal emissions and will not be invoked, unblocking
it (for exactly the amount of times it has been blocked before)
reverts its "blocked" state, so the handler will be recognized
by the signal system and is called upon future or currently
ongoing signal emissions (since the order in which handlers are
called during signal emissions is deterministic, whether the
unblocked handler in question is called as part of a currently
ongoing emission depends on how far that emission has proceeded
yet).
The <parameter>handler_id</parameter> passed into <link linkend="g-signal-handler-unblock">g_signal_handler_unblock</link>() has
to be a valid id of a signal handler that is connected to a
signal of <parameter>instance</parameter> and is currently blocked.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>instance</parameter>&nbsp;:</entry>
<entry>	The instance to unblock the signal handler of.
</entry></row>
<row><entry align="right"><parameter>handler_id</parameter>&nbsp;:</entry>
<entry>	Handler id of the handler to be unblocked.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-signal-handler-disconnect">g_signal_handler_disconnect ()</title>
<programlisting>void        g_signal_handler_disconnect     (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="gulong">gulong</link> handler_id);</programlisting>
<para>
<link linkend="g-signal-handler-disconnect">g_signal_handler_disconnect</link>() disconnects a handler from an
instance so it will not be called during any future or currently
ongoing emissions of the signal it has been connected to.
The <parameter>handler_id</parameter> becomes invalid and may be reused.
The <parameter>handler_id</parameter> passed into <link linkend="g-signal-handler-disconnect">g_signal_handler_disconnect</link>() has
to be a valid signal handler id, connected to a signal of
<parameter>instance</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>instance</parameter>&nbsp;:</entry>
<entry>	The instance to remove the signal handler from.
</entry></row>
<row><entry align="right"><parameter>handler_id</parameter>&nbsp;:</entry>
<entry>	Handler id of the handler to be disconnected.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-signal-handler-find">g_signal_handler_find ()</title>
<programlisting><link linkend="gulong">gulong</link>      g_signal_handler_find           (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="GSignalMatchType">GSignalMatchType</link> mask,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> func,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Find the first signal handler that matches certain selection criteria.
The criteria mask is passed as an OR-ed combination of <link linkend="GSignalMatchType">GSignalMatchType</link>
flags, and the criteria values are passed as arguments.
The match <parameter>mask</parameter> has to be non-0 for successful matches.
If no handler was found, 0 is returned.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>instance</parameter>&nbsp;:</entry>
<entry>	The instance owning the signal handler to be found.
</entry></row>
<row><entry align="right"><parameter>mask</parameter>&nbsp;:</entry>
<entry>		Mask indicating which of <parameter>signal_id</parameter>, <parameter>detail</parameter>,
		<parameter>closure</parameter>, <parameter>func</parameter> and/or <parameter>data</parameter> the handler has to match.
</entry></row>
<row><entry align="right"><parameter>signal_id</parameter>&nbsp;:</entry>
<entry>	Signal the handler has to be connected to.
</entry></row>
<row><entry align="right"><parameter>detail</parameter>&nbsp;:</entry>
<entry>	Signal detail the handler has to be connected to.
</entry></row>
<row><entry align="right"><parameter>closure</parameter>&nbsp;:</entry>
<entry>	The closure the handler will invoke.
</entry></row>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry>		The C closure callback of the handler (useless for non-C closures).
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>		The closure data of the handler's closure.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>	A valid non-0 signal handler id for a successful match.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-signal-handlers-block-matched">g_signal_handlers_block_matched ()</title>
<programlisting><link linkend="guint">guint</link>       g_signal_handlers_block_matched (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="GSignalMatchType">GSignalMatchType</link> mask,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> func,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
This function blocks all handlers on an instance that match a certain
selection criteria. The criteria mask is passed as an OR-ed combination of
<link linkend="GSignalMatchType">GSignalMatchType</link> flags, and the criteria values are passed as arguments.
Passing at least one of the <literal>G_SIGNAL_MATCH_CLOSURE</literal>, <literal>G_SIGNAL_MATCH_FUNC</literal>
or <literal>G_SIGNAL_MATCH_DATA</literal> match flags is required for successful matches.
If no handlers were found, 0 is returned, the number of blocked handlers
otherwise.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>instance</parameter>&nbsp;:</entry>
<entry>	The instance to block handlers from.
</entry></row>
<row><entry align="right"><parameter>mask</parameter>&nbsp;:</entry>
<entry>		Mask indicating which of <parameter>signal_id</parameter>, <parameter>detail</parameter>,
		<parameter>closure</parameter>, <parameter>func</parameter> and/or <parameter>data</parameter> the handlers have to match.
</entry></row>
<row><entry align="right"><parameter>signal_id</parameter>&nbsp;:</entry>
<entry>	Signal the handlers have to be connected to.
</entry></row>
<row><entry align="right"><parameter>detail</parameter>&nbsp;:</entry>
<entry>	Signal detail the handlers have to be connected to.
</entry></row>
<row><entry align="right"><parameter>closure</parameter>&nbsp;:</entry>
<entry>	The closure the handlers will invoke.
</entry></row>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry>		The C closure callback of the handlers (useless for non-C closures).
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>		The closure data of the handlers' closures.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>	The amount of handlers