gtk.texi

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

@item GTK_TYPE_BOOL @tab "gboolean"
@tab The boolean type.  It is some small integer where the number 0
     represents false and 1 is true.  No other values are allowed.
@item GTK_TYPE_INT @tab "gint"
@tab A signed integer with at least 32 bits.
@item GTK_TYPE_UINT @tab "guint"
@tab A unsigned integer with at least 32 bits.
@item GTK_TYPE_LONG @tab "glong"
@tab A signed integer with at least 32 bits.
@item GTK_TYPE_ULONG @tab "gulong"
@tab A unsigned integer with at least 32 bits.  This is large enough to
     hold a coerced pointer.
@item GTK_TYPE_FLOAT @tab "gfloat"
@tab A single precision floating point number.
@item GTK_TYPE_DOUBLE @tab "gfloat"
@tab A souble precision floating point number.
@item GTK_TYPE_POINTER @tab "gpointer"
@tab A untyped pointer.  Do not use this if you can avoid it.
@end multitable

The values of these types are all represented `directly' with the C
types that are indicated in the `name' column above.  @pxref{Boxed
types} for a discussion of this.

@node Enumerations and flags, Strings, Simple types, Types
@section Enumerations and Flags

@node Strings, Boxed types, Enumerations and flags, Types
@section Strings

@node Boxed types, Callbacks, Strings, Types
@section Boxed Types

@node Callbacks, Composite types, Boxed types, Types
@section Callbacks

@node Composite types,  , Callbacks, Types
@section Composite Types

@node Objects, Signals, Types, Top
@chapter Objects





















@section Object functions

The GtkObject type is the root of the type hierarchy used by GTK. It
provides a minimal set of fields used to implement the actual object,
class and signal mechanisms, as well as several utility routines which
make dealing with objects easier.

For the adventurous, see @ref{Object Implementation}.

@deftypefun guint gtk_object_get_type (void)
Returns the @code{GtkObject} type identifier.
@end deftypefun

@deftypefun void gtk_object_class_add_signals (GtkObjectClass *@var{class}, gint *@var{signals}, gint @var{nsignals})
Adds @var{signals} to the @code{signals} field in the GtkObjectClass
structure @var{class}. @xref{Signals}.
@end deftypefun

@deftypefun GtkObject* gtk_object_new (guint @var{type}, @dots{})
@end deftypefun

@deftypefun GtkObject* gtk_object_newv (guint @var{type}, guint @var{nargs}, GtkArg *@var{args})
@end deftypefun

@deftypefun void gtk_object_ref (GtkObject *@var{object});
@end deftypefun

@deftypefun void gtk_object_unref (GtkObject *@var{object});
@end deftypefun

@deftypefun void gtk_object_getv (GtkObject *@var{object}, guint @var{nargs}, GtkArg *@var{args})
@end deftypefun

@deftypefun void gtk_object_set (GtkObject *@var{object}, @dots{})
@end deftypefun

@deftypefun void gtk_object_setv (GtkObject *@var{object}, guint @var{nargs}, GtkArg *@var{args})
@end deftypefun

@deftypefun GtkArg* gtk_object_query_args (GtkType @var{class_type}, guint *@var{nargs})
@end deftypefun

@deftypefun void gtk_object_add_arg_type (gchar *@var{arg_name}, GtkType @var{arg_type}, guint @var{arg_id})
@end deftypefun

@deftypefun GtkType gtk_object_get_arg_type (gchar *@var{arg_name})
@end deftypefun


@deftypefun void gtk_object_destroy (GtkObject *@var{object})
Performs checks to make sure it is alright to destroy @var{object} and
then emits the @code{destroy} signal. The check which is performed is to
make sure @var{object} 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} is processing another
signal we mark @var{object} is needing to be destroyed. When we finish
processing of the other signal we check whether the object needs to be
destroyed.
@end deftypefun

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{gtk_object_get_data}, and @code{gtk_object_remove_data} are the
interface to this mechanism. Two other routines,
@code{gtk_object_set_user_data} and @code{gtk_object_get_user_data},
exist as convenience functions which simply use the same mechanism.

@deftypefun void gtk_object_set_data (GtkObject *@var{object}, const char *@var{key}, gpointer @var{data})
Associate @var{data} with @var{key} in the data list of @var{object}.
@end deftypefun

@deftypefun gpointer gtk_object_get_data (GtkObject *@var{object}, const char *@var{key})
Retrieve the data associated with @var{key} in the data list of @var{object}.
@end deftypefun

