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+:

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_typeif the argument is an object, this is the object class type.
gchar *namethe name of the argument.
GtkType typethe type of the argument; it may be an object's type or a fundamental type.
guint arg_flagsflags applicable to the argument (i.e. readable, writable, and whether it needs to be constructed).
gchar *full_namethe object name and argument name separated by ::, e.g. "GtkObject::user_data" or "GtkButton::label".
guint arg_idthe 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.