TABLE OF CONTENTS

MPGui.library/--background--
MPGui.library/AllocMPGuiHandleA
MPGui.library/FreeMPGuiHandle
MPGui.library/MPGuiCurrentAttrs
MPGui.library/MPGuiError
MPGui.library/MPGuiResponse
MPGui.library/ReadMPGui
MPGui.library/SetMPGuiGadgetValue
MPGui.library/SyncMPGuiRequest
MPGui.library/WriteMPGui
MPGui.library/--background--                     MPGui.library/--background--

 MPGui provides an easy way to display simple single colum requesters with
 File/String/Number/Slider/Cycle/Check/ScreenMode/List gadgets.

 It uses a text input file to specify the format of the Gui.

 Menus can be provided.

 Bottom gadgets can be "Ok/Cancel" for normal gadgets or "Save/Use/Cancel"
 for preferences requesters.

 Normal Help and continuous Help is supported.

 Keyboard shortcuts are supported.

 The format of the file is:

 * comment
                  Comment line

 Any %n% (n>0) will be replaced by parameters if supplied
 %% is changed to % if parameters are supplied

 "command " etc.
        etc.      Command (etc. is ignored)
  "Comment"       Comment for heading of requester
  "HelpNode"      Global Help Node for requester
  GADGET "Title":"prefix"!HelpNode!
                         A Gadget
                         GAGDET is type of gadget (see below).
                         "Title" is gadget title
                         "prefix" appears before the value in the result
                         !HelpNode! is optional help string to
                                    use in call back

  LFILE "Title":"prefix":"def"!Help!
                  Input file string and request gadget
                  Key activates
                  Right shift and key shows requester
  SFILE "Title":"prefix":"def"!Help!
                  Output file string and gadget
                  Key activates
                  Right shift and key shows requester
  FILE "T":"P":"def"!Help!
                  File string and request (input file)
                  Key activates
                  Right shift and key shows requester
  OFILE "T":"P":"def":Y/N!Help!
                  Optional file (has checkbox)
                  Key toggles and activates if becomes selectable
                  Left shift and key activates if selectable
                  Right shift and key shows requester if selectable
  ONUMBER "T":"P":"def":Y/N!Help!
                  Optional number (has checkbox)
                  Key toggles and activates if becomes selectable
                  Left shift and key activates if selectable
  NUMBER "T":"P":"def"!Help!
                  Number
                  Key activates
  CYCLE "Title"!Help!
                  Cycle gadget, each entry can be followed by other gadgets
                  Key cycles
                  Shift and key cycles back
        "value1":"Prefix1"
        "value2":"Prefix2"
     gadgets      
                  Only active when item is 2
        "value3":"Prefix3"
  ENDCYCLE:"number or valuen" 
                  Finished by default value (numeric or string)
  STRING "Title":"prefix":"def"!Help!
                  String - use for floating point as well
                  Key activates
  OSTRING "Title":"prefix":"def":Y/N!Hlp!
                  String with checkbox
                  Key toggles and activates if becomes selectable
                  Left shift and key activates if selectable
  CHECK "T":"P":Y/N!Help
                  Check box gadget
                  Key toggles
  SLIDER "T":"P":"min":"max":"def"!Hlp!
                  Slider gadget
                  Key increases
                  Shift and key decreases
  MODEn "T":"P":"def"!Help!
                  Screen Mode requester
                  Key activates
                  Right shift and key shows requester
                  n == 1 -> Workbench modes
                       2 -> Workbench modes + NONE
                       3 -> All modes
                       4 -> All modes + NONE (3 and 4 do not work too well)
  LIST "Title":!Help!
                  List view
                  Key cycles
                  Shift and key cycles back
       "value1":"prefix1"
       "value2":"prefix2"
  ENDLIST:"number or valuen":"lines"
                  finished by default value and lines (optional) default 4

MPGui.library/AllocMPGuiHandleA               MPGui.library/AllocMPGuiHandleA

   NAME   
  AllocMPGuiHandleA -- Allocates an MPGuiHandle. (V3)
  AllocMPGuiHandle -- Varargs version of AllocMPGuiHandleA (V3)

   SYNOPSIS
  gh = AllocMPGuiHandleA(taglist)
  D0                     A0

  struct MPGuiHandle * AllocMPGuiHandleA(struct TagItem *);

  gh = AllocMPGuiHandle(Tag1, ...)

  struct MPGuiHandle * AllocMPGuiHandle(ULONG,...);

   FUNCTION
  Allocates an MPGuiHandle.

   INPUTS
  taglist - pointer to TagItem array.

  Tags are:

  MPG_PUBSCREENNAME - Data is char * name of public screen to use.
                      Default is default public screen.
  MPG_RELMOUSE      - Data is BOOL. TURE to open requester near pointer.
                      Default is FALSE.
  MPG_HELP          - Data is struct Hook *, called with object=char * to
                      help node to be displayed.
  MPG_CHELP         - Call help when gadget changes
  MPG_PARAMS        - Data is char ** array of parameters
  MPG_NEWLINE       - Data is BOOL. TRUE means new line rather than space
                      in output, no "s round files or screen modes.
                      Default is FALSE.
  MPG_PREFS         - Data is BOOL. Default FALSE. TRUE provides
                      _Save/_Use/_Cancel gadgets, Use MPGuiResponse() to
                      get response (1=Save 2=Use), Esc key will not exit.
  MPG_MENUS         - Data is struct NewMenu *.
  MPG_MENUHOOK      - Data is struct Hook *, called with
                      object=struct IntuiMsg *, message = struct Menu *
                      If MPG_HELP is set then called for MENUHELP as well.
                      Return 0 to quit, non 0 to continue.
  MPG_SIGNALS       - Data is ULONG signals to wait for then call hook
                      provided in MPG_SIGNALHOOK.
  MPG_SIGNALHOOK    - Data is struct Hook *, called with
                      object = ULONG signals received,
                      message = ULONG notused
                      Return 0 to quit, non 0 to continue.

   RESULT
  gh - Allocated MPGuiHandle.
       NULL on error (no memory).

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO
  FreeMPGuiHandle(),MPGuiResponse().

MPGui.library/FreeMPGuiHandle                   MPGui.library/FreeMPGuiHandle

   NAME   
  FreeMPGuiHandle -- Frees a Handle allocated by AllocMPGuiHandleA(). (V3)

   SYNOPSIS
  FreeMPGuiHandle( gh)
                   A0

  void FreeMPGuiHandle( struct MPGuiHandle *);


   FUNCTION
  Frees a Handle allocated by AllocMPGuiHandleA().

   INPUTS
  gh - Handle allocated by AllocMPGuiHandleA.

   RESULT
  None.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO
  AllocMPGuiHandleA().

MPGui.library/MPGuiCurrentAttrs               MPGui.library/MPGuiCurrentAttrs

   NAME   
  MPGuiCurrentAttrs -- Returns the Current MPGui attributes. (V3)

   SYNOPSIS
  Attrs = MPGuiCurrentAttrs( gh)
  D0                          A0

  char * MPGuiCurrentAttrs( struct MPGuiHandle *);

   FUNCTION
  Returns the same as would be returned by SyncMPGuiRequest if the OK gadget
  is pressed now.

   INPUTS
  gh - An MPGuiHandle currently being used by SyncMPGuiRequest().

   RESULT
  Attrs - String that would be returned SyncMPGuiRequest.

   EXAMPLE

   NOTES
  This should be called from a MPG_MENUHOOK supplied to AllocMPGuiHandle().
  e.g. If a Save As... menu item is called.

   BUGS

   SEE ALSO
  SyncMPGuiRequest().

MPGui.library/MPGuiError                             MPGui.library/MPGuiError

   NAME   
  MPGuiError -- Returns the error message for an MPGuiHandle. (V3)

   SYNOPSIS
  Message = MPGuiError(gh )
  D0                   A0

  char * MPGuiError( struct MPGuiHandle *);

   FUNCTION
  Returns the error message for an MPGuiHandle.

   INPUTS
  gh - MPGuiHandle allocated by AllocMPGuiHandleA().

   RESULT
  Message - The text of an error message. May be multi line.

   EXAMPLE

   NOTES
  Use after SyncMPGuiRequest() returns -1.

   BUGS

   SEE ALSO
  SyncMPGuiRequest().

MPGui.library/MPGuiResponse                       MPGui.library/MPGuiResponse

   NAME   
  MPGuiResponse -- returns the response from a Prefs MPGui. (V3)

   SYNOPSIS
  resp = MPGuiResponse( gh)
  D0                   A0

  ULONG MPGuiResponse( struct MPGuiHandle *);

   FUNCTION
  Returns the response after calling SyncMPGuiRequest() with MPG_PREFS.

   INPUTS
  gh - An MPGuiHandle.

   RESULT
  resp - MPG_SAVE Save gadget was pressed.
         MPG_USE  Use gadget was pressed.

   EXAMPLE

   NOTES
  Only use if SyncMPGui() returns not (0 or -1).

   BUGS

   SEE ALSO
  AllocMPGuiHandleA(),SyncMPGuiRequest().

MPGui.library/ReadMPGui                               MPGui.library/ReadMPGui

   NAME   
  ReadMPGui -- Reads information for an MPGui. (V4)

   SYNOPSIS
  result = ReadMPGui( fname, gh)
  D0                         A0     A1

  BOOL ReadMPGui( char *, struct MPGuiHandle *);

   FUNCTION
  Reads all the information in the file for an MPGuiHandle allocated by
  AllocMPGuiHandle().

   INPUTS
  fname - name of file describing gui.
  gh    - MPGuiHandle allocated by AllocMPGuiHandle().

   RESULT
  TRUE if file read OK
  FALSE for error. Use MPGuiError() to get error.

   EXAMPLE

   NOTES
  Ignores any tags supplied to AllocMPGuiHandleA().

  This currently serves no purpose, but may be later used for a gui based
  gui designer.

   BUGS

   SEE ALSO
  AllocMPGuiHandleA(),MPGuiError(),WriteMPGui().

MPGui.library/SetMPGuiGadgetValue           MPGui.library/SetMPGuiGadgetValue

   NAME   
  SetMPGuiGadgetValue -- Sets the value of an MPGui gadget. (V3)

   SYNOPSIS
  succ = SetMPGuiGadgetValue( gh, Title, Value)
  D0                          A0  A1     A2

  BOOL SetMPGuiGadgetValue( struct MPGuiHandle *, char *, char *);

   FUNCTION
  Sets the value of a gadget currently being displayed by
  SyncMPGuiRequest().

   INPUTS
  gh    - MPGuiHandle being displayed by SyncMPGuiRequest().
  Title - Title of the gadget as in the input file.
  Value - Value of the gadget.
          Y/N for a CHECKs.
          A String for Strings/Files/Modes.
          A String (which is converted using strtol) for Numbers/Sliders.
          A value or number in the list/cycle for lists/cycles.

   RESULT
  error - 1 for success, 0 for failure.
          Error means gadget not found or Value not found.

   EXAMPLE

   NOTES
  Title must be exact including "_" as required.

  This should be called from a MPG_MENUHOOK supplied to AllocMPGuiHandle().
  e.g. If a Reset To Defaults... menu item is called.

   BUGS

   SEE ALSO
  SyncMPGuiRequest().

MPGui.library/SyncMPGuiRequest                 MPGui.library/SyncMPGuiRequest

   NAME   
  SyncMPGuiRequest -- Displays and processes an MPGui. (V3)

   SYNOPSIS
  result = SyncMPGuiRequest( fname, gh)
  D0                         A0     A1

  char * SyncMPGuiRequest( char *, struct MPGuiHandle *);

   FUNCTION
  Displays an MPGuiHandle allocated by AllocMPGuiHandle() and processes all
  messages.

   INPUTS
  fname - name of file describing gui.
  gh    - MPGuiHandle allocated by AllocMPGuiHandle().

   RESULT
  Attributes of the MPGui if Save/Use/Ok was used.
  0 if Cancel was used/window closed/Esc pressed.
  -1 for error. Use MPGuiError() to get error.

   EXAMPLE

   NOTES
  If MPG_PREFS was supplied to AllocMPGuiHandle() then use MPGuiResponse()
  to determine if Save or Use was pressed.

  Falls back to a compressed/column format using topaz80 if required.

   BUGS
  When trying to cope with very small screens/very large requesters it can
  result in gadgets with negative width which can crash the system.

   SEE ALSO
  AllocMPGuiHandleA(),MPGuiError(),MPGuiResponse().

MPGui.library/WriteMPGui                             MPGui.library/WriteMPGui

   NAME   
  WriteMPGui -- Writes information for an MPGui. (V4)

   SYNOPSIS
  result = WriteMPGui( fname, gh)
  D0                         A0     A1

  BOOL WriteMPGui( char *, struct MPGuiHandle *);

   FUNCTION
  Writes all the information in the file for an MPGuiHandle allocated by
  AllocMPGuiHandle().

   INPUTS
  fname - name of file to describe the gui.
  gh    - MPGuiHandle allocated by AllocMPGuiHandle().

   RESULT
  TRUE if file written OK
  FALSE for error. Use MPGuiError() to get error.

   EXAMPLE

   NOTES
  Ignores any tags supplied to AllocMPGuiHandleA().

  This currently serves no purpose, but may be later used for a gui based
  gui designer.

   BUGS

   SEE ALSO
  AllocMPGuiHandleA(),MPGuiError(),ReadMPGui().

