GOBM4 0.2.0 Manual page

NAME

GOBM4 -> Preprocessor for the GTK+ Object Builder

SYNOPSIS

gobm4 [ options ] file ... file

DESCRIPTION

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).

OPTIONS

--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.

INVOKING 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

Note that in practice you may need a more complicated make rule. For example you might want to use the --no-private-header option (which will be passed to gob) or the -I option (which will be passed to m4).

WRITING IN GOBM4

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) {

This source file defines the Glue:Model class, and requires two modules, class and method. The class module defines the CLASS macro, which you can see being used in the fourth line. This line could have been written "class Glue:Model from Gtk:Object {", but using the macro allows gobm4 to store the names of the class being defined and its parent for later use.

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).

PROPERTIES AND TYPES


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);
}

Objects of the class Foo:Bar will have three properties named title, mailbox, and popup_timeout. These properties will be accessible as data members (though popup_timeout is private, and will only be accessible to those C source files that include foo-bar-private.h). They will also automatically be accessible via gtk_object_get(), gtk_object_set(), and gtk_object_new(). In addition, mailbox and title will be correctly reference counted (or copied, in the case of title) when set by the gtk_object_set() function, and when the object is constructed or destroyed.

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)')

Note that these macros are not accessible directly (and thus cannot interfere with the C namespace) because they contain a hyphen, which is a non-letter character in m4. The part of the definition before the hyphen is always the name of the type being defined. When defining a new type, you must provide TYPE, GTYPE, DEFAULT, and INIT macros, which are the C type, the Gtk+ type (minus the "GTK_TYPE_" prefix), a default value for properties of this type if no initialiser was specified, and a macro that should expand to a suitable C initialiser (when given the initialiser specified to gobm4 as an argument).

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).

METHODS, OVERRIDES, AND HANDLERS


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));

The real advantage to using these macros is that they store the prototypes of the functions they declare for later use with the OVERRIDE and HANDLER macros.

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();
  }

In this case the method "shutdown" from the superclass "Gtk:Object" is being overridden. The OVERRIDE macro here will expand to "override (Gtk:Object)" followed by the prototype used for the shutdown method in the original definition of Gtk:Object (in gtkobject.h). The arguments, if any, passed to the method will have the same names they did in the prototype that is being copied (in this case, one of the arguments is called "object"). If any argument is called "self", it will be renamed as "_self", because gob treats "self" as a special argument name. Note also the use of GOBM4_PARENT_HANDLER(). This will call PARENT_HANDLER() (which is defined by gob) with the original arguments passed to the method.

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);
    }

As with OVERRIDE, the handler function will have its argument list constructed from argument list originally used when the signal in question was declared, with an additional argument named "user_data", of type gpointer added to the end of the list. If no protection type is specified the handler will default to being private.

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).

LIST OF GOBM4 MODULES AND MACROS


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 'gobm4' (version documented 0.1.0)

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

Module 'conditional' (version documented 0.1.0)

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.

Module 'class' (version documented 0.2.0)

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

Module 'proto' (version documented 0.1.1)

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

Module 'method' (version documented 0.1.0)

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

Module 'types' (version documented 0.3.0)

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.

Module 'gtkcompat' (version documented 0.1.1)

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.

Module 'property' (version documented 0.1.1)

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

Module 'property-set' (version documented 0.1.0)

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.





AUTHOR

Josh Parsons <josh@philosophy.org.au>