@deftypefun void gtk_object_remove_data (GtkObject *@var{object}, const char *@var{key})
Remove the data associated with @var{key} in the data list of @var{object}.
@end deftypefun

@deftypefun void gtk_object_set_user_data (GtkObject *@var{object}, gpointer @var{data})
Sets @var{data} into the @code{user_data} field of @var{object}.
@end deftypefun

@deftypefun gpointer gtk_object_get_user_data (GtkObject *@var{object})
Returns the @code{user_data} field of @var{object}.
@end deftypefun

@c ------------ Is this deprecated? -----------------

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).

@deftypefun void gtk_object_value_stack_new (guint @var{object_type}, const gchar *@var{value_id}, GtkParamType @var{value_type})
@end deftypefun

@deftypefun void gtk_object_push_value (guint @var{object_type}, const gchar *@var{value_id}, @dots{})
Push a value on the value stack specified by @var{object_type} and
@var{value_id}. The type of value is implicitly given in the context of
@var{object_type} and @var{value_id}. (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.
@end deftypefun

@deftypefun void gtk_object_pop_value (guint @var{object_type}, const gchar *@var{value_id})
Pop a value of the value stack specified by @var{object_type} and
@var{value_id}.
@end deftypefun

@deftypefun gint gtk_object_peek_value (guint @var{object_type}, const gchar *@var{value_id}, gpointer @var{data})
Peek at the value on the top of the value stack specified by
@var{object_type} and @var{value_id}. The @var{data} 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}, then
@var{data} 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} will
return @code{FALSE}. On success it will return @code{TRUE}.
@end deftypefun


@node Signals, Widgets, Objects, Top
@comment node-name, next, previous, up
@chapter Signals Overview
@cindex Signals

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.

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.

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.

@deftypefun gint gtk_signal_new (gchar *@var{name}, GtkSignalRunType @var{run_type}, gint @var{object_type}, gint @var{function_offset}, GtkSignalMarshaller @var{marshaller}, GtkParamType @var{return_val}, gint @var{nparams}, @dots{})
Create a new signal and give it the character string identifier
@var{name}. @var{name} needs to be unique in the context of
@var{object_type}'s branch of the class hierarchy. That is,
@var{object_type} cannot create a signal type with the same name as a
signal type created by one of its parent types.

@var{run_type} specifies whether the class function should be run before
(@code{GTK_RUN_FIRST}), after (@code{GTK_RUN_LAST}) or both before and
after normal signal handlers (@code{GTK_RUN_BOTH}). Additionally, the
@code{GTK_RUN_NO_RECURSE} 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} 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} flag is used by the GtkAdjustment
widget).

The @var{function_offset} 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} 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)} will give the offset
of the @code{destroy} class function within the
@code{GtkObjectClass}. 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} structure ``is
a'' @code{GtkObjectClass} structure, etc.)

The @var{marshaller} 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).

The @var{return_val} and @var{nparams} 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{@dots{}}) specifies the types of the
arguments. These can be one of @code{GTK_PARAM_CHAR},
@code{GTK_PARAM_SHORT}, @code{GTK_PARAM_INT}, @code{GTK_PARAM_LONG},
@code{GTK_PARAM_POINTER} or @code{GTK_PARAM_FUNCTION}. It is undefined
to specify @code{GTK_PARAM_NONE} as an argument type, however it is OK
to use @code{GTK_PARAM_NONE} for @var{return_val}. (This corresponds to
returning a @code{void}).

@code{gtk_signal_new} 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.

@strong{Note:} @code{gtk_signal_new} is only needed by widget writers. A
normal user of GTK will never needed to invoke this function.
@end deftypefun

@deftypefun gint gtk_signal_lookup (gchar *@var{name}, gint @var{object_type})
Returns the integer identifier for the signal referenced by @var{name}
and @var{object_type}. If @var{object_type} does not define the signal
@var{name}, then the signal is looked for in @var{object_type}'s parent
type recursively.
@end deftypefun

@deftypefun gchar* gtk_signal_name (gint @var{signal_num})
@end deftypefun

@deftypefun gint gtk_signal_emit (GtkObject *@var{object}, gint @var{signal_type}, @dots{})
Emit the signal specified by the integer identifier @var{signal_type}
from @var{object}. If an error occurs, @code{gtk_signal_emit} will
return @code{FALSE} and will return @code{TRUE} on success. The signal
definition determines the parameters passed in the variable argument
list (@code{@dots{}}). For example, if the signal is defined as:

@example
  gint (* event) (GtkWidget *widget, GdkEvent *event);
@end example

Then a call to emit the ``event'' signal would look like:

@example