GTK+ Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
#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); |
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().
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 | ??? |
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. |
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.
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. |
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. |
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(). |
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. |
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. |
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). |
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. |
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. |
guint gtk_arg_info_hash (gconstpointer arg_info); |
A GHashFunc for hashing GtkArgInfos.
arg_info : | a GtkArgInfo. |
Returns : | a hash value for that GtkArgInfo. |