Runtime Linkage queries

[Tim Janik <timj gtk org>]

hi everyone,

user interface builders usually let you create complete guis through
creating and placing widgets/containers in other containers.
gtk implements a mechanism to query/set widget specific arguments to
control widget specific behaviour, but does not (yet) support a way
for runtime settings/adjustments of the way a container links in a
child.
i therefore would like the following things to be implemented:

- a way to query a container about the expected type of child
- a way to query the supported linkage arguments of a container
- a way to set these linkage arguments.

for the implementation side i'd like to see...

the GtkContainerClass extended to support the following methods:

struct _GtkContainerClass
{
  [...]
  
  void    (*get_linkage_arg)  (GtkContainer *container,
  			       GtkWidget    *child,
                               GtkArg       *arg,
                               guint         arg_id);
  void    (*set_linkage_arg)  (GtkContainer *container,
  			       GtkWidget    *child,
                               GtkArg       *arg,
                               guint         arg_id);
  
  GtkType (*next_child_slot)  (GtkContainer *container);
};

the following functions to be implemented on gtkcontainer basis:

GtkType gtk_container_next_child_slot (GtkContainer *container);

/* this function is similar to gtk_object_add_arg_type */
void    gtk_container_add_arg_type (GtkContainerClass *klass,
                                    const gchar       *arg_name,
                                    GtkType            arg_type,
                                    guint              arg_flags,
                                    guint              arg_id);

/* this function is similar to gtk_object_query_args */
GtkArg* gtk_container_query_args   (GtkContainer   *container,
				    guint32       **arg_flags,
				    guint          *nargs);

/* the following functions are in place to set/get the linkage
 * arguments through the newly introduced class methods
 */

/* this function is similar to gtk_object_getv */
void    gtk_container_linkage_getv    (GtkContainer *container,
				       GtkWidget    *child,
                                       guint         n_args,
				       GtkArg       *args);

/* this function is similar to gtk_object_setv */
void    gtk_container_linkage_setv    (GtkContainer *container,
				       GtkWidget    *child,
                                       guint         n_args,
				       GtkArg       *args);


/* this function is a combination of gtk_container_add and
 * gtk_container_linkage_setv, similar to the semantics of
 * gtk_object_new
 */
void    gtk_container_linkage_add     (GtkContainer *container,
				       GtkWidget    *child,
				       ...);

/* this function is a combination of gtk_container_add and
 * gtk_container_linkage_setv, similar to the semantics of
 * gtk_object_newv
 */
void    gtk_container_linkage_addv    (GtkContainer *container,
				       GtkWidget    *child,
                                       guint         n_args,
				       GtkArg       *args);


the gtk_container_next_child_slot() will return the expected base type
of new children.
examples:
a GtkWindow would return GTK_TYPE_WIDGET if it doesn't yet have a child,
and GTK_TYPE_NONE otherwise (since it is derived from GtkBin it can hold
one child at maximum).
a GtkBox would always return GTK_TYPE_WIDGET, since it can hold an unlimited
amount of children.
a GtkList would always return GTK_TYPE_LIST_ITEM, since that is the minimum
base class a list's children have to be derived from, and a GtkList can hold
an unlimited amount of children as well.
a GtkPaned would return GTK_TYPE_WIDGET as long as one of its two child slots
is unallocated.

basically, the linkage argument functions operate similar to the object
argument mechanism, they just have an extra child widget specified.
e.g. a GtkBox will introduce the following linkage arguments:

GtkBox::expand  bool
GtkBox::fill    bool
GtkBox::padding int

the usage of linkage arguments is actually straight forward, once one
got familiar with the object argument mechanism. a small example prog:

GtkWidget *box;
GtkWidget *label;
GtkWidget *window;

gtk_init (NULL, NULL);

window = gtk_window_new (GTK_WINDOW_TOPLEVEL);

box = gtk_widget_new (GTK_TYPE_BOX,
                      "GtkBox::homogenous", TRUE,
                      "GtkWidget::visible", TRUE,
                      "GtkWidget::parent", window,
		      NULL);
label = gtk_widget_new (GTK_TYPE_LABEL,
			"GtkWidget::visible", TRUE,
			"GtkLabel::label", "yeppers",
			NULL);
gtk_container_linkage_add (box,
                           label,
                           "GtkBox::expand", TRUE,
                           "GtkBox::fill", TRUE,
                           "GtkBox::padding", 4,
                           NULL);
gtk_widget_show (window);
gtk_main ();


i'm curious about people's comments, especially damon's ;)

---
ciaoTJ