@database mgui.guide

@$VER: MGui V2.30 - By Fabio Rotondo (C)Amiga Foundation Classes

This guide file has been created using AutoGuide V1.05 - By Fabio Rotondo (fsoft@intercom.it).

@node main "Amiga Foundation Classes: mgui_oo/Main"


                      ** Mgui- 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.
    @{" addA(wtitle, gui, tags)        " LINK mgui_addA} 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.
    @{" 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 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

@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_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_addA "mgui / addA()"

          NAME: addA(wtitle:PTR TO CHAR, gui, tags=NIL:PTR TO LONG)

   DESCRIPTION: Add a new GUI to mgui object using tag-list.

        INPUTS: wtitle          - Title of the GUI window.

                gui             - GUI description (see EasyGUI)

                tags            - Tag List. You can happily mix EasyGUI tags
                                  with Mgui tags in the same list.

       RESULTS: a PTR to a gui_obj - The GUI has been added.

         NOTES: - This method may raise exceptions coming from NodeMaster() and
                  EasyGUI.

                - Starting from EasyGUI V3.3a, new tags have been added to
                  allow better multiple GUIs handling.
                  Please, note that:

                    -->> you MUST NOT use the EG_CLEAN tag <<--

                  Use the MGUI_FREEPROC method instead.

                - Don't use EG_INFO. Use MGUI_INFO instead.

                - This method actually returns TWO values:

                        gui - a pointer to a valid gui_obj
                         gh - pointer to the gui handle

      SEE ALSO: @{" setattrs() " LINK Mgui_setattrs}

                EasyGUI/easyguiA()

                @{" 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_INFO   - This is the MGui replacement FOR EG_INFO.

                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_FREEGUI - You can tell to Mgui class whether to free a GUI
                               or not. Usually, Mgui will mind GUI deallocation
                               after closing the GUI, so you don't have to
                               worry about it, but sometimes, it is better if
                               YOU do it by yourself. For example, in a
                               multi-gui list. This TAG will allow you to do
                               whatever you want with your GUI definition.
                               Possible values: TRUE (default) free the gui
                               definition. FALSE do not free gui definition.
                               NOTE: by default the gui definition WILL BE
                               freed. And you have to set this tag to FALSE
                               for every GUI you do not want to free.

                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)


         NOTES: - Don't use EG_INFO in your program. Use MGUI_INFO instead.

                - Don't use EG_CLEAN in your program. Use MGUI_FREEPROC instead (it is
                  also more comfy than EG_CLEAN)

       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

