X-Git-Url: http://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/c190a2ae41238682c1430b8482683b6a7c15c66b:/doc/USER_GUIDE..b9f22ab5a7f4d4bfe0932debf8864a21b5c852cd:/doc/static/gitweb/git-favicon.png diff --git a/doc/USER_GUIDE b/doc/USER_GUIDE deleted file mode 100644 index 52ca71e..0000000 --- a/doc/USER_GUIDE +++ /dev/null @@ -1,211 +0,0 @@ -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 from { }". -For example: - -class Gtk:New:Button from Gtk:Button { - -} - -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 ':' - -or - (check ) - -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, " " 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 " ()". 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; -}