gtk.texi

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

marked as @samp{out} or @samp{inout} it means that the called module is
allowed to change the contents of the composite value and that these
changes need to be propagated back to the originator of the value.  Mode
@samp{out} means that the argument has no meaningful value at the
beginning and should not be read.  Mode @samp{in} specifies that the
called module is not allowed to change the value in any way.

The type system allows for an unbounded number of types.  Every widget
is a type for example and you can add new widget types at any time
without confusing the run-time implementation of the type system.
Nevertheless, all types are derived from a certain @dfn{fundamental}
type, and there are only a small and finite number of fundamental types.
We only specify rules for the fundamental types and all other types
inherit these rules from their fundamental type.  For example,
@samp{int} is a fundamental type, as is @samp{GtkObject}.  All widgets
derive from @samp{GtkObject} and so the rules for @samp{GtkObject} apply
to all widgets as well.

This derivation defines a type hierachy, but this hierachy is not
completely general.  You can't derive from @samp{int} for example, and
you can only have one level of derivation from @samp{enum}.  The
fundamental type @samp{GtkObject}, however, is the basis for the large
and deep hierarchy of widget types.

The individual fundamental types are defined and explained in the
following sections.  Here is a complete list of them:

@table @samp
@item none
The not-a-value type, similar to @samp{void}.
@item char
A character.  Internationalization issues are still undecided.
@item bool
True or false.
@item byte, ubyte, int, uint, long, ulong, float, double
The usual assortment of scalar types.
@item string
A string.  Internationalization issues are still undecided.
@item enum, flags
Enumerations with a fixed set of literals.  Either used to express a
single choice from this set or to individually turn on and off several
flags.
@item boxed
A pointer to an opaque structure that can be copied and destroyed.
@item callback
A pointer to a function with enough extra information so that it can
also be used for functions written in languages completely different
from C.
@item GtkObject
A pointer to a GtkObject or derived type.  The fun starts here.
@item args, slist, dlist, cvec, tvec
An assortment of composite types like linked lists and counted or
zero-terminated arrays.
@item pointer, signal, c_callback
Obsolete types.
@end table

@node Basics, Simple types, Type introduction, Types
@section Basic Concepts

The basis for the type system are the fundamental types.  At run-time,
they are represented by members of the @code{GtkFundamentalType}
enumeration.  For the static declarations, they are identified with a
unique name.

@deftp {Enumeration} GtkFundamentalType
This enumeration contains a member for each defined fundamental type.
Most members are listed along with the description of their semantics,
but one is listed here:

@table @code
@item GTK_TYPE_INVALID
No valid type is derived from this.  Use @code{GTK_TYPE_INVALID} to
express exceptional situations.  This member does not really correspond
to a fundamental type and thus there is no name for it.
@end table
@end deftp

@deftp {Data type} GtkType
The type @code{GtkType} holds the run-time representation of a type.  It
is a integer of a certain size.  The follwing macros are defined to
access the basic properties of a @code{GtkType}:

@deftypefn {Macro} {unsigned int} GTK_TYPE_SEQNO (GtkType type)
Returns the sequence number of @var{type}.  The sequence numbers are
guaranteed to be dense, i.e., you can use them to index a table and the
table need not be much larger than the number of different GtkTypes that
you might encounter.
@end deftypefn

@deftypefn {Macro} GtkFundamentalType GTK_FUNDAMENTAL_TYPE (GtkType type)
Returns the fundamental type of @var{type}.
@end deftypefn

Both macros simply access different bit-fields of a @code{GtkType}, so
they are very efficient.
@end deftp

New types are registered with the @code{gtk_type_unique} function.  Any
kind oftype can be registered with @code{gtk_type_unique} but there are
convenience functions for most fundamental types.  Each fundamental type
has its own interpretation of the rules below and these convenience
functions should be used to automatically get the type registration
right.  So, don't be put off by the apparent complexity of the interface
to @code{gtk_type_unique}.  You will be using it only for new widgets,
and there the rules are simple.

