DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(gtk.info.gz) Basics

Info Catalog (gtk.info.gz) Type introduction (gtk.info.gz) Types (gtk.info.gz) Simple types
 
 Basic Concepts
 ==============
 
    The basis for the type system are the fundamental types.  At
 run-time, they are represented by members of the `GtkFundamentalType'
 enumeration.  For the static declarations, they are identified with a
 unique name.
 
  - 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:
 
     `GTK_TYPE_INVALID'
           No valid type is derived from this.  Use `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.
 
  - Data type: GtkType
      The type `GtkType' holds the run-time representation of a type.  It
      is an integer of a certain size.  The follwing macros are defined
      to access the basic properties of a `GtkType':
 
       - Macro: unsigned int GTK_TYPE_SEQNO (GtkType type)
           Returns the sequence number of 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.
 
       - Macro: GtkFundamentalType GTK_FUNDAMENTAL_TYPE (GtkType type)
           Returns the fundamental type of TYPE.
 
      Both macros simply access different bit-fields of a `GtkType', so
      they are very efficient.
 
    New types are registered with the `gtk_type_unique' function.  Any
 kind oftype can be registered with `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 `gtk_type_unique'.  You will be using it only for new widgets, and
 there the rules are simple.
 
    The `GtkTypeInfo' structure is used to communicate information to
 `gtk_type_unique' as opposed to passing in large numbers of parameters.
 
      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;
      }
 
    * The `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
      `GtkObject' structure is "GtkObject", and the name of the
      `GtkWindowType' enumeration is "GtkWindowType".  Note that the C
      type corresponding to "GtkObject" is really a pointer to a
      `GtkObject' struct, but the name has no "*" in it.
 
    * The `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 `sizeof'
      operator. For instance, the sizeof of the `GtkObject' structure is
      computed by doing `sizeof (GtkObject)'.  When the type has no
      associated structure or when you do not want to support the
      `gtk_type_new' function for the new type, set `object_size' to 0.
      Only types derived from GTK_TYPE_OBJECT can be handled by
      `gtk_type_new', anyway.
 
    * The `class_size' field refers to the size in bytes of the C
      structure for the class.  Again, the `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.  `gtk_type_class'
      will then always return `NULL'.
 
    * The `class_init_func' and `base_class_init_func' fields are
      callbacks which are used by the type mechanism to initialize class
      specific fields. The single argument these functions take is a
      pointer to a class structure.  When you do not need one or both of
      them, set the corresponding field to `NULL'.  The
      `class_init_func' will be called at most once, right after the
      class structure of size `class_size' has been allocated.  The
      interaction between `class_init_func' and `base_class_init_func'
      is only really useful for the full-fledged object system.  It is
      described there  Objects.
 
    * The `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 `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 `NULL'.  All object initialization functions for all types
      that are part of the inheritance chain are called, starting with
      the most basic type.
 
 
  - Function: guint gtk_type_unique (GtkType PARENT_TYPE, GtkTypeInfo
           *TYPE_INFO)
      The PARENT_TYPE is simply the new types parent type. If
      PARENT_TYPE is GTK_TYPE_INVALID, then the new type is a new
      fundamental type.  You should never register new fundamental types.
      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.
 
  - Function: gchar* gtk_type_name (GtkType TYPE)
      The returned string is the name of TYPE as specified to
      `gtk_type_unique'.
 
  - Function: GtkType gtk_type_from_name (guchar *NAME)
      Return the type associated with NAME. If there is no type
      associated with NAME, then GTK_TYPE_INVALID will be returned.
 
  - Function: GtkType gtk_type_parent (GtkType TYPE)
      Returns the parent type of TYPE or GTK_TYPE_INVALID if TYPE is a
      fundamental type.
 
  - Function: gpointer gtk_type_class (GtkType TYPE)
      Returns the initialized class structure for TYPE. The class
      structure is actually created and initialized the first time it is
      needed.  Refer to  Objects for details on how this
      initialization works for GTK_TYPE_OBJECT derived types.
 
      The returned structure is shared by all objects of TYPE and, as
      such, should not be modified.
 
  - Function: gpointer gtk_type_new (GtkType TYPE)
      Returns a new instance of an TYPE object.  This works only for
      GTK_TYPE_OBJECT derived types.  Please see  Objects.
 
  - Function: void gtk_type_describe_heritage (GtkType TYPE)
      Prints the type heritage for TYPE. The heritage for a type
      includes the type and all its parent types up the type tree.
 
  - Function: void gtk_type_describe_tree (GtkType TYPE, gboolean
           SHOW_SIZE)
      Prints the type tree which starts at TYPE. SHOW_SIZE is a boolean
      which determines whether type sizes are printed.
 
  - Function: gboolean gtk_type_is_a (GtkType TYPE, GtkType IS_A_TYPE)
      A predicate function which determines whether the relation TYPE
      is_a IS_A_TYPE is true.
 
    Values of all types can be handled uniformly by storing them into a
 `GtkArg' structure.  The `GtkArg' has the following fields:
 
 `gchar *name'
      This can be used to give the value represented by this `GtkArg'
      structure a name.  It is not used much.
 
 `GtkType type'
      The type of this value.
 
 `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 `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 `GTK_VALUE_*' macros take a
      `GtkArg' structure as their only parameter (_not_ a pointer) and
      evaluate to a lvalue.
 
    For example, the accessor for the fundamental type GTK_TYPE_INT is
 called GTK_VALUE_INT and you could use it like this:
 
      GtkArg value;
      
      value.name = NULL;
      value.type = GTK_TYPE_INT;
      GTK_VALUE_INT(value) = 7;
 
Info Catalog (gtk.info.gz) Type introduction (gtk.info.gz) Types (gtk.info.gz) Simple types
automatically generated byinfo2html