@database mgui_database @$VER: mgui Docs V1.20 - By Fabio Rotondo - (C) Amiga Foundation Classes @node main "AMIGA-E Modules: mgui_oo/Main" ** mgui_oo V1.20 - Original By Fabio Rotondo ** Part of Amiga Foundation Classes @{" Introduction " LINK mgui_intro} @{" Author(s) Info " LINK author} @{" Amiga Foundation Classes " LINK "afc.guide/main"} Requires: @{" NodeMaster " LINK "NodeMaster.guide/Main"}, EasyGUI Base: $000C COMMANDS BRIEF DESCRIPTION ----------------------------------------------------------------------- @{" mgui() " LINK mgui_mgui} Init the object. @{" add(....) " LINK mgui_add} Add a new GUI. @{" clear() " LINK mgui_clear} Close all GUIs. @{" del() " LINK mgui_del} Delete a GUI. @{" empty() " LINK mgui_empty} Check if mgui has no GUIs. @{" first() " LINK mgui_first} Pos on first GUI. @{" freeguis() " LINK mgui_INTERNAL} * INTERNAL USE ONLY * @{" gui() " LINK mgui_gui} Actual GUI pointer. @{" lock(mode=TRUE) " LINK mgui_lock} Lock/Unlock GUI. @{" message() " LINK mgui_message} Parse a message. @{" nm() " LINK mgui_nm} Returns related NodeMaster object. @{" numgui() " LINK mgui_numgui} Number of avail GUIs. @{" pop(pos=TRUE) " LINK mgui_pop} Pop a GUI from the stack. @{" pos(v, m=NAME, here=FALSE) " LINK mgui_pos} Search for a GUI. @{" push() " LINK mgui_push} Push a GUI into the stack. @{" screen(scr) " LINK mgui_screen} Set default screen. @{" setattrs(tags) " LINK mgui_setattrs} Set various attributes. @{" succ() " LINK mgui_succ} Pos on next GUI. @{" version() " LINK mgui_version} Returns object's version and revision. @{" ERROR TABLE " LINK Error_Table} @endnode @node mgui_mgui "mgui / mgui()" NAME: mgui() DESCRIPTION: mgui class constructor. INPUTS: NONE RESULTS: NONE SEE ALSO: @{" NodeMaster/nodemaster() " LINK "NodeMaster.guide/NodeMaster_nodemaster"} @endnode @node mgui_first "mgui / first()" NAME: first() DESCRIPTION: Set position to the first GUI in the mgui object. INPUTS: NONE RESULTS: a PTR to GUI - First() succeded. NIL - First() failed. SEE ALSO: @{" NodeMaster/first() " LINK "NodeMaster.guide/NodeMaster_first"} @endnode @node mgui_succ "mgui / succ()" NAME: succ() DESCRIPTION: Set position to the next GUI in the mgui object. INPUTS: NONE RESULTS: a PTR to GUI - succ() succeded. NIL - succ() failed. SEE ALSO: @{" NodeMaster/succ() " LINK "NodeMaster.guide/NodeMaster_succ"} @endnode @node mgui_empty "mgui / empty()" NAME: empty() DESCRIPTION: Checks if mgui object is empty or not. INPUTS: NONE RESULTS: TRUE - mgui object is empty. FALSE - at least one GUI is present. SEE ALSO: @{" NodeMaster/empty() " LINK "NodeMaster.guide/NodeMaster_empty"} @endnode @node mgui_gui "mgui / gui()" NAME: gui() DESCRIPTION: Get actual GUI pointer. INPUTS: NONE RESULTS: a PTR to a GUI - gui() succeded. NIL - gui() failed. (mgui is empty) SEE ALSO: @{" NodeMaster/obj() " LINK "NodeMaster.guide/NodeMaster_obj"} @endnode @node mgui_numgui "mgui / numgui()" NAME: numgui() DESCRIPTION: Get the number of GUIs opened at the moment. INPUTS: NONE RESULTS: a LONG containing the number of GUIs opened. SEE ALSO: @{" NodeMaster/numitems() " LINK "NodeMaster.guide/NodeMaster_numitems"} @endnode @node mgui_push "mgui / push()" NAME: push() DESCRIPTION: Push a GUI into the stack. INPUTS: NONE RESULTS: TRUE - GUI pushed into the stack. FALSE - push() failed. (Stack is full) SEE ALSO: @{" NodeMaster/push() " LINK "NodeMaster.guide/NodeMaster_push"} @endnode @node mgui_pop "mgui / pop()" NAME: pop(pos=TRUE) DESCRIPTION: Pop a GUI from the stack. INPUTS: pos - Should be TRUE or FALSE: TRUE - (default) a GUI is pop()ed from the stack and the mgui object is positioned on it. FALSE - a GUI is pop()ed from the stack, but mgui IS NOT positioned on it (ie. just clear a push()ed GUI) RESULTS: a PTR to GUI - pop() succeded. NIL - pop() failed (stack is empty or pos=FALSE) SEE ALSO: @{" NodeMaster/pop() " LINK "NodeMaster.guide/NodeMaster_pop"} @endnode @node mgui_screen "mgui / screen()" NAME: screen(scr:PTR TO screen) DESCRIPTION: Set the default screen where mgui's GUIs will be opened. INPUTS: scr - PTR to the screen. RESULTS: NONE SEE ALSO: @{" add() " LINK mgui_add} @endnode @node mgui_clear "mgui / clear()" NAME: clear() DESCRIPTION: Close all GUIs. INPUTS: NONE RESULTS: all GUIs are closed. SEE ALSO: @{" NodeMaster/clear() " LINK "NodeMaster.guide/NodeMaster_clear"} @endnode @node mgui_add "mgui / add()" NAME: add(wtitle:PTR TO CHAR, gui, info=0, screen=0, textattr=0, newmenus=0, awproc=0, x=-1, y=-1) DESCRIPTION: Add a new GUI to mgui object. INPUTS: wtitle - Title of the GUI window. gui - GUI description (see EasyGUI) info - Whatever you want. screen - PTR to screen where open the GUI. textattr - Font description. newmenus - Menu list. awproc - PTR to a appwin proc. x, y - window starting coordinates. RESULTS: a PTR to GUI - The GUI has been added. NOTE: This method may raise exceptions coming from NodeMaster() and EasyGUI. SEE ALSO: EasyGUI/easygui() @{" NodeMaster/add() " LINK "NodeMaster.guide/NodeMaster_add"} @endnode @node mgui_message "mgui / message()" NAME: message() DESCRIPTION: Waits for a new message from the user. This is one of the coolest methods of the object: you just do not have to do anything: everything is handled by this method, which minds also for inputs coming from external signals. INPUTS: NONE RESULTS: This method returns THREE values at a time: parsed - TRUE if signal arrived has been correctly parsed. sig - Signal arrived at Wait(). res - result returned by guimessage(). SEE ALSO: EasyGUI/guimessage() @endnode @node mgui_setattrs "mgui / setattrs()" NAME: setattrs(tags) DESCRIPTION: This method is used to change some current GUI's attributes and also to change mgui object's attributes. This is the only way to modify mgui behaviours. INPUTS: There are two kind of tags, those working on the current GUI and the others working on mgui itself. We'll list them separately. GUI Tags, these are the tags acting on the current GUI: MGUI_MAIN - Tells mgui whether the current GUI is the main one or not. When the main GUI is closed, all the others GUI will be closed at the same time. Possible values, TRUE / FALSE. MGUI_FREEPROC - Tells mgui what procedure(s) to call when the current GUI'll be closed. This is very useful, because you can create very complex GUI with a lot of dinamycally allocated objects and structures, that have to be freed on GUI closing. This command needs a list (or a structure) containing: PTR to proc and arguments to pass to the procedure. Example: [MGUI_FREEPROC, [{freeobj}, obj, {freesig}, sig, NIL, NIL], NIL, NIL] MGUI_NAME - This is not just a name, it is more like an "handle". Name value can be of 4 bytes (4 CHARS) just like the errors you usually Raise(). Possible values, anything 4 bytes long. Example: "MAIN" MGUI_USER - This is a field you should fill with anything you want. It is just a PTR to something. Possible values, everything. Example: myobj. MGUI_LOCK - You can lock/unlock a GUI with this tag, so you can receive user's inputs or just ignore them. Possible values: TRUE (locks GUI), FALSE (unlock GUI) MGUI Tags, these are tags action on the mgui object as a whole: MGUI_ADDSIGMASK - With this tag you can add to mgui Wait() signal some external signals you want mgui to hear about. When the Wait() is trigged by one of these sigs, the message isn't parsed and the message() method will return it to your control: you should be able to handle this message correctly. MGUI_REMSIGMASK - With this tag you can remove an external signal previously added with MGUI_ADDSIGMASK. From now on, Wait() will not wait for it anymore. MGUI_ADDEXTERNAL - This is a tag very similar to MGUI_ADDSIGMASK, but this time, you have to provide to mgui also a procedure to call whenever the Wait() is trigged by the sig you want. This is very useful, for example, to wait for Commodity or ARexx events and then to have mgui to handle all these stuff for you. The syntax is the following: [MGUI_ADDEXTERNAL, [{procedure}, signal, proc_params], NIL, NIL] procedure - proc to call when Wait() is trigged. signal - External signal to check. proc_params - Paramteres to pass to the procedure. If you want to pass more than one single value, enclose them inside []. Example: [param1, param2, param3] MGUI_REMEXTERNAL - This tag removes a signal set with MGUI_ADDEXTERNAL. From now on, Wait() will not wait for external exents anymore. Possible values: signal to remove. Example: [MGUI_REMEXTERNAL, signal, NIL, NIL] MGUI_LOCKALL - This tag will enable you to lock/unlock ALL GUIs in one single shot. Possible values: TRUE (locks GUIs), FALSE (unlock GUIs) RESULTS: NONE SEE ALSO: @{" message() " LINK mgui_message} @{" action() " LINK mgui_action} @endnode @node mgui_lock "mgui / lock()" NAME: lock(mode=TRUE) DESCRIPTION: This method locks or unlocks current GUI. INPUTS: mode - TRUE locks the GUI (default), FALSE unlocks the GUI. RESULTS: NONE SEE ALSO: @{" setattrs() " LINK mgui_setattrs} EasyGUI/blockwin() EasyGUI/unblockwin() @endnode @node mgui_del "mgui / del()" NAME: del() DESCRIPTION: This method close current GUI. The current GUI is closed and the proc set using MGUI_FREEPROC tag is called to free resources. INPUTS: NONE RESULTS: PTR to next avaible GUI or NIL if it was the last GUI. SEE ALSO: @{" add() " LINK mgui_add} @{" NodeMaster/del() " LINK "NodeMaster.guide/NodeMaster_del"} @endnode @node mgui_pos "mgui / pos() " NAME: pos(value, mode=MGUI_SEARCH_NAME, fromhere=FALSE) DESCRIPTION: This method will scan all GUIs to find the one matching the value required. Value may vary and it is influenced by the mode value. INPUTS: value - Value to search. mode - Search mode. Avaible modes are: MGUI_SEARCH_NAME - Compare value with GUI's name field. MGUI_SEACH_GUIHANDLE - Compare value with GUI's guihandle. MGUI_SEARCH_MAIN - Will search for the first GUI with the main flag set. fromhere - Tells mgui whether to scan from the beginning of the list of GUIs or just from the current position. Default is FALSE: the list is scanned from the first position. RESULTS: a PTR to GUI - pos() succeded. NIL - pos() failed. NOTE: When the pos() has mode set to MGUI_SEARCH_MAIN, value is ignored. SEE ALSO: @endnode @node mgui_nm "mgui / nm() " NAME: nm() DESCRIPTION: This method returns the PTR to the embedded NodeMaster object. INPUTS: NONE RESULTS: a PTR to NodeMaster object. SEE ALSO: @{" NodeMaster " LINK "NodeMaster.guide/main"} @endnode @node mgui_action "mgui / action() " NAME: action(actions) DESCRIPTION: This method is used to trig some actions on current GUI. INPUTS: actions - Action to perform on current GUI. Current defined actions are: MGUI_ACTION_TOFRONT - Brings GUI window to front. MGUI_ACTION_TOBACK - Brings GUI window to back. MGUI_ACTION_ACTIVATE - Activate GUI window. These actions can be ORed together. Example: action(MGUI_ACTION_TOFRONT OR MGUI_ACTION_ACTIVATE) RESULTS: TRUE - Actions performed. FALSE - action() failed (maybe no GUI is avaible) SEE ALSO: @{" setattrs() " LINK mgui_setattrs} @endnode @node mgui_version "mgui / version() " NAME: version() DESCRIPTION: This method returns current version and revision of the mgui class currently in use. INPUTS: NONE RESULTS: This method returns TWO values: version and revision. SEE ALSO: @endnode @node author "Author(s) Info" Original By: Fabio Rotondo (fsoft@intercom.it) E Version By: Fabio Rotondo Address: Fabio Rotondo C.so Vercelli 9 28100 Novara ITALY e-mail: fsoft@intercom.it Fabio.Rotondo@deagostini.it Phone: (ITA) - (0)321 - 459676 (home) (ITA) - (0)2 - 38086520 (office) (ITA) - (0)338 - 7336477 (GSM Phone) Fax: (ITA) - (0)2 - 38086278 Web: http://www.intercom.it/~fsoft (my home page) http://www.intercom.it/~fsoft/ablast.html (Amiga Blast Home Page) @endnode @node mgui_intro "mgui / Introduction" MGUI Mgui is a class that helps Amiga E programmers to write multi-gui programs very easily. It rely heavily on EasyGUI, so it is very hard that it will be ported to any other language. Anyway, I decided to include it in AFC because it is extremily useful. Note: you must to know how to use EasyGUI to use mgui. I have nothing more to add. Just try this class and enjoy yourself. Cheers, Fabio Rotondo @endnode @node Error_Table "mgui / Error Table" At the moment, this class does not define any error. @endnode