The @code{GtkTypeInfo} structure is used to communicate information to
@code{gtk_type_unique} as opposed to passing in large numbers of
parameters.

@example
typedef struct _GtkTypeInfo GtkTypeInfo;

struct _GtkTypeInfo
@{
  gchar *type_name;
  guint object_size;
  guint class_size;
  GtkClassInitFunc class_init_func;
  GtkObjectInitFunc object_init_func;
  gpointer reserved_1;
  gpointer reserved_2;
  GtkClassInitFunc base_class_init_func;
@}
@end example

@itemize @bullet
@item
The @code{type_name} field refers to the name of the type.  This is the
same name that is used in the static definitions.  It is convention for
the type name to be closely related to the name of the underlying C
type. For example, the type name of the @code{GtkObject} structure is
``GtkObject'', and the name of the @code{GtkWindowType} enumeration is
``GtkWindowType''.  Note that the C type corresponding to ``GtkObject''
is really a pointer to a @code{GtkObject} struct, but the name has no
``*'' in it.

@item
The @code{object_size} field refers to the size in bytes of the C
structure for types that have such a structure. The easiest (and
portable) means of computing this size is by using the C @code{sizeof}
operator. For instance, the sizeof of the @code{GtkObject} structure is
computed by doing @code{sizeof (GtkObject)}.  When the type has no
associated structure or when you do not want to support the
@code{gtk_type_new} function for the new type, set @code{object_size} to
0.  Only types derived from GTK_TYPE_OBJECT can be handled by
@code{gtk_type_new}, anyway.

@item
The @code{class_size} field refers to the size in bytes of the C
structure for the class.  Again, the @code{sizeof} operator should be
used to compute this value.  If you don't want to have a class structure
for this type, set the field to 0.  @code{gtk_type_class} will then
always return @code{NULL}.

@item
The @code{class_init_func} and @code{base_class_init_func} fields are
callbacks which are used by the type mechanism to initialize class
specific fields. The single argument these function taks is a pointer to
a class structure.  When you do not need one or both of them, set the
corresponding field to @code{NULL}.  The @code{class_init_func} will be
called at most once, right after the class structure of size
@code{class_size} has been allocated.  The interaction between
@code{class_init_func} and @code{base_class_init_func} is only really
useful for the full-fledged object system.  It is described there
@pxref{Objects}.

@item
The @code{object_init_func} field is a callback which is used by the
type mechanism to initialize object specific fields for structures that
have been allocated via @code{gtk_type_new}. The single argument this
functions takes is a pointer to an object structure.  If you do not want
any special object initialization to take place, set this to
@code{NULL}.  All object initialization functions for all types that are
part of the inheritance chain are called, starting with the most basic
type.

@end itemize

@deftypefun guint gtk_type_unique (GtkType @var{parent_type}, GtkTypeInfo *@var{type_info})
The @var{parent_type} is simply the new types parent type. If
@var{parent_type} is GTK_TYPE_INVALID, then the new type is a new
fundamental type.  You should @b{never} register new fundamental types.
@var{type_info} is a pointer to a structure which contains necessary
information for construction of the new type.

You can only register a specific name once.
@end deftypefun

@deftypefun gchar* gtk_type_name (GtkType @var{type})
The returned string is the name of @var{type} as specified to
@code{gtk_type_unique}.
@end deftypefun

@deftypefun GtkType gtk_type_from_name (guchar *@var{name})
Return the type associated with @var{name}. If there is no type
associated with @var{name}, then GTK_TYPE_INVALID will be returned.
@end deftypefun

@deftypefun GtkType gtk_type_parent (GtkType @var{type})
Returns the parent type of @var{type} or GTK_TYPE_INVALID if @var{type}
is a fundamental type.
@end deftypefun

@deftypefun gpointer gtk_type_class (GtkType @var{type})
Returns the initialized class structure for @var{type}. The class
structure is actually created and initialized the first time it is
needed.  Refer to @pxref{Objects} for details on how this initialization works for GTK_TYPE_OBJECT derived types.

@c  If creation and initialization occurs, the @code{class_size}
@c  field of the @code{GtkTypeInfo} structure used to initialize this type
@c  is used to determine how large the class structure is. The
@c  @code{class_init_func} field from the @code{GtkTypeInfo} structure is
@c  called for all the members in the types ancestry, including the
@c  type. The order of this invocation proceeds from the root on down. For
@c  example, the @code{GtkWidgetClass} is first initialized as an
@c  @code{GtkObjectClass} by the object class initialization routine and
@c  then by the widget class initialization routine. This allows the widget
@c  class initialization routine to override values set by the object class
@c  initialization routine.

The returned structure is shared by all objects of @var{type} and, as
such, should not be modified.
@end deftypefun

@deftypefun gpointer gtk_type_new (GtkType @var{type})
Returns a new instance of an @var{type} object.  This works only for GTK_TYPE_OBJECT derived types.  Please see @pxref{Objects}.
@c  The @code{object_size}
@c  and @code{object_init_func} fields of the @code{GtkTypeInfo} structure
@c  are used to determine the objects allocated size and the object specific
@c  initialization routine. Similarly to the class initialization, all the
@c  object initialization routines from the root on down to the particular
@c  type being created are invoked.
@end deftypefun

@deftypefun void gtk_type_describe_heritage (GtkType @var{type})
Prints the type heritage for @var{type}. The heritage for a type
includes the type and all its parent types up the type tree.
@end deftypefun

@deftypefun void gtk_type_describe_tree (GtkType @var{type}, gboolean @var{show_size})
Prints the type tree which starts at @var{type}. @var{show_size} is a
boolean which determines whether type sizes are printed.
@end deftypefun

@deftypefun gboolean gtk_type_is_a (GtkType @var{type}, GtkType @var{is_a_type})
A predicate function which determines whether the relation @var{type}
is_a @var{is_a_type} is true.
@end deftypefun

@c  @deftypefun void gtk_type_get_arg (GtkObject *@var{object}, GtkType @var{type}, GtkArg *@var{arg}, guint @var{arg_id})
@c  @end deftypefun

@c  @deftypefun void gtk_type_set_arg (GtkObject *@var{object}, GtkType @var{type}, GtkArg *@var{arg}, guint @var{arg_id})
@c  @end deftypefun

Values of all types can be handled uniformly by storing them into a
@code{GtkArg} structure.  The @code{GtkArg} has the following fields:

@table @code
@item gchar *name
This can be used to give the value represented by this @code{GtkArg}
structure a name.  It is not used much.

@item GtkType type
The type of this value.

@item union d
A big union that has (at least conceptually) one member for each
fundamental type.  You should not access these members directly.
Rather, use the @code{GTK_VALUE_*} macros.  There is one macro for each
fundamental type, and its name is derived from the name of the
GtkFundamentalType enumeration members simply by replacing ``Gtk_TYPE''
with ``GTK_VALUE''.  All @code{GTK_VALUE_*} macros take a @code{GtkArg}
structure as their only parameter (@emph{not} a pointer) and evaluate to
a lvalue.
@end table

For example, the accessor for the fundamental type GTK_TYPE_INT is
called GTK_VALUE_INT and you could use it like this:

@example
GtkArg value;

value.name = NULL;
value.type = GTK_TYPE_INT;
GTK_VALUE_INT(value) = 7;
@end example

@node Simple types, Enumerations and flags, Basics, Types
@section Simple Types

The Gtk type system has a full set of the usual simple types: integers,
floating point numbers, but also boolean and character.  You can not
derive new types from these.

@multitable {GTK_TYPE_POINTER} {"gpointer"} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item Enum @tab Name @tab Description
@item GTK_TYPE_NONE @tab "void"
@tab A type without value.
@item GTK_TYPE_CHAR @tab "char"
@tab A 8-bit unsigned number representing a character.  Numbers
     between 0 and 127 are ASCII, the rest is undefined.