+++ /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.90.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 similar 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 or set 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 "self" 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 { self->height = ARG; } get { ARG = self->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 = self->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 "self",
-which gob will translate into a pointer to the object instance. The rest
-of the arguments are very similar 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
-numeric arguments for being a certain value. The test can be a <,>,<=,>=
-!= or ==. Example:
-.nf
-
- public int foo(self, int h (check > 0 < 11), Gtk:Widget *w (check null type))
-
-.fi
-.PP
-This will be the prototype of a function which has a self 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(self, 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 "virtual" keyword before the
-prototype. If you put the keyword "private" right after the "virtual"
-keyword, the wrapper will not be a public method, but a private one.
-.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 "self" pointer (not including the
-"self" 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 just like a public method. Example:
-.nf
-
- signal first INT(POINTER,INT)
- int do_something(self, Gtk:Widget *w (check null type), int length)
- {
- ...
- }
-
-or
-
- signal last NONE(NONE) void foo(self);
-
-.fi
-.PP
-If you don't want the wrapper that emits the signal to be public, you can
-include the keyword "private" after the "signal" keyword. This will make
-the wrapper a normal private method.
-.PP
-If you don't define a "first" or a "last", the default will be taken as
-"last".
-.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 "self" 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 *self (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(self)
- {
- return self->len;
- }
-
- private int
- bar(self,int i)
- {
- return foo(self) + i;
- }
-
-.fi
-.PP
-Making new objects:
-.PP
-You should define a new method which should be a normal public method. Inside
-this method, you can use the GET_NEW macro that is defined for you and that
-will fetch a new object, so a fairly standard new method would look like:
-.nf
-
- public GtkWidget *
- new(void) {
- GtkObject *ret;
- ret = GTK_OBJECT (GET_NEW);
- return ret;
- }
-
-.fi
-
-.SH BUGS
-.PP
-The generated header file is included as the first file in the .c file, no
-matter what. This means that you will have to put things that need to be
-included before that, into an %h{ } section.
-
-.SH AUTHOR
-.PP
-George Lebl <jirka@5z.com>
projects / gob-dx.git / blobdiff