Proposal: GUBIs gtk.def

[Tim Janik <Tim Janik Hamburg Netsurf DE>]

hi folks,

within the last few days i exchanged quite some ideas with marius vollmer
about GUBIs gtk.defs format. within this process marius suggested to use
this format as a general gtk+ interface description, which is why i'm
drafting this proposal to which he has been a great help in creation.
my main intention was driven by the fact that i figured i would need much
deeper and precise information about the gtk+ interface then what is currently
provided by GUBIs hardcoded widget knowledge or the guile-gtk gtk.defs file,
if i ever want to have a chance to support multiple target languages close to
their fullest extends.

the main stubs are:

-	function definitions now consist of the library-domain,
	the operation-symbol and a method name like
	gtk widget set-uposition
	instead of the old
	gtk-widget-set-uposition
	because this didn't provide enough information to build oo-stubs.
	function arguments are grouped together now (through another
	perenthesis level) and are flagged to be of type `in', `out' or
	`inout'.
-	object definitions can have a creator function assigned now, and the
	old `fields' part inside the object definitons (which used to be
	merely a hack anyway) will be replaced by a `slot' defintion.
-	slots consist of a type/name pair that can have optional default
	values (main use: interface builders) followed by an optional
	action description.
-	actions are of a specified type (type currently consists of one out of
	{accessor|mutator|activator|deactivator}), a function portion and
	its calling parameter descriptions. hereby parameter can be a
	constant value (e.g. -1) a reference to the object the slot referes to,
	named `this' or a reference to the slot itself indicated by the
	slots name.
-	function grouping. functions can be put into groups which is usefull
	for locical separation along lines like `creation', `linkage',
	`configuration', `connection', `misc', etc...
-	library domain hints. library domains should be defined preceeding
	to the function deinitions and can contain informations like
	neccessary include files or linkage dependencies on other libraries.
-	descriptions: these consist of the keyword `description' followed
	by strings which will be concatenated in the glue building process.
	descriptions are optional on every single item.

concerning the slots i'd like to translate a simple example i gave to marius
explaining the neccessity of expressing widget parameters besides the
additional arguments that could be figured from their corresponding
`configure' functions:

> das problem ist, das dieser per-widget-parameter die funktions argumente
> pro widget unterscheiden soll, die fuer das gleiche widget gleich aussehen
> koennten. beispiel, ich habe zwei C funktionen:
the problem is, that this per-widget-parameter [slot] should distinct between
those function arguments that could look similar (on a per widget basis).
as an example, here are two C functions:

> void gtk_window_set_title (GtkWindow *window, gchar *title);
> void gtk_window_set_icon_title (GtkWindow *window, gchar *title);

> wenn ich nun ein generische eingabe fuer widget specifische parameter
> bastel, dann wuerde sie ungefaehr so aussehen:
if i'm going to create a generic input dialog for widget specific parameters
it would look like this:

> Widget Name:    | MyWindow      |
> Title:          | MyWindowTitle |
> Title:          | MyIconTitle   |

> und sonst koennte man diese namen halt gut unterscheiden:
otherwise [having the seperation through slots] the parameters are easily
to distinguish:

> Widget Name:    | MyWindow      |
> Title:          | MyWindowTitle |
> Icon Title:     | MyIconTitle   |

> im prinzip soll es nur moeglich sein saemtlichen widget-specifischen
> parametern einen eindeutigen (sinnvollen) namen zu zuordnen.
basically, it should just be possible to assign each widget specific parameter
an own, unique and suggestive name.


i think in general you should have got the idea by now ;)
so, the new format mainly features oo and GUI builders and as an aside
it's predestinated to produce (reference) documantation with any grouping
you might find appropriate.
i'd like to see a function browser based on this (somewhen in the future)
just like the DB Browser of the Gimp.



please note that nothing of this is stone graved at the moment and your
comments, suggestions and criticism is more than apprechiated.


now, here comes a sample portion of what i'd like GUBIs new gtk.defs file
to look like:


; -*- gnome-rc -*-

(define-domain	glib
  (globally-include	"glib.h")
  (libraries		"glib" "m"))

(define-domain	gdk
  (globally-include	"gdk/gdk.h")
  (libraries		"gdk" "glib" "X11" "Xext" "m"))

(define-domain	gtk
  (description		"Gtk+ - The GIMP Toolkit")
  (globally-include	"gtk/gtk.h")
  (libraries		"gdk" "gdk" "glib" "X11" "Xext" "m"))

; LIBRARY-DOMAIN-DEFINITION:
; (define-domain DOMAIN-NAME [DESCRIPTION] [G-INCLUDES] [L-INCLUDES] [LIBRARIES] )
;
; DESCRIPTION:
; (description [STRING...] )
; multiple STRINGs will get concatenated
;
; G-INCLUDES:
; (globally-include [STRING...] )
;
; L-INCLUDES:
; (locally-include [STRING...] )
;
; LIBRARIES:
; (libraries [STRING...] )
;
;; the library domain must be defined before any function definition
;; refers to this domain

(define-object GtkWidget (GtkObject)
  (slots
    (GtkWidget	widget)
    (bool	focus-grab	0
      (activator	gtk-widget-grab-focus this))
    (gint	x	-2
      (mutator	gtk-widget-set-uposition this  x -2))
    (gint	y	-2
      (mutator	gtk-widget-set-uposition this -2 y))))

(define-object GtkContainer (GtkWidget)
  (slots
    (int	border-width	0
      (mutator	gtk-container-border-width this border-width))))

(define-object GtkWindow (GtkBin)
  (slots
    (string title
      (mutator	gtk-window-set-title this title))
    (string icon_title
      (mutator	gtk-window-set-icon-title this icon_title)))
  (creator gtk-window-new))

; OBJECT-DEFINITION:
; (define-object TYPE-NAME (PARENT-TYPE) [DESCRIPTION]
; [SLOTS] [CREATOR] )
;
;; the PARENT-TYPE has to be defined already
;
; DESCRIPTION:
; (description [STRING...] )
; multiple STRINGs will get concatenated
;
; CREATOR:
; (creator FUNCTION-NAME)
;
; SLOTS:
; (slots [(SLOT-DEFINITION)...] )
;
; SLOT-DEFINITION:
; (TYPE SLOT-NAME [DEFAULT-VALUE] [DESCRIPTION] [ACTION-DEFINITION] )
;
; ACTION-DEFINITION:
; (ACTION-TYPE FUNCTION-NAME [PARAMETER-NAMES...] )
;
; ACTION-TYPE:
; {accessor|mutator|activator|deactivator}

(define-function	gtk widget grab-focus
  (description
    "this function is used to grab the focus for"
    "a widget. the widget needs to be flagged with CAN_FOCUS.")
  (returns      none)
  (arguments
    (in GtkWidget	widget)))

; FUNCTION-DEFINITION:
; (define-function DOMAIN OPERATION-SYMBOL METHOD [DESCRIPTION]
;   [RETURNS] [ARGUMENTS] )
;
; DESCRIPTION:
; (description [STRING...] )
; multiple STRINGs will get concatenated
;
; RETURNS:
; (returns TYPE)
;
; ARGUMENTS:
; (arguments [ARG...] )
;
; ARG:
; (ARG-TYPE TYPE NAME)
;
; ARG-TYPE:
; {in|out|inout}


(define-function	gtk widget set-name
  (description
    "this function is used to set a widgets name for"
    "further references.")
  (returns      none)
  (arguments
    (in GtkWidget	widget)
    (in string		name)))

(function-group-set	configure
  gtk-widget-set-name
  gtk-widget-grab-focus)

(function-group-set	creators
  gtk-window-new)

; FUNCTION-GROUPING:
; (function-group-set GROUP-NAME [DESCRIPTION] [FUNCTION-NAME...] )
;
; DESCRIPTION:
; (description [STRING...] )
; multiple STRINGs will get concatenated
;
; GROUP-NAME:
; any identifier you might find appropriate...
;


---
ciaoTJ