GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Implementation of Object Properties

## Name

Implementation of Object Properties -- Utility function to manipulate lists of named, typed arguments.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkArgInfo;
    GtkArg*     gtk_arg_new                     (GtkType arg_type);
    GtkArg*     gtk_arg_copy                    (GtkArg *src_arg,
                                                 GtkArg *dest_arg);
    void        gtk_arg_free                    (GtkArg *arg,
                                                 gboolean free_contents);
    gchar*      gtk_args_collect                (GtkType object_type,
                                                 GHashTable *arg_info_hash_table,
                                                 GSList **arg_list_p,
                                                 GSList **info_list_p,
                                                 const gchar *first_arg_name,
                                                 va_list var_args);
    void        gtk_args_collect_cleanup        (GSList *arg_list,
                                                 GSList *info_list);
    gchar*      gtk_arg_get_info                (GtkType object_type,
                                                 GHashTable *arg_info_hash_table,
                                                 const gchar *arg_name,
                                                 GtkArgInfo **info_p);
    GtkArgInfo* gtk_arg_type_new_static         (GtkType base_class_type,
                                                 const gchar *arg_name,
                                                 guint class_n_args_offset,
                                                 GHashTable *arg_info_hash_table,
                                                 GtkType arg_type,
                                                 guint arg_flags,
                                                 guint arg_id);
    GtkArg*     gtk_args_query                  (GtkType class_type,
                                                 GHashTable *arg_info_hash_table,
                                                 guint32 **arg_flags,
                                                 guint *n_args_p);
    gchar*      gtk_arg_name_strip_type         (const gchar *arg_name);
    gint        gtk_arg_info_equal              (gconstpointer arg_info_1,
                                                 gconstpointer arg_info_2);
    guint       gtk_arg_info_hash               (gconstpointer arg_info);

## Description

All the functions in here are marked a Non-public. We describe it anyway because it is occasionally useful to understand how the work is done.

Arguments are a way of describing a named parameter to a function. They have two important roles within gtk+:

- they describe object properties. This means that they present an interface to get and set a named-type for any type of object in a consistent way. (All the relevant functions to do this start with gtk_object_set or gtk_object_get).

- they describe signal arguments. This is a lot less often needed but still useful. Usually if you are just emitting or creating a particular signal it is more convenient to just use gtk_signal_emit() or gtk_signal_new(). However if you are writing a function to emit or create an arbitrary signal, you must use gtk_signal_emitv() or gtk_signal_newv().

## Details

### struct GtkArgInfo

    struct GtkArgInfo
    {
      /* hash key portion */
      GtkType class_type;
      gchar *name;

      GtkType type;
      guint arg_flags;
      gchar *full_name;

      /* private fields */
      guint arg_id;
      guint seq_id;
    };

A structure containing information about the argument. Returned by gtk_arg_get_info().

GtkType `class_type` | if the argument is an object, this is the object class type.
gchar *`name` | the name of the argument.
GtkType `type` | the type of the argument; it may be an object's type or a fundamental type.
guint `arg_flags` | flags applicable to the argument (i.e. readable, writable, and whether it needs to be constructed).
gchar *`full_name` | the object name and argument name separated by ::, e.g. "GtkObject::user_data" or "GtkButton::label".
guint `arg_id` | the unique argument identified.
guint `seq_id` | ???

### gtk_arg_new ()

    GtkArg*     gtk_arg_new                     (GtkType arg_type);

Creates a new argument of a certain type, set to 0 or NULL.

`arg_type` : | the type of the argument.
Returns : | the newly created GtkArg.

### gtk_arg_copy ()

    GtkArg*     gtk_arg_copy                    (GtkArg *src_arg,
                                                 GtkArg *dest_arg);

It will either copy data into an existing argument or allocate a new argument and copy the data. Strings are duplicated. All other pointers and values are copied (shallowly-- that is the pointers themselves are copied, not the data they point to.)

You should call gtk_arg_reset() on dest_arg before calling this if the argument may contain string data that you want freed.

`src_arg` : | the argument to duplicate.
`dest_arg` : | the argument to copy over (or NULL to create a new GtkArg).
Returns : | the new GtkArg (or dest_arg, if it was not NULL).

### gtk_arg_free ()

    void        gtk_arg_free                    (GtkArg *arg,
                                                 gboolean free_contents);

Frees the argument, and optionally its contents.

`arg` : | the argument to free.
`free_contents` : | whether to free the string, if it is a string.

### gtk_args_collect ()

    gchar*      gtk_args_collect                (GtkType object_type,
                                                 GHashTable *arg_info_hash_table,
                                                 GSList **arg_list_p,
                                                 GSList **info_list_p,
                                                 const gchar *first_arg_name,
                                                 va_list var_args);

Private: given a hashtable of argument information it takes a vararg list and parses it into arguments (in the form of lists of GtkArgs and lists of GtkArgInfos.

The list of arguments starts with first_arg_name then the first argument's value. Followed by any number of additional name/argument pairs, terminated with NULL.

`object_type` : | the type of object we are collecting arguments for.
`arg_info_hash_table` : | a hashtable mapping from names of arguments to their GtkArgInfos.
`arg_list_p` : | a returned list of arguments obtained from parsing the varargs.
`info_list_p` : | a returned list of the GtkArgInfos.
`first_arg_name` : | the name of the first argument.
`var_args` : | a va_list containing the value of the first argument, followed by name/value pairs, followed by NULL.
Returns : | an error message on failure, or NULL otherwise.

### gtk_args_collect_cleanup ()

    void        gtk_args_collect_cleanup        (GSList *arg_list,
                                                 GSList *info_list);

Private: erase lists of arguments returned from gtk_args_collect().

`arg_list` : | arg_list_p returned from gtk_args_collect().
`info_list` : | info_list_p returned from gtk_args_collect().

### gtk_arg_get_info ()

    gchar*      gtk_arg_get_info                (GtkType object_type,
                                                 GHashTable *arg_info_hash_table,
                                                 const gchar *arg_name,
                                                 GtkArgInfo **info_p);

Private: get information about an argument.

`object_type` : | the type of object.
`arg_info_hash_table` : | the hashtable of GtkArgInfos.
`arg_name` : | the name of the argument to lookup.
`info_p` : | the argument info.
Returns : | an error message on failure, or NULL otherwise.

### gtk_arg_type_new_static ()

    GtkArgInfo* gtk_arg_type_new_static         (GtkType base_class_type,
                                                 const gchar *arg_name,
                                                 guint class_n_args_offset,
                                                 GHashTable *arg_info_hash_table,
                                                 GtkType arg_type,
                                                 guint arg_flags,
                                                 guint arg_id);

Create a new argument registered with a class.

`base_class_type` : | the basic type having the arguments, almost alway GTK_TYPE_OBJECT, except if your defining a different type argument that gets a different namespace. GtkContainer does this to define per-child arguments of the container.
`arg_name` : | name of the argument to create. (must be a static constant string)
`class_n_args_offset` : | offset into the base class structure that tells the number of arguments.
`arg_info_hash_table` : | hashtable of GtkArgInfos.
`arg_type` : | type of the argument.
`arg_flags` : | flags of the argument.
`arg_id` : | ???
Returns : | the new GtkArgInfo.

### gtk_args_query ()

    GtkArg*     gtk_args_query                  (GtkType class_type,
                                                 GHashTable *arg_info_hash_table,
                                                 guint32 **arg_flags,
                                                 guint *n_args_p);

Private: from a class type and its arginfo hashtable, get an array of GtkArgs that this object accepts.

`class_type` : | the class type.
`arg_info_hash_table` : | the hashtable of GtkArgInfos.
`arg_flags` : | returned array of argument flags.
`n_args_p` : | the number of arguments this object accepts.
Returns : | the array of arguments (or NULL on error).

### gtk_arg_name_strip_type ()

    gchar*      gtk_arg_name_strip_type         (const gchar *arg_name);

Given a fully qualified argument name (e.g. "GtkButton::label") it returns just the argument name (e.g. "label") unless the argument name was invalid, in which case it returns NULL.

`arg_name` : | the fully-qualified argument name.
Returns : | the base argument name.

### gtk_arg_info_equal ()

    gint        gtk_arg_info_equal              (gconstpointer arg_info_1,
                                                 gconstpointer arg_info_2);

A GCompareFunc for hashing GtkArgInfos.

`arg_info_1` : | a GtkArgInfo.
`arg_info_2` : | a GtkArgInfo.
Returns : | whether the arguments are the same.

### gtk_arg_info_hash ()

    guint       gtk_arg_info_hash               (gconstpointer arg_info);

A GHashFunc for hashing GtkArgInfos.

`arg_info` : | a GtkArgInfo.
Returns : | a hash value for that GtkArgInfo.

## See Also

GtkObject.

<<< Previous Page | Home | Up | Next Page >>>
Signal Marshallers | Types