gobm4 [ options ] file ... file
Gobm4 is a preprocessor (more strictly, a set of preprocessor macros)
for use with gob, the GTK+ Object Builder. This manual page describes
how to invoke gobm4 to turn .gob.m4 source files into processed C
source. It also describes how to write Gtk+ objects using gobm4. It
is assumed that the reader is familiar with the use of gob itself (if
you are not, please see the gob man page).
| --usage | Display usage information. |
| --version | Display version information. |
| --make-gob | Create a preprocessed .gob file |
| --make-gob-stdout | Create a preprocessed .gob file on stdout. |
| --make-c | Invoke gob to create C output. (This behaviour is the default). |
| --gob-supports-m4 | Assume that gob supports the --m4 option. |
| --gob=GOB | Use GOB as the command to invoke gob. |
| --verbose | Display commandlines used when gob or m4 are invoked. |
| --gobm4dir | Display the system directory searched for gobm4 modules. |
| --prefix | Display the prefix under which gobm4 was installed. |
Other options will be passed through to gob.
The --gob-* and --make-* options may be preceded by "no"
(e.g. --nomake-c) to negate their effect. This is useful with
--make-c, which is on by default, and the --gob-* options, whose
default settings are determined by gob's behaviour when gobm4 was
configured. The --make-* options are independent: all or none may be
used in any one run of gobm4.
You would normally invoke gobm4 to transform a gobm4 source file (with
extension .gob.m4) into C source, ready to be compiled. Doing that is
very simple. "gobm4 foo-bar.gob.m4" will transform foo-bar.gob.m4
into foo-bar.c, foo-bar.h and foo-bar-private.h.
You might also need to use --make-gob if you are trying to debug
extensions that you have made to gobm4. "gobm4 foo-bar.gob.m4" will
transform foo-bar.gob.m4 into foo-bar.c, foo-bar.h, foo-bar-private.h,
and foo-bar.gob. The .gob file is unnecessary, but it allows the user
to see what gobm4 has done to the source before submitting it to gob.
Gobm4 is also often invoked from a makefile created by automake. To
use gobm4 with automake, include the autoconf macro GOBM4_CHECK() in
your project's configure.in. If you are using features not present in
all versions of gobm4, you can use GOBM4_CHECK(<ver>) to check for
gobm4 version at least <ver>. If gobm4 is installed, GOBM4_CHECK()
fills in the autoconf substitution GOBM4 with the path to gobm4, and
sets the environment variable gobm4_installed to "yes". Because gobm4
should not be required for projects to build, it is best to use an
automake conditional to generate an appropriate rule for make only if
gobm4 is found. Thus:
in configure.in... GOBM4_CHECK(0.1.2) AM_CONDITIONAL(HAVE_GOBM4,[test x$gobm4_install = xyes]) and in the relevant Makefile.am... if HAVE_GOBM4 %.c %.h : %.gob.m4 $(GOBM4) $< endif |
If you know how to write a Gtk+ object using gob, then you already
know how to write one using gobm4. The m4 stage of gobm4's
preprocessing will pass through any text it doesn't recognise
(anything apart from m4 and gobm4 macros, that is) so any valid gob
source file is a valid gobm4 source file.
To begin using gobm4 macros, you first need to request that gobm4
include the gobm4 module that supplies the macros you want to use.
This is done with the GOBM4_REQUIRE() macro. Here is an example of
its use, from the first four lines of the source file glue-model.gob.m4:
GOBM4_REQUIRE(class)
GOBM4_REQUIRE(method)
CLASS(Glue:Model from Gtk:Object) {
|
The CLASS macro can also be called GOBM4_CLASS. In fact CLASS is just
an alias for GOBM4_CLASS - some of the most frequently used gobm4
macros have such aliases (for ease of typing and to improve
readability). Because macros that don't begin with GOBM4_ could
interfere with symbols defined in other libraries, you can switch the
aliases off by defining the symbol GOBM4_NAMESPACE_PARANOIA (by
invoking gobm4 with the option -DGOBM4_NAMESPACE_PARANOIA, that is).
One of the most convenient features of gobm4 is the ability to easily
define gtk arguments with associated data members (or, for convenient
reference, "properties"). Here is an example:
GOBM4_REQUIRE(class)
GOBM4_REQUIRE(property)
CLASS(Foo:Bar from Gtk:Object) {
PROPERTY(protected STRING title = "untitled");
PROPERTY(protected OBJECT mailbox);
PROPERTY(private UINT popup_timeout=20);
}
|
Why would you do all this rather than just using a data member?
First, it makes interpreted language bindings easier. Second, it
makes object construction easier - you can create your objects simply
by calling gtk_object_new() (rather than having to create your own
foo_bar_new() function). And third, it allows your objects to be
saved and reloaded by the generic method of introspecting the object's
properties, then re-creating the object with gtk_object_new() (libglue
is a library that provides this, and other, features).
An advantage of gobm4's PROPERTY macro over the existing gob "link", "objectlink", and "stringlink" keywords is that it is extensible. You
can easily add new types with new copying and referencing rules. For
example, here is the definition of the PIXBUF type (from types.m4) and
a FILENAME type (from libglue):
m4_define(`PIXBUF-TYPE',`GdkPixbuf *')
m4_define(`PIXBUF-GTYPE',`POINTER')
m4_define(`PIXBUF-DEFAULT',`NULL')
m4_define(`PIXBUF-INIT',`GOBM4_ERROR(Pixbuf members may not be initialised)')
m4_define(`PIXBUF-UNREF',`if($1) gdk_pixbuf_unref($1)')
m4_define(`PIXBUF-REF',`gdk_pixbuf_ref($1)')
m4_define(`FILENAME-TYPE',`gchar *')
m4_define(`FILENAME-GTYPE',`STRING')
m4_define(`FILENAME-DEFAULT',`g_strdup("")')
m4_define(`FILENAME-INIT',`glue_path_strdup($1)')
m4_define(`FILENAME-UNREF',`if($1) g_free($1)')
m4_define(`FILENAME-COPY',`glue_path_strdup($1)')
|
If the UNREF, REF, and COPY macros are not defined, then gobm4 assumes
that the type is a straightforward scalar type with no reference
counting (a type such as INT). If UNREF is defined, then gobm4 will
use it to dispose of properties of this type when they are no longer
being used. If COPY is defined, then gobm4 will use it to make copies
of properties that cannot be reference counted (such as STRINGs). If
REF is defined, then gobm4 uses it to perform full reference counting
on properties of this type (as will be done for OBJECTs and PIXBUFs).
Gobm4 provides macros that can be used to define methods, virtual
methods and signals, in the "method" module. Here are some examples
(the function bodies have been removed):
SIGNAL(first NONE(INT)
void checked(self,BiffMailboxStatus status))
{
...
}
SIGNAL(private (NO_RECURSE) NONE(NONE) void start_check(self));
METHOD(void add_client(self,Wm:Client *client (check type null)))
{
...
}
VIRTUAL(GtkWidget *get_outer(self));
|
OVERRIDE is used when defining a new class to override a superclass's
virtual methods, or default signal handlers. It takes just one
argument, which is the name of the method to override. So, for
example:
GOBM4_REQUIRE(method)
GOBM4_REQUIRE(gtk)
OVERRIDE(Gtk:Object::shutdown) {
my_clean_up(SELF(object));
GOBM4_PARENT_HANDLER();
}
|
HANDLER is used to create a function that matches the signature of a
user signal handler for some signal. For example:
GOBM4_REQUIRE(method)
GOBM4_REQUIRE(gtk)
HANDLER(Gtk:Widget::parent_set parent_set_handler)
{
Self *self=SELF(user_data);
/* sanity check */
g_assert(widget==self->socket);
...
}
METHOD(void foo(self))
{
gtk_signal_connect_after(GTK_OBJECT(self->socket),
"parent_set",
(GtkSignalFunc)parent_set_handler,
self);
}
|
In the examples above, we've overridden virtual methods and signals
defined by gtk. gobm4 knows the prototypes of all gtk virtual methods
and signals automatically. They are contained in the module "gtk".
gobm4 will try to obtain other prototypes from the gobm4 sources for
the relevant class, searching the normal gobm4 search path (which can
be modified using the -I commandline option).
If gnome-libs were installed when gobm4 was configured, gobm4 will
also know the prototypes of all the gnomeui virtual methods and
signals (contained in the module "gnome"). If you want to use the
OVERRIDE / HANDLER mechanism with other gnome components (such as
libapplet or libcapplet) you can use the GOBM4_PROCESS_HEADER_GNOME()
macro (see below).
The remainder of this manual page documents in detail the gobm4
modules that are distributed with gobm4. This documentation has been
extracted from comments in the module source code, and is not at this
stage complete.
module control
| GOBM4_PUSHDIV (number) | diverts to the diversion numbered number, saving the old diversion number in GOBM4_OLD_DIVNUM |
| GOBM4_ERROR (description) | die, printing input file, line number and description |
| GOBM4_MODULE (name, version, description) | declare a module named name |
| GOBM4_MODULE_VERSION (modulename) | expands to the version of module modulename |
| GOBM4_MODULE_DESCRIPTION (modulename) | expands to the description of module modulename |
| GOBM4_INCLUDE (module) | include a gobm4 module, forcibly |
| GOBM4_REQUIRE (module,version) | include a gobm4 module if it has not been included already, and if it is newer than version, and if it has the same major version number as version |
| GOBM4_QUICKNAME (macroname) | copy the definition of GOBM4_macroname to macroname, only if GOBM4_NAMESPACE_PARANOIA is not defined |
Defines macros for CPP-like conditional compilation.
| GOBM4_IF (a,b) | If a and b match, has no effect, otherwise causes all gob source code to be ignored until the next GOBM4_ELSE or GOBM4_ENDIF. |
| GOBM4_ENDIF () |
| GOBM4_ELSE () |
| GOBM4_IFDEF (<token>) | Like GOBM4_IF, but tests whether token is a defined gobm4 symbol. Note that this macro cannot test whether a token is defined by gob, C, or gtk. |
macros to help with defining classes
| GOBM4_BASE_OBJECT () | Expands to the gob typename of the fundamental object type. At present, this will be either Gtk:Object or G:Object depending on the version of gob. |
| BASE_OBJECT | An alias for GOBM4_BASE_OBJECT |
| GOBM4__CLASS (class,parent) | Declare a class. class and parent should be valid gob class names (e.g. Foo:Bar, Gtk:Object). If parent is omitted, class will be made a subclass of the most fundamental object type. |
| GOBM4_CLASS (gobtext) | Declare a class. gobtext should be of the form "Foo:Bar from Some:Object". Using GOBM4_CLASS will allow gobm4 macros to retrieve the name of the class currently being defined (and its parent's name). This is just a sugar-coated wrapper for GOBM4__CLASS() |
| CLASS | An alias for GOBM4_CLASS |
store and expand function prototypes
| GOBM4_PROTO () |
| GOBM4_PROTO_USE (class) | Like GOBM4_PROTO_INCLUDE, except that if we already have prototypes corresponding to class, do nothing. |
| GOBM4_PROTO_EXPAND (name) | if name is the name of a method, virtual method, or signal that we know about, expand to a complete prototype for name |
| GOBM4__PROTO (name,prototype) | save prototype as the prototype corresponding to name |
methods, signals and virtuals
| GOBM4_PARENT_HANDLER () | passing arguments automatically |
| GOBM4__OVERRIDE (class,method) | a correct declaration is automatically generated |
| OVERRIDE | An alias for GOBM4_OVERRIDE |
| GOBM4__HANDLER (protection,class,method,name) | generate a declaration of a user signal handler for method of class |
| HANDLER | An alias for GOBM4_HANDLER |
| GOBM4__SIGNAL (protection,signal-flags,first|last,marshall-spec,prototype) |
| SIGNAL | An alias for GOBM4_SIGNAL |
| GOBM4__METHOD (protection,prototype) |
| METHOD | An alias for GOBM4_METHOD |
| GOBM4__VIRTUAL (protection,prototype) |
| VIRTUAL | An alias for GOBM4_VIRTUAL |
Defines standard types for use with the property module.
| GOBM4_COPY (type,expression) | Expands to a C expression returning a copy of expression expression must be of type type. If type implements reference counting, that will be used instead of copying. |
This module includes gtk or gtk2 depending on whether gobm4 is being used with gob / gtk+ version 1 or 2. It also defines GOBM4_HAVE_GOBJECT if compiling with gob 2.
data members and linked arguments
| GOBM4_ACCESSOR (protection,member) | expands to a self-> expression for accessing member |
| GOBM4_INITIALISER (type,c-code) | expands to a gob initialiser. e.g. INITIALISER(STRING,"foo") expands to ={g_strdup("foo")} |
| GOBM4_DESTRUCTOR (protection,type,member) | expands to a gob destructor for the data member member e.g. DESTRUCTOR(public,STRING,foo) expands to destroywith g_free |
| GOBM4_DATA_MEMBER (protection,type,member,initialiser) | expands to a gob data member declaration complete with initialiser and destructor |
| GOBM4_ARGUMENT_GET (protection,type,argflags,member) | expands to the body of the "get" part of a gob argument decl |
| GOBM4_ARGUMENT_SET (protection,type,argflags,member) | expands to the body of the "set" part of a gob argument decl |
| GOBM4_ARGUMENT (protection,type,argflags,member) | expands to a gob argument declaration linked to member |
| GOBM4__PROPERTY (protection,type,argflags,member,initialiser) | expands to a gob data member declaration and linked argument declaration |
| PROPERTY | An alias for GOBM4_PROPERTY |
This module overrides the GOBM4_ARGUMENT macro from module property, and causes it to generate a set_<argumentname> method for each argument declared with GOBM4_ARGUMENT (and thus, indirectly, for each argument declared with GOBM4_PROPERTY). This is useful if you need an efficient way to set arguments (more efficient than calling gtk_object_set, that is).
| GOBM4_ARGUMENT (protection,type,argflags,member) | Expands to a gob argument declaration linked to member. |
Josh Parsons <josh@philosophy.org.au>