gtk-signals.html

该压缩包包含了GTK+的大量API函数

HREF=../glib/glib-basic-types.html#GUINT
>guint</A> signal_id,
                                             <A
HREF="gtk-signals.html#GTKEMISSIONHOOK"
>GtkEmissionHook</A
> hook_func,
                                             <A
HREF=../glib/glib-basic-types.html#GPOINTER
>gpointer</A> data);
<A
HREF=../glib/glib-basic-types.html#GUINT
>guint</A>       <A
HREF="gtk-signals.html#GTK-SIGNAL-ADD-EMISSION-HOOK-FULL"
>gtk_signal_add_emission_hook_full</A
>
                                            (<A
HREF=../glib/glib-basic-types.html#GUINT
>guint</A> signal_id,
                                             <A
HREF="gtk-signals.html#GTKEMISSIONHOOK"
>GtkEmissionHook</A
> hook_func,
                                             <A
HREF=../glib/glib-basic-types.html#GPOINTER
>gpointer</A> data,
                                             <A
HREF=../glib/glib-datasets.html#GDESTROYNOTIFY
>GDestroyNotify</A> destroy);
void        <A
HREF="gtk-signals.html#GTK-SIGNAL-REMOVE-EMISSION-HOOK"
>gtk_signal_remove_emission_hook</A
> (<A
HREF=../glib/glib-basic-types.html#GUINT
>guint</A> signal_id,
                                             <A
HREF=../glib/glib-basic-types.html#GUINT
>guint</A> hook_id);</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7803"
></A
><H2
>Description</H2
><DIV
CLASS="REFSECT2"
><A
NAME="AEN7805"
></A
><H3
>What are signals?</H3
><P
>Signals are a way to get notification when something happens
and to customize object behavior according to the
user's needs.
Every <I
CLASS="WORDASWORD"
>signal</I
> is uniquely identified by a name,
"class_name::signal_name", where signal_name might be something like
"clicked" and class_name might be "GtkButton".  Note that some other class
may also define a "clicked" callback, so long as it doesn't derive from
<A
HREF="gtkbutton.html"
>GtkButton</A
>.</P
><P
>When they are created, they are also assigned a unique positive integer,
the signal id (1 is the first signal id- 0 is used to flag an error).
Each is also tied to an array of types that describes
the prototype of the function pointer(s) (handlers) you may
connect to the signal.  Finally, every signal has
a default handler that is given by a function pointer
in its class structure:  it is run by default whenever the
signal is emitted.  (It is possible that a signal will
be emitted and a user-defined handler will prevent the default handler
from being run.)</P
><P
>Signals are used by everyone, but they are only
created on a per class basis-- so you should call
call <A
HREF="gtk-signals.html#GTK-SIGNAL-NEW"
>gtk_signal_new</A
>() unless you are writing
a new <A
HREF="gtkobject.html"
>GtkObject</A
> type.  However, if you want to make a new signal
for an existing type, you may use <A
HREF="gtkobject.html#GTK-OBJECT-CLASS-USER-SIGNAL-NEW"
>gtk_object_class_user_signal_new</A
>()
to create a signal that doesn't correspond to a class's builtin
methods.</P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN7815"
></A
><H3
>How are signals used?</H3
><P
>There are two basic actions in the signal handling game.
If you want notification of an event, you must <I
CLASS="EMPHASIS"
>connect</I
>
a function pointer and a data pointer to that signal;  the data pointer
will be passed as the last argument to the function (so long as you
are using the default marshalling functions).
You will receive a connection id, a unique positive integer
corresponding to that attachment.</P
><P
>Functions that want to notify the user of certain actions,
<I
CLASS="EMPHASIS"
>emit</I
> signals.</P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN7821"
></A
><H3
>Basic Terminology</H3
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>signal</DT
><DD
><P
>A class method, e.g. GtkButton::clicked.
More precisely it is a unique class-branch/signal-name pair.
This means you may not define a signal handler for a class which
derives from GtkButton that is called clicked,
but it is okay to share signals names if they are separate in
the class tree.</P
></DD
><DT
>default handler</DT
><DD
><P
>The object's internal method which is invoked
when the signal is emitted.</P
></DD
><DT
>user-defined handler</DT
><DD
><P
>A function pointer and data connected
to a signal (for a particular object).</P
><P
>There are really two types: those which are connected
normally, and those which are connected by one 
of the connect_after functions.  The connect_after handlers
are always run after the default handler.</P
><P
>Many toolkits refer to these as <I
CLASS="WORDASWORD"
>callbacks</I
>.</P
></DD
><DT
>emission</DT
><DD
><P
>the whole process of emitting a signal,
including the invocation of all
the different handler types mentioned above.</P
></DD
><DT
>signal id</DT
><DD
><P
>The unique positive (nonzero) integer
used to identify a signal.  It can be used instead of 
a name to many functions for a slight performance
improvement.</P
></DD
><DT
>connection id</DT
><DD
><P
>The unique positive (nonzero) integer
used to identify the connection of a user-defined handler
to a signal.  Notice that it is allowed to connect the
same function-pointer/user-data pair twice, so
there is no guarantee that a function-pointer/user-data
maps to a unique connection id.</P
></DD
></DL
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN7851"
></A
><H3
>A brief note on how they work.</H3
><P
>The functions responsible for translating an array of GtkArgs
to your C compiler's normal semantics are called Marshallers.
They are identified by
gtk_marshal_return_value__parameter_list()
for example a C function returning a gboolean and taking a gint
can be invoked by using gtk_marshal_BOOL__INT().
Not all possibly combinations of return/params are available,
of course, so if you are writing a <A
HREF="gtkobject.html"
>GtkObject</A
> with parameters
you might have to write a marshaller.</P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN7858"
></A
><H2
>Details</H2
><DIV
CLASS="REFSECT2"
><A
NAME="AEN7860"
></A
><H3
><A
NAME="GTK-SIGNAL-OFFSET-CAPS"
></A
>GTK_SIGNAL_OFFSET()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define GTK_SIGNAL_OFFSET(struct, field)	(GTK_STRUCT_OFFSET (struct, field))</PRE
></TD
></TR
></TABLE
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN7865"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>struct</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>&nbsp;</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>field</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>&nbsp;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN7878"
></A
><H3
><A
NAME="GTKSIGNALMARSHAL"
></A
>GtkSignalMarshal ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void        (*GtkSignalMarshal)             (<A
HREF="gtkobject.html"
>GtkObject</A
> *object,
                                             <A
HREF=../glib/glib-basic-types.html#GPOINTER
>gpointer</A> data,
                                             <A
HREF=../glib/glib-basic-types.html#GUINT
>guint</A> nparams,
                                             <A
HREF="gtk-types.html#GTKARG"
>GtkArg</A
> *args,
                                             <A
HREF="gtk-types.html#GTKTYPE"
>GtkType</A
> *arg_types,
                                             <A
HREF="gtk-types.html#GTKTYPE"
>GtkType</A
> return_type);</PRE
></TD
></TR
></TABLE
><P
>This is currently a hack left in for a scheme wrapper library.
It may be removed.</P
><P
>Don't use it.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN7890"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>object</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The object which emits the signal.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>data</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The user data associated with the hook.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>nparams</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The number of parameters to the function.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>args</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The actual values of the arguments.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>arg_types</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The types of the arguments.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>return_type</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The type of the return value from the function
or GTK_TYPE_NONE for no return value.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN7920"
></A
><H3
><A
NAME="GTKSIGNALDESTROY"
></A
>GtkSignalDestroy ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void        (*GtkSignalDestroy)             (<A
HREF=../glib/glib-basic-types.html#GPOINTER
>gpointer</A> data);</PRE
></TD
></TR
></TABLE
><P
>A function which you can use to clean up when the
signal handler is destroyed.</P
><P
>For example, if your handler requires a few variables
that you made into a struct and allocated (using <A
HREF=../glib/glib-memory-allocation.html#G-NEW
>g_new</A>()
or something), then you will probably want to free
it as soon as the hook is destroyed.  This will
allow you to do that. (For this in particular
it is convenient to pass <A
HREF=../glib/glib-memory-allocation.html#G-FREE
>g_free</A>() as a <A
HREF="gtk-signals.html#GTKSIGNALDESTROY"
>GtkSignalDestroy</A
>
function).</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN7930"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>data</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The user data associated with the hook that is being
destroyed.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN7939"
></A
><H3
><A
NAME="GTKEMISSIONHOOK"
></A
>GtkEmissionHook ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
><A
HREF=../glib/glib-basic-types.html#GBOOLEAN
>gboolean</A>    (*GtkEmissionHook)              (<A
HREF="gtkobject.html"
>GtkObject</A
> *object,
                                             <A
HREF=../glib/glib-basic-types.html#GUINT
>guint</A> signal_id,
                                             <A
HREF=../glib/glib-basic-types.html#GUINT
>guint</A> n_params,
                                             <A
HREF="gtk-types.html#GTKARG"
>GtkArg</A
> *params,
                                             <A
HREF=../glib/glib-basic-types.html#GPOINTER
>gpointer</A> data);</PRE
></TD
></TR
></TABLE
><P
>A simple function pointer to get invoked when the
signal is emitted.  This allows you tie a hook to the signal type,
so that it will trap all emissions of that signal, from any object.</P
><P
>You may not attach these to signals created with the
GTK_RUN_NO_HOOKS flag.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN7952"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>object</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the object which emits the signal.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>signal_id</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the unique integer identify the signal type.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>n_params</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the number of parameters to the function,
not including return value.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>params</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the parameters to the function.  A pointer to
the return value is passed as a last element.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>data</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the user data associated with the hook.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><I
CLASS="EMPHASIS"
>Returns</I
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>whether it wished to be removed.  If it returns
TRUE, the signal hook is disconnected (and destroyed).
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV