--- /dev/null
+.\"
+.\" gob manual page
+.\" (C) 1999 George Lebl <jirka@5z.com>
+.\"
+.\" This manual page is covered by the terms of the GNU General
+.\" Public License.
+.\"
+.TH GOB 1 "GOB 0.0.2"
+.SH NAME
+GOB \- The GTK+ Object Builder
+.SH SYNOPSIS
+.PP
+.B gob
+.SH DESCRIPTION
+.PP
+GTK+ Object Builder is a simple preprocessor for easily creating
+GTK+ objects. It does not parse any C code and ignores any C errors. It
+is in spirit similiar to things like lex or yacc.
+.SH TYPENAMES
+.PP
+Because we need to parse out different parts of the typename,
+sometimes you need to specify the typename with some special syntax.
+Types are specified in capitalized form and words are separated by ':'.
+The first word of the type (which can be empty) is the "namespace". This
+fact is for example used for the type checking macro. For "Gtk:New:Button",
+the macro will be GTK_IS_NEW_BUTTON. This format of typenames is used in
+the class declaration header and for method argument types.
+
+.SH OUTPUT FILE NAMES
+.PP
+The filenames are created from the typename. The words are
+separated by '-' and all in lower case. For example for an object named
+"Gtk:New:Button", the files are gtk-new-button.c and gtk-new-button.h.
+
+.SH INCLUDING NORMAL C CODE IN THE OUTPUT FILES
+.PP
+To include some code directly in the output C file begin with
+'%{' on an empty line and end the code with a '%{' on an empty line. To
+put the code in the output header file, start the code with a '%h{'.
+For example:
+.nf
+
+ %h{
+ void somefunc(int i);
+ %}
+ %{
+ void somefunc(int i)
+ {
+ /* some code */
+ }
+ %}
+
+.fi
+.SH MAKING A NEW CLASS
+.PP
+The class header:
+.PP
+There can be only one class per input file. Defining a class
+is sort of like in Java, you define the class and write inline code
+directly into the class definition. To define a class you need to specify
+the new object name and the name of the object from which it is derived
+from, such as this "class <new type> from <parent type> { <class code> }".
+For example:
+.nf
+
+ class Gtk:New:Button from Gtk:Button {
+ <class code>
+ }
+
+.fi
+.PP
+Data members:
+.PP
+There are three types of data members. Two of them are normal
+data numbers, and one is a virtual one, usually linked to a normal public
+data member. The two normal data members are public or private. They are
+basically just copied into the object directly. There is only one
+identifier allowed per typename unlike in normal C. Example:
+.nf
+
+ public int i;
+ private GtkWidget *h;
+
+.fi
+.PP
+The private members are not currently protected from outside use,
+they are just marked by a comment in the header file, this will most likely
+be somehow solved in some future version.
+.PP
+The third type is an argument type. It is a named datamember which
+is one of the features of the GTK+ object system. You need to define a get
+and a set handler. They are fragments of C code that will be used to
+get the value orset the value of the argument. Inside them you can use the
+define ARG to which you assign the data or get the data. You can also use
+the identifier "this" as pointer to the object instance. The type is
+defined as one of the gtk type enums, but without the GTK_TYPE_ prefix.
+For example:
+.nf
+
+ public int height;
+ argument INT height set { this->height = ARG; } get { ARG = this->height; };
+
+.fi
+.PP
+If you don't define a set or a get handler it will be a readonly
+or a writeonly argument. If you want to add extra argument flags, add
+them into parenthesis after the argument keyword, separated by '|' and
+without the GTK_ARG_ prefix. For example:
+.nf
+
+ public int height;
+ argument (CONSTRUCT) INT height get { ARG = this->height; };
+
+.fi
+.PP
+Methods:
+.PP
+There is a whole array of possible methods. The two normal,
+"familiar" method types are private and public. Public are defined as
+normal functions with a prototype in the header file. Private methods
+are defined as static functions with prototypes at the top of the .c
+file. Then there are signal, virtual and override methods. You can also
+define init and init_class methods with a special definition if you want
+to add code to the constructors or you can just leave them out.
+.PP
+Argument lists:
+.PP
+For all but the init and init_class methods, you use the
+following syntax for arguments. The first argument can be just "this",
+which gob will translateinto a pointer to the object instance. The rest
+of the arguments are very similiar to normal C arguments. If the
+typename is an object pointer you should use the syntax defined above
+with the words separated by ':'
+.nf
+<type> <argument id>
+or
+<type> <argument id> (check <list of checks>)
+.fi
+.PP
+The checks are glib type preconditions, and can be the following:
+"null", which tests pointers for being NULL, "type" which checks GTK+
+object pointers for being the right type, "<test> <number>" which tests
+numberic arguments for being a certain value. The test can be a <,>,<=,>=
+!= or ==. Example:
+.nf
+
+ public int foo(this, int h (check > 0 < 11), Gtk:Widget *w (check null type))
+
+.fi
+.PP
+This will be the prototype of a function which has a this pointer
+as the first argument, an integer argument which will be checked and has
+to be more then 0 and less then 11, and a pointer to a GtkWidget object
+instance and it is checked for being null and the type will also be
+checked.
+.PP
+Error return:
+.PP
+Methods which have a return value, there also has to be something
+returned if there is an error, such as if a precondition is not met. The
+default is 0, casted to the type of the method. If you need to return
+something else then you can specify an "onerror" keyword after the
+prototype and after that a number, a token (an identifier) or a bit of C
+code enclosed in braces {}. The braces will not be printed into the
+output, they just delimit the string. For example
+.nf
+
+ public void * get_something(this, int i (check >= 0)) onerror NULL {
+ ...
+ }
+
+.fi
+.PP
+Virtual methods:
+.PP
+Virtual methods are basically pointers in the class structure,
+so that one can override the method in derived methods. They can be empty
+(if you put ';' instead of the C code). A wrapper will also be defined
+which makes calling the methods he same as public methods. This type of
+method is just a little bit "slower" then normal functions, but not as
+slow as signals. You define them by using "virutal" keywrod before the
+prototype.
+.PP
+Signals:
+.PP
+Signals are methods to which the user can bind other handlers
+and override the default handler. The default handler is basically the
+method body. This is the most versatile and flexible type of a method
+and also the slowest. You need to specify a whole bunch of things when
+you define a signal. One thing is when the default handler will be run,
+first or last. You specify that by "first" or "last" right after the
+"signal" keyword. Then you need to define the gtk enum types (again
+without the GTK_TYPE_ prefix). For that you define the return types
+and the types of arguments after the "this" pointer (not including the
+"this" pointer). You put it in the following syntax "<return type> (<list
+of arguments>)". If the return type is void, the type should be "NONE",
+the same should be for the argument list. The rest of the prototype is
+the same as for other method types. The body can also be empty, and
+also there is a public method wrapper which you can use for calling the
+signal jus tlike a public method. Example:
+.nf
+
+ signal first INT(POINTER,INT)
+ int do_something(this, Gtk:Widget *w (check null type), int length)
+ {
+ ...
+ }
+
+or
+
+ signal last NONE(NONE) void foo(this);
+
+.fi
+.PP
+Override methods:
+.PP
+If you need to override some method (a signal or a virtual method
+of some class in the parent tree of the new object), you can define and
+override method. After the "override" keyword, you should put the
+typename of the class you are overriding a method from. Other then that
+it is the same as for other methods. The "this" pointer in this case
+should be the type of the method you are overriding so that you don't
+get warnings during compilation. Example:
+.nf
+
+ override (Gtk:Container) void
+ add (Gtk:Container *this (check null type), Gtk:Widget *wid (check null type))
+ {
+ ...
+ }
+.fi
+.PP
+Calling methods:
+.PP
+Inside the code, defines are set for the methods, so that you don't
+have to type the class name before each call. Example:
+.nf
+
+ private int
+ foo(this)
+ {
+ return this->len;
+ }
+
+ private int
+ bar(this,int i)
+ {
+ return foo(this) + i;
+ }
+.fi
+.SH BUGS
+.PP
+The generated header file is included as the first file in the .c file, no
+matter what. ths means that you willhave to putthings that need to be included
+before that, into an %h{ } section.
+.SH AUTHOR
+.PP
+George Lebl <jirka@5z.com>
projects / gob-dx.git / blobdiff