+++ /dev/null
-GTK+ Object Builder
-
-AUTHOR: George Lebl
-
- 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.
-
-Typenames:
-
- 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.
-
-The output file names:
-
- 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.
-
-Including normal C code in the output files:
-
- 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:
-
-%h{
-void somefunc(int i);
-%}
-%{
-void somefunc(int i)
-{
- /* some code */
-}
-%}
-
-Making a new class:
-
-The class header:
-
- 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:
-
-class Gtk:New:Button from Gtk:Button {
- <class code>
-}
-
-Data members:
-
- 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:
-
-public int i;
-private GtkWidget *h;
-
- 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.
-
- 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:
-
-public int height;
-argument INT height set { this->height = ARG; } get { ARG = this->height; };
-
- 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:
-
-public int height;
-argument (CONSTRUCT) INT height get { ARG = this->height; };
-
-Methods:
-
- 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.
-
-Argument lists:
-
- 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 ':'
-<type> <argument id>
-or
-<type> <argument id> (check <list of checks>)
-
-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:
-
-public int foo(this, int h (check > 0 < 11), Gtk:Widget *w (check null type))
-
- 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.
-
-Error return:
-
- 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
-
-public void * get_something(this, int i (check >= 0)) onerror NULL {
- ...
-}
-
-Virtual methods:
-
- 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.
-
-Signals:
-
- 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:
-
-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);
-
-Override methods:
-
- 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:
-
-override (Gtk:Container) void
-add (Gtk:Container *this (check null type), Gtk:Widget *wid (check null type))
-{
- ...
-}
-
-Calling methods:
-
- Inside the code, defines are set for the methods, so that you don't
-have to type the class name before each call. Example:
-
-private int
-foo(this)
-{
- return this->len;
-}
-
-private int
-bar(this,int i)
-{
- return foo(this) + i;
-}
projects / gob-dx.git / blobdiff
