GenGui V1.0 =========== ©1994 by Matthias Meixner Read the README file for the legal issues This package is for layout and creation of graphical user interfaces (GUI). Unlike some other programs like Gadtools, you do not draw your GUI just like in a paint-program, but you describe the GUI in a kind of description language. From this description GenGui generates a C-headerfile, wich containes the description data in a form that is needed by the routines which must be linked to your program and which do the real work on runtime. 1. The basic idea: ================== The description of the Gui is box oriented. Every box affects the size and position of the objects inside the box. A box has an orientation, which determines the positions of the objects in a box, in a vertical box the first object is on top and all other objects are below this one, in a horizontal box, the first one is on the most left side. Within a box every object can have a relative size, a size absolut in characters or a size absolut in pixels or a mixture of the last two. This object can be a new box, a gadget or a custom "gadget". This allows an easy generation of resizeable GUI's. Maybe you should get an example now: Imagine you want to have a GUI, which looks like that: +-------------------------+ | | | +-----+ +-----+ +-----+ | | |Text1| |Text2| |Text3| | | +-----+ +-----+ +-----+ | | | | | | | +-------------------------+ The description would look like this: PROJECTNAME Project1 // This is the name, which will be used // in the generated source HBOX // horizontal box VREL 1 // the box has relative height HREL 1 // and relative width BUTTON // We want to generate a button STDLINE 1 // with a height of one line plus spacing HREL 1 // and relative width TEXT "Text1" // "Text1" should be written in it ID 1 // and maybe we want to identify it later END BUTTON STDLINE 1 HREL 1 TEXT "Text2" ID 2 END BUTTON STDLINE 1 HREL 1 TEXT "Text3" ID 3 END END This would describe a GUI with three gadgets, each has (including an adequate spacing) one third of the width of the window, and a height of one line. Gengui offers some reasonable defaultvalues for the different types of objects, which significantly reduce the size of the description: PROJECTNAME Project1 HBOX BUTTON TEXT "Text1" ID 1 END BUTTON TEXT "Text2" ID 2 END BUTTON TEXT "Text3" ID 3 END END Maybe you want the first button to be double as wide as the other two buttons: PROJECTNAME Project1 HBOX BUTTON HREL 2 // now this button gets 2 parts of the width of this box TEXT "Text1" ID 1 END BUTTON // whereas this button gets only one part, TEXT "Text2" ID 2 END BUTTON // and this one too TEXT "Text3" ID 3 END END Now lets think of something like that: +-----------------+ | | | +-------------+ | | | | | | +-------------+ | | | | +--------+ | | | | | | +--------+ | | | | +---+ | | | | | | +---+ | | | +-----------------+ The first button has three times the size and the second one two times the size of the last button. PROJECTNAME Project1 VBOX // Now one button is above the other ! BUTTON HREL 3 // Three thimes the size TEXT "Text1" ID 1 END BUTTON HREL 2 // two times the size of the last button. TEXT "Text2" ID 2 END BUTTON TEXT "Text3" ID 3 END END And now a last example for this topic: +---------------+ | | | +------+ | | | | | | +------+ | | | | +--+ +------+ | | | | | | | | | | | | | | | | | | | | | | | | | | +--+ +------+ | | | +---------------+ PROJECTNAME Pro2 HBOX VBOX // left box HREL 1 VBOX // this creates the empty place in the top left corner END BUTTON VREL2 END END VBOX // right box HREL 2 // of double width BUTTON VREL 1 END BUTTON VREL 2 END END END 2. The description language =========================== These are keywords for the description languange. It does not distinguish between lower- and uppercase. Some keywords more than one name, since i could not decide wich one would be more easy to remember :). These other names can be found in the brackets (). Every command must be on a separate line, comments begin with '//' and mark the rest of the line as comment. #c_source #end_source Everything between these two lines will be directly included in the generated output. These keywords must begin on the first column ! These are the commands that are used to describe the objects of the GUI: BUTTON BUTTON : Normal button, default size HREL 1, STDLINE 1 CHECKBOX CHECKBOX : Checkbox, default size HCAR 2, VCHAR 1 CUSTOM CUSTOM : Custom Gadget, default size HREL 1, VREL 1, Read also the chapter about custom gadgets ! CYCLE CYCLE : Cycle-gadget, default size HREL 1, STDLINE 1 HBOX HBOX : horizontal box, default size: HREL 1, VREL 1 INTEGER INTEGER : Integer-gadget, default size HREL 1, STDLINE 1 LISTVIEW LISTVIEW : default size HREL 1, VREL 1 MX MX : MX-gadget, default size HREL 1, VREL 1 NUMBER NUMBER : Number-gadget, default size HREL 1, STDLINE 1 PALETTE PALETTE : Palette-gadget, default size HREL 1, VREL 1 SCROLLER SCROLLER : Scroller, default size HREL 1, VREL 1 SLIDER SLIDER : Slider, default size HREL 1, VREL 1 STRING STRING : String-gadget, default size HREL 1, STDLINE 1 TEXT TEXT : Text-gadget, default size HREL 1, STDLINE 1 VBOX VBOX : vertical box, default size: HREL 1, VREL 1 Each of these commads defines a block, which must be terminated by "END" Commands specifying the size of the objects: HCHAR (XCHAR) HCHAR chars : Absolute width of 'chars' characters HPIX (XPIX) HPIX pixel : Absolute width of 'pixel' pixels HREL (XREL) HREL size : Relative width STDCOL STDCOL chars : Absolute width of 'chars' characters plus 4 pixels space STDLINE STDLINE chars : Absolute height of 'chars' characters plus 4 pixels space VCHAR (YCHAR) VCHAR chars : Absolute height of 'chars' characters VPIX (YPIX) VPIX pixel : Absolute height of 'pixel' pixels VREL (YREL) VREL size : Relative height XSPACE XSPACE xs : Set the amount of horizontal space between gadgets to xs pixels, defaults to INTERWIDTH (only allowed within HBOX/VBOX) YSPACE YSPACE ys : Set the amount of vertical space between gadgets to ys pixels, defaults to INTERHEIGHT (only allowed within HBOX/VBOX) Commands for the description of gadget-specific data: CUSTOM CUSTOM func : Set the custom function for custom-gadgets. NOTE: this is only valid within a custom-object and since it is written the same way as the CUSTOM-object the meaning of CUSTOM only depends on the context. FLAGS FLAGS flagset : Set the flags of the gadget (-> ng_Flags) NOTE: it is possible spread the flags to more than one FLAGS command e.g.: FLAGS a|b would have the same effect as FLAGS a FLAGS b HOOK HOOK function : Set a hook function that is called, when the gadget sends a message. See also the chapter on hook-functions. ID ID id : Set the ID of the gadget (-> ng_GadgetID) NOTE: id must not contain any whitespace characters ! TAGS TAGS tags : Set the tags for a gadget. You need not set TAG_DONE, since this is automatically done. You may use more than one TAGS command per gadget, e.g. TAGS a,b TAGS c,d would have the same effect as TAGS a,b,c,d TEXT TEXT string : Set the text for the gadget (-> ng_GadgetText) TEXTATTR TEXTATTR textattr : Set ng_TextAttr. By default the standart font of the window is used for the gadgets. USER USER userdata : Set user data. You can access the user data via the macro GetUserData(). NOTE: the field ng_UserData is required by GenGui itself, but therefore it has another field reserved for this purpose. General note: The parameters of all these commands may be preprocessor symbols, in fact they are just passed on to the generated source. 3. What's generated by GenGui ============================= GenGui takes the descriptionfile and generates two headerfile. The first headerfile contains the full data of the descriptionfile and some required or useful defines. First it contains a struct WinInfo that has the name which was set using the command projectname. This struct is required for rendering the GUI to the window, therefore it is the most important structure in the headerfile. Furthermore an array of pointers to gadgets is allocated in the headerfile. This array has the name of the project plus the suffix "_Gadgets" and contains the pointers to the gadgets which you require for e.g. setting new attributes of the gadgets. To know which entry in this array belongs to a certain gadget, GenGui generates a definition for every Gadget, which tells you which entry belongs to a certain gadget. The name of this definition consists of two parts: the projectname and, seperated by an underscore, the ID of the gadget. OK, let's have a simple example to illustrate, how you would use it. The second headerfile has the extension "_def.h" and contains only the structure definitions, the prototypes and the #defines. It is useful if you want to access the GUI from another module. This could be a description of a GUI: #c_source #define ExampleButton 1 // I want to have a more telling name than a number #end_source Projectname Test VBOX BUTTON TEXT "Test" ID ExampleButton end end To render the GUI to the window you would use: RenderGui(window,&Test); And to change the attributes of the gadget you would use: GT_SetGadgetAttrs(Test_Gadgets[Test_ExampleButton],window,NULL, ... ); For accessing the contents of string- or integergadgets there are two macros GetString() and GetNumber(), which take the address of the gadget and return the contents of the gadget. Since GenGui needs the field "UserData" for internal use and it reserves another field for this purpose, it generates a new macro GetUserData() that fullfills the purpose to accessing this field for userdata. For the handling of customgadgets you require some additional defines: First there are some modes defined, whose meaning is explained in the chapter for customgadgets. Furthermore there is a macro GetInfo(), which gives you the address of the GadInfo that corresponds to a given gadget. The other structures in the headerfile contain the actual data that describes the GUI. Since they are not important for the programmer their names consist of the projectname and an extension of some numbers and characters. If you want to know more of what can be found in the headerfile you should have a look at the generated source :). 4. Writing code using GenGui ============================ The first thing you have to do is to write the file with the description of the GUI in the description-language, that was presented in chapter 2. The filename must have the extension .gui. The next step is to compile this description to a normal C-headerfile using GenGui: GenGui file.gui You will get two headerfiles: file.h and file_def.h "file.h" contains the data of the GUI and "file_def.h" contains all from "file.h" except for the data itself. There are two important aspects: - You must use Gui_GetIMsg() instead of GT_GetIMsg()! - You must use Gui_SetGadgetAttrs() instead of GT_SetGadgetAttrs()! The following example will show you how to use these GUI's within your own programs: #include "file.h" // include the headerfile that was generated by GenGui main() { struct IntuiMessage msg; struct WIndow *win; int run=1; /* . Now open all required libraries and the window. "win" must point to . the newly opened window. */ /* The Projectname of the GUI is TestPro */ if(RenderGui(win,&TestPro)) {/* do the cleanup, send an error msg .... */} /* RenderGui returns 0 if successful, an error code on failure */ while(run) { WaitPort(win->UserPort); // you may use Wait instead, if you like :) while(GuiGetIMsg(win->UserPort,&msg)) { /* It is very important that you use this function instead of GetMsg or GT_GetIMsg(), since it does some additional actions !!! */ switch(msg.Class) { case IDCMP_CLOSEWINDOW: run=0;break; case IDCMP_NEWSIZE: ResizeGui(&TestPro); // do the resizing break; case IDCMP_REFRESHWINDOW: RefreshGui(&TestPro); // and the refresh break; // ... and some more actions you need } } } FreeGui(&TestPro); // Free the gadgets /* close the window and free the sources etc. */ } When opening the window you should consider that it must be large enough to have room for all gadgets. If the window is too small then the GUI will look quite messed up. The easiest way to determine the needed size of the window is to check the minimum size for topaz 8 and then scale this size depending on the size of the used font. 5. Hook functions ================= For every gadget you may define a hook-function. This function is called whenever Intuition sends a message for this gadget. It receives a copy of the Intuimessage as parameter and must return an int as result. If you return null then the Intuimessage is passed on to your main program, in the other case the Intuimessage is ignored and your program will not receive this message any more. 6. Custom gadgets ================= Custom gadgets are a very powerful element for generating graphical user interfaces. They not only allow you to add gadgets other than gadtools gadgets, you can also use it to render information to the window, that is not really a gadget, for example some borders or texts, which should be resizeable. And a special thing which you can create using customgadgets are multiplexed user interfaces. "What's that?", you may ask. OK, I'll give you an idea, what you can achieve by this. Imagine that there is not enough room in the window to place all gadgets in it. Then you could have e.g. a cyclegadget with which you can select the group of gadgets you want to be visible in the window. First at all every customgadget requires a function that handles the creation of the "gadget". This function gets 7 arguments, the first one is a pointer to a WinInfo structure, the second one is a pointer to a NewGadget structure which was filled with all needed data (only MODE_NEW,MODE_RESIZE and MODE_REFRESH). The third one is a pointer to a GadInfo and the last four parameters describe the position and the width/height of the area of gadget. NOTE: The area of the gadget also contains the spacing around the gadget. The (suggested) dimensions of the gadget itself can be found in the newgadget structure. This function is called in several cases. It is not only called when the gadget should be created, but also when it should be removed. There are 6 Modes, which are marked in 'Mode' field of the WinInfo structure. The Modes are: MODE_NEW: A new gadget should be created. If you create gadgets you should add them to the GList 'Gadgets' in the WinInfo structure and fill 'Prev' in the same structure with the pointer to the last gadget. MODE_RESIZE: The gadget should be resized. Note that you must store the state of the gadget, e.g. the contents of a stringgadget and if the gadget is disabled. You may store that information in the Code field of the delivered GadInfo structure and the information if it is disabled can be stored using the flag BOXFLG_DISABLED in 'dim.Flags' of this structure. You must not change any other bits in this field. Straight after this call it will be called with MODE_RESTORE and only then it is allowed to use GT_SetGadgetAttrs() to change the state of gadtools gadgets, since during the MODE_REISZE call the gadgets are not bound to the window yet and GT_SetGadgetAttrs() would not work at this point. MODE_REFRESH: Redraw the gadget. You need not redraw system-gadgets, since RefreshGList() is called internally. MODE_FREE: Free the gadget. MODE_BACKUP: Store the complete information of the gadget e.g. in the fields that are named in the description of MODE_RESIZE. MODE_RESTORE: Restore the information that was stored with MODE_BACKUP or MODE_RESIZE. If you just want to draw some lines, you should ignore the latter three cases that are only important for the handling of gadgets or 'SubGui's. In these cases the contents of the NewGadget structure are not valid, however you will get a pointer to such a structure to avoid enforcer-hits. You can also use the field Render in the WinInfo structure to determine if you have draw your lines. It is set to 1 if drawing is needed and to 0 if not. You must return 0 if everything was OK and any value !=0 if an error occurred. If you want to draw some lines and render another GUI in this area you can use "SubGuis". Therefore you must describe a complete GUI just like before and render this GUI with SubGui() to the window. This function takes the same parameters as RenderGui() plus four additional parameters which describe the position and the dimensions of the GUI. You must call this every time your customfunction is called. This function return 0 on success and an value !=0 if an error occurred. In this case your function must also return a value !=0 to tell that there was an error. There is another thing that is possible using 'SubGuis', that are multiplexed user-interfaces. You might have several groups of gadgets that are rendered to the same place in the window and e.g. a global variable decides which of these groups is displayed in the window. Note that you must remove the complete GUI from the window first, if you want to switch the groups, but you cannot use FreeGui(), since this would lose the complete information that is stored in the GUI. StopGui() exists for this case. It stores this information and removes the GUI after this. The next time you call RenderGUI this information is restored. StopGUI() can also be used if you want to keep informations although you want to close the window, because you might reopen it later. See also the example for multiplexed interfaces. 7. The functions in the runtime-library "gui_lnk.o" =================================================== Gui_GetIMsg: struct IntuiMessage *Gui_GetIMsg(struct MsgPort *,struct IntuiMessage *) You must call this function instead of GT_GetIMsg() or GetMsg(). Unlike these function it requires also pointer to an 'IntuiMessage' structure where it stores a copy of the received IntuiMessage. Internally it calls GT_ReplyMsg(), therefore you need not call this any more. It returns the pointer of the given IntuiMessage, if there is a message of interest for the program, otherwise it returns NULL. This is for example the case if you have a hook-function seleced for a gadget which returns a value !=0 to indicate that the message may be ignored. Gui_SetGadgetAttrs / Gui_SetGadgetAttrsA: BOOL Gui_SetGadgetAttrsA(struct Gadget *, struct Window *, struct Requester *, struct TagItem *) BOOL Gui_SetGadgetAttrs(struct Gadget *, struct Window *, struct Requester *, Tag, ...) This is a replacemet for the function GT_SetGadgetAttrs of gadtools.library. You must call this function instead of that of gadtools, since Gengui needs to keep track of the information stored in the gadgets. NOTE: Whereas the gadtools function returns VOID this one returns if it was successful to modify the attributes. If there is not enough memory it returns 0 to indicate that there was an error and the attributes are not changed. RenderGui: int RenderGui(struct Window *win, struct WinInfo *winfo) RenderGui draws the gadgets to the window. You must supply the pointer to the window and the pointer to the WinInfo structure of your GUI. This one can be obtained by using the & operator on the name that was selected using "PROJECTMAME" in the descriptionfile. It returns 0 if everything was OK. ResizeGui: int ResizeGui(struct WinInfo *winfo) This function is used to adapt the GUI to the new size when a window has been resized. You must call this function every time you receive a IDCMP_NEWSIZE message. It returns 0 if everything was OK. RefreshGui: int RefreshGui(struct WinInfo *winfo) This function is used to refresh the gadgets within the window. It is only important if you are using SimpleRefresh, since only then it is your job to refresh the window. If you are using SmartRefresh windows then it should not be required since the system does that job for you. It returns 0 if everything was OK. FreeGui: void FreeGui(struct WinInfo *winfo) FreeGui removes the gadgets from the window. StopGui: void StopGui(struct WinInfo *winfo) StopGui() stores the information of the gadgets and removes them after this from the window. RenderGui() will recognize if the information was stored and will restore them if this was the case. SubGui: int SubGui(struct WinInfo *parent, struct WinInfo *winfo, int left,int top,int width, int height) SubGui allows to draw GUIs within another GUI. You must not use this function for other purposes. It is not possible to render a GUI only with this function. You must use RenderGui for this, since it allocates some additional resources wich are also required by SubGui and must be already allocated when SubGui is called. ClearWindow: void ClearWindow(struct Window *) Removes all contents from the window, erases the inner of the window with the EraseRect() and refreshes the windowborders. 8. Compiling ============ You need to compile gui_lnk.c in the Gui_lib directory and link this to your program. Of course you need not recompile it every time. Just compile it with your favourite C-compiler and then link gui_lnk.o to your program.