gtk.html

gtk是linux一款强大的夸平台的图形化开发工具

<DD><A NAME="IDX27"></A>
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_getv</B> <I>(GtkObject *<VAR>object</VAR>, guint <VAR>nargs</VAR>, GtkArg *<VAR>args</VAR>)</I>
<DD><A NAME="IDX28"></A>
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_set</B> <I>(GtkObject *<VAR>object</VAR>, ...)</I>
<DD><A NAME="IDX29"></A>
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_setv</B> <I>(GtkObject *<VAR>object</VAR>, guint <VAR>nargs</VAR>, GtkArg *<VAR>args</VAR>)</I>
<DD><A NAME="IDX30"></A>
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> GtkArg* <B>gtk_object_query_args</B> <I>(GtkType <VAR>class_type</VAR>, guint *<VAR>nargs</VAR>)</I>
<DD><A NAME="IDX31"></A>
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_add_arg_type</B> <I>(gchar *<VAR>arg_name</VAR>, GtkType <VAR>arg_type</VAR>, guint <VAR>arg_id</VAR>)</I>
<DD><A NAME="IDX32"></A>
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> GtkType <B>gtk_object_get_arg_type</B> <I>(gchar *<VAR>arg_name</VAR>)</I>
<DD><A NAME="IDX33"></A>
</DL>

</P>

<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_destroy</B> <I>(GtkObject *<VAR>object</VAR>)</I>
<DD><A NAME="IDX34"></A>
Performs checks to make sure it is alright to destroy <VAR>object</VAR> and
then emits the <CODE>destroy</CODE> signal. The check which is performed is to
make sure <VAR>object</VAR> is not already processing another signal. If this
were the case then destroying the object immediately would undoubtedly
cause problems as the other signal would not be able to tell the object
was destroyed. The solution is that if <VAR>object</VAR> is processing another
signal we mark <VAR>object</VAR> is needing to be destroyed. When we finish
processing of the other signal we check whether the object needs to be
destroyed.
</DL>

</P>
<P>
The GtkObject type provides a mechanism for associating arbitrary
amounts of data with an object. The data is associated with the object
using a character string key. The functions <CODE>gtk_object_set_data</CODE>,
<CODE>gtk_object_get_data</CODE>, and <CODE>gtk_object_remove_data</CODE> are the
interface to this mechanism. Two other routines,
<CODE>gtk_object_set_user_data</CODE> and <CODE>gtk_object_get_user_data</CODE>,
exist as convenience functions which simply use the same mechanism.

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_set_data</B> <I>(GtkObject *<VAR>object</VAR>, const char *<VAR>key</VAR>, gpointer <VAR>data</VAR>)</I>
<DD><A NAME="IDX35"></A>
Associate <VAR>data</VAR> with <VAR>key</VAR> in the data list of <VAR>object</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gpointer <B>gtk_object_get_data</B> <I>(GtkObject *<VAR>object</VAR>, const char *<VAR>key</VAR>)</I>
<DD><A NAME="IDX36"></A>
Retrieve the data associated with <VAR>key</VAR> in the data list of <VAR>object</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_remove_data</B> <I>(GtkObject *<VAR>object</VAR>, const char *<VAR>key</VAR>)</I>
<DD><A NAME="IDX37"></A>
Remove the data associated with <VAR>key</VAR> in the data list of <VAR>object</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_set_user_data</B> <I>(GtkObject *<VAR>object</VAR>, gpointer <VAR>data</VAR>)</I>
<DD><A NAME="IDX38"></A>
Sets <VAR>data</VAR> into the <CODE>user_data</CODE> field of <VAR>object</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gpointer <B>gtk_object_get_user_data</B> <I>(GtkObject *<VAR>object</VAR>)</I>
<DD><A NAME="IDX39"></A>
Returns the <CODE>user_data</CODE> field of <VAR>object</VAR>.
</DL>

</P>

<P>
The GtkObject type also provides a mechanism for specifying
initialization values for fields. This general mechanism is called
object value stacks. The reason for using value stacks is that they can
simplify the life of the programmer. For instance, by default widgets
are non-visible when created. However, the "visible" value for widgets
may be specified so that widgets are made visible when created. (FIXME:
unfinished).

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_value_stack_new</B> <I>(guint <VAR>object_type</VAR>, const gchar *<VAR>value_id</VAR>, GtkParamType <VAR>value_type</VAR>)</I>
<DD><A NAME="IDX40"></A>
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_push_value</B> <I>(guint <VAR>object_type</VAR>, const gchar *<VAR>value_id</VAR>, ...)</I>
<DD><A NAME="IDX41"></A>
Push a value on the value stack specified by <VAR>object_type</VAR> and
<VAR>value_id</VAR>. The type of value is implicitly given in the context of
<VAR>object_type</VAR> and <VAR>value_id</VAR>. (That is, it is not specified
explicitly in the function call). Only a single extra argument is
expected which is the data which is to be placed on the stack.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_object_pop_value</B> <I>(guint <VAR>object_type</VAR>, const gchar *<VAR>value_id</VAR>)</I>
<DD><A NAME="IDX42"></A>
Pop a value of the value stack specified by <VAR>object_type</VAR> and
<VAR>value_id</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gint <B>gtk_object_peek_value</B> <I>(guint <VAR>object_type</VAR>, const gchar *<VAR>value_id</VAR>, gpointer <VAR>data</VAR>)</I>
<DD><A NAME="IDX43"></A>
Peek at the value on the top of the value stack specified by
<VAR>object_type</VAR> and <VAR>value_id</VAR>. The <VAR>data</VAR> argument is
interpreted as the location of where to place the "peeked" data. For
instance, if the peeked data is of type <CODE>GTK_PARAM_POINTER</CODE>, then
<VAR>data</VAR> will be a pointer to a pointer. If the value stack is empty
or does not exist or an error occurs, <CODE>gtk_object_peek_value</CODE> will
return <CODE>FALSE</CODE>. On success it will return <CODE>TRUE</CODE>.
</DL>

</P>



<H1><A NAME="SEC14" HREF="gtk_toc.html#TOC14">Signals Overview</A></H1>
<P>
<A NAME="IDX44"></A>

</P>
<P>
Signals are GTK's method for objects to perform callbacks. A signal is
an event which occurs upon an object. The programmer can connect to a
signal of an object which involves specifying a function to be called
when that signal is emitted in the specified object.

</P>
<P>
When a signal is emitted, both the class function associated with the
signal (when it was defined) and all signal handlers installed for that
signal on the particular object emitting the signal are called. The
widget programmer can specify whether the class function is to be called
before after or both before and after the signal handlers installed by
the widget user. The widget user can, however, specify that their signal
handler is to be run after the class function (using the "_after"
signal connection routines). Any signal handling function can emit the
same signal on the same object while it is running causing that signal
emission to either restart or to run recursively. Additionally, signal
emission can be terminated prematurely. While both such abilities are
rarely used, they do allow for greater flexibility in regards to
signals. For instance, a programmer can attach to the key press event
signal and intercept all tab key presses from a widget. This particular
example is used in the file selection dialog to implement tab completion
of filenames and prevent the entry widget from inserting the tab into
its buffer.

</P>
<P>
Signals are selected using either an integer identifier or a character
string name. It is convention to name the signal the same as the class
function which is associated with it. There are two versions of most of
the signal functions, one which takes an integer identifier and one
which takes a character string name for the signal.

</P>
<P>
<DL>
<DT><U>Function:</U> gint <B>gtk_signal_new</B> <I>(gchar *<VAR>name</VAR>, GtkSignalRunType <VAR>run_type</VAR>, gint <VAR>object_type</VAR>, gint <VAR>function_offset</VAR>, GtkSignalMarshaller <VAR>marshaller</VAR>, GtkParamType <VAR>return_val</VAR>, gint <VAR>nparams</VAR>, ...)</I>
<DD><A NAME="IDX45"></A>
Create a new signal and give it the character string identifier
<VAR>name</VAR>. <VAR>name</VAR> needs to be unique in the context of
<VAR>object_type</VAR>'s branch of the class hierarchy. That is,
<VAR>object_type</VAR> cannot create a signal type with the same name as a
signal type created by one of its parent types.

</P>
<P>
<VAR>run_type</VAR> specifies whether the class function should be run before
(<CODE>GTK_RUN_FIRST</CODE>), after (<CODE>GTK_RUN_LAST</CODE>) or both before and
after normal signal handlers (<CODE>GTK_RUN_BOTH</CODE>). Additionally, the
<CODE>GTK_RUN_NO_RECURSE</CODE> value can be or'ed with any of those values to
specify that the signal should not be recursive. By default, emitting
the same signal on the same widget will cause the signal to be emitted
twice. However, if the <CODE>GTK_RUN_NO_RECURSE</CODE> flag is specified,
emitting the same signal on the same widget will cause the current
signal emission to be restarted. This allows the widget programmer to
specify the semantics of signal emission on a per signal
basis. (The <CODE>GTK_RUN_NO_RECURSE</CODE> flag is used by the GtkAdjustment
widget).

</P>
<P>
The <VAR>function_offset</VAR> is the byte offset from the start of the class
structure to the class function field within the class structure. The
easiest means to compute this offset is by using the
<CODE>GTK_SIGNAL_OFFSET</CODE> macro which takes the class structure type as
the first argument and the field as the second argument. For example,
<CODE>GTK_SIGNAL_OFFSET (GtkObjectClass, destroy)</CODE> will give the offset
of the <CODE>destroy</CODE> class function within the
<CODE>GtkObjectClass</CODE>. Note: An offset is specified instead of an
absolute location since there will be multiple instances of a class
structure being referenced. (The <CODE>GtkWidgetClass</CODE> structure "is
a" <CODE>GtkObjectClass</CODE> structure, etc.)

</P>
<P>
The <VAR>marshaller</VAR> function is used to invoke a signal handler. Since
signal handlers may take different parameters and return values and a
general mechanism for invoking them is not apparent, the approach of
making the signal creator responsible for invoking the signal handler
was taken. (FIXME: unfinished).

</P>
<P>
The <VAR>return_val</VAR> and <VAR>nparams</VAR> and the remaining arguments
specify the return value and the arguments to the signal handler
respectively. Note: There is an implicit first argument to every signal
handler which is the widget the signal has been emitted from. The
variable argument list (<VAR>...</VAR>) specifies the types of the
arguments. These can be one of <CODE>GTK_PARAM_CHAR</CODE>,
<CODE>GTK_PARAM_SHORT</CODE>, <CODE>GTK_PARAM_INT</CODE>, <CODE>GTK_PARAM_LONG</CODE>,
<CODE>GTK_PARAM_POINTER</CODE> or <CODE>GTK_PARAM_FUNCTION</CODE>. It is undefined
to specify <CODE>GTK_PARAM_NONE</CODE> as an argument type, however it is OK
to use <CODE>GTK_PARAM_NONE</CODE> for <VAR>return_val</VAR>. (This corresponds to
returning a <CODE>void</CODE>).

</P>
<P>
<CODE>gtk_signal_new</CODE> returns the integer identifier of the newly
created signal. Signal identifiers start numbering at 1 and increase
upwards. A value of -1 will be returned if an error occurs.

</P>
<P>
<STRONG>Note:</STRONG> <CODE>gtk_signal_new</CODE> is only needed by widget writers. A
normal user of GTK will never needed to invoke this function.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gint <B>gtk_signal_lookup</B> <I>(gchar *<VAR>name</VAR>, gint <VAR>object_type</VAR>)</I>
<DD><A NAME="IDX46"></A>
Returns the integer identifier for the signal referenced by <VAR>name</VAR>
and <VAR>object_type</VAR>. If <VAR>object_type</VAR> does not define the signal
<VAR>name</VAR>, then the signal is looked for in <VAR>object_type</VAR>'s parent
type recursively.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gchar* <B>gtk_signal_name</B> <I>(gint <VAR>signal_num</VAR>)</I>
<DD><A NAME="IDX47"></A>
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gint <B>gtk_signal_emit</B> <I>(GtkObject *<VAR>object</VAR>, gint <VAR>signal_type</VAR>, ...)</I>
<DD><A NAME="IDX48"></A>
Emit the signal specified by the integer identifier <VAR>signal_type</VAR>
from <VAR>object</VAR>. If an error occurs, <CODE>gtk_signal_emit</CODE> will
return <CODE>FALSE</CODE> and will return <CODE>TRUE</CODE> on success. The signal
definition determines the parameters passed in the variable argument
list (<CODE>...</CODE>). For example, if the signal is defined as:

</P>

<PRE>
  gint (* event) (GtkWidget *widget, GdkEvent *event);
</PRE>

<P>
Then a call to emit the "event" signal would look like:

</P>

<PRE>
  GdkEvent event;
  gint return_val;
  ...
  gtk_signal_emit (some_object,
                   gtk_signal_lookup ("event",
                     GTK_OBJECT_TYPE (some_object)),
                   &#38;event, &#38;return_val);
</PRE>

<P>
Notice that the <CODE>widget</CODE> argument is implicit in that the first
argument to every signal is a type derived from <CODE>GtkObject</CODE>. The
<VAR>return_val</VAR> argument is actually a pointer to the return value type
since the signal mechanism needs to be able to place the return value in
an actual location. And lastly, the <CODE>gtk_signal_lookup</CODE> call is
normally avoided by using the <CODE>gtk_signal_emit_by_name</CODE> function
instead. <CODE>gtk_signal_emit</CODE> is normally used internally by widgets
which know the signal identifier (since they defined the signal) and can
therefore side-step the cost of calling <CODE>gtk_signal_lookup</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gint <B>gtk_signal_emit_by_name</B> <I>(GtkObject *<VAR>object</VAR>, gchar *<VAR>name</VAR>, ...)</I>
<DD><A NAME="IDX49"></A>
Similar to <CODE>gtk_signal_emit</CODE> except that the signal is referenced
by <VAR>name</VAR> instead of by its integer identifier.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_signal_emit_stop</B> <I>(GtkObject *<VAR>object</VAR>, gint <VAR>signal_type</VAR>)</I>
<DD><A NAME="IDX50"></A>
Stop the emission of the signal <VAR>signal_type</VAR> on
<VAR>object</VAR>. <VAR>signal_type</VAR> is the integer identifier for the signal
and can be determined using the function
<CODE>gtk_signal_lookup</CODE>. Alternatively, the function
<CODE>gtk_signal_emit_stop_by_name</CODE> can be used to refer to the signal
by name. Attempting to stop the emission of a signal that isn't being
emitted does nothing.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gtk_signal_emit_stop_by_name</B> <I>(GtkObject *<VAR>object</VAR>, gchar *<VAR>name</VAR>)</I>
<DD><A NAME="IDX51"></A>
Similar to <CODE>gtk_signal_emit_stop</CODE> except that the signal is
referenced by <VAR>name</VAR> instead of by its integer identifier.