@database CommonFuncs.guide
@rem Source: CommonFuncs.c
@rem Generated with RoboDoc v3.0i (Jul 10 1996)
@rem RoboDoc is copyright 1994--1996 by Maverick Software Development
@node Main CommonFuncs.guide
@{jcenter}
@{fg highlight}@{b}TABLE OF CONTENTS@{ub}@{fg text}

@{"Byt2Str()           " Link "Byt2Str()"}
@{"CloseLibs()         " Link "CloseLibs()"}
@{"CommonFuncs.c       " Link "CommonFuncs.c"}
@{"ComputeFont()       " Link "ComputeFont()"}
@{"ComputeX()          " Link "ComputeX()"}
@{"ComputeY()          " Link "ComputeY()"}
@{"DisplayTitle()      " Link "DisplayTitle()"}
@{"FGetS()             " Link "FGetS()"}
@{"FileReq()           " Link "FileReq()"}
@{"File_DirReq()       " Link "File_DirReq()"}
@{"FindIcon()          " Link "FindIcon()"}
@{"FindTools()         " Link "FindTools()"}
@{"FontXDim()          " Link "FontXDim()"}
@{"GetPathName()       " Link "GetPathName()"}
@{"GetToolBoolean()    " Link "GetToolBoolean()"}
@{"GetToolInt()        " Link "GetToolInt()"}
@{"GetToolStr()        " Link "GetToolStr()"}
@{"GetUserResponse()   " Link "GetUserResponse()"}
@{"Guarded_AllocLV()   " Link "Guarded_AllocLV()"}
@{"Guarded_FreeLV()    " Link "Guarded_FreeLV()"}
@{"HSV2RGB()           " Link "HSV2RGB()"}
@{"Handle_Problem()    " Link "Handle_Problem()"}
@{"HideListFromView()  " Link "HideListFromView()"}
@{"MakeHexASCIIStr()   " Link "MakeHexASCIIStr()"}
@{"ModifyListView()    " Link "ModifyListView()"}
@{"NotifyUser()        " Link "NotifyUser()"}
@{"OpenLibs()          " Link "OpenLibs()"}
@{"RGB2HSV()           " Link "RGB2HSV()"}
@{"ReportAllocLVError()" Link "ReportAllocLVError()"}
@{"SanityCheck()       " Link "SanityCheck()"}
@{"SetNotifyWindow()   " Link "SetNotifyWindow()"}
@{"SetReqButtons()     " Link "SetReqButtons()"}
@{"SetTagItem()        " Link "SetTagItem()"}
@{"SetTagPair()        " Link "SetTagPair()"}
@{"SetupList()         " LINK "SetupList()"}
@{"UserInfo()          " Link "UserInfo()"}
@{"getScreenModeID()   " Link "getScreenModeID()"}
@{jleft}
@endnode

@NODE "SetupList()" "SetupList()"
@{fg shine}SetupList()@{fg text}

@{b}NAME@{ub}
@{b}    SetupList()

@{ub}
@{b}SYNOPSIS@{ub}
    void SetupList( struct List *list, struct ListViewMem *lvm );


@{b}DESCRIPTION@{ub}
    Initialize a List structure for a ListView Gadget.

    As you can see, struct ListViewMem contains everything that the
    List structure needs:
@{FG SHINE}    
    struct ListViewMem {
    
       UBYTE       *lvm_NodeStrs;
       struct Node *lvm_Nodes;
       int          lvm_NumItems;
       int          lvm_NodeLength;
    };
@{FG TEXT}
@ENDNODE

@Node "Byt2Str()" "Byt2Str()"
@{fg shine}Byt2Str()@{fg text}

@{b}NAME@{ub}
@{b}    Byt2Str()

@{ub}
@{b}SYNOPSIS@{ub}
    char *hexstr = Byt2Str( char *output, UBYTE input_byte );


@{b}DESCRIPTION@{ub}
    Take an input binary character & generate a displayable 
    two-character ASCII 
    string that displays the HexaDecimal value of each byte.


@{b}WARNINGS@{ub}
@{b}    The output buffer has to be TWO times as long as the input
    buffer (+ 1 for nil); in other words supply a buffer that's
    three characters long!
@{ub}
@endnode
@Node "CloseLibs()" "CloseLibs()"
@{fg shine}CloseLibs()@{fg text}

@{b}NAME@{ub}
@{b}    CloseLibs()

@{ub}
@{b}SYNOPSIS@{ub}
    void CloseLibs( void );


@{b}DESCRIPTION@{ub}
    Close the three most-commonly used libraries - 

       intuition.library, graphics.library & gadtools.library.

@endnode
@Node "CommonFuncs.c" "CommonFuncs.c"
@{fg shine}CommonFuncs.c@{fg text}

@{b}NAME@{ub}
@{b}    @{b}CommonFuncs.c@{ub}

@{ub}
@{b}DESCRIPTION@{ub}
    Functions that get used a lot for GUI programming, especially for
    GadToolsBox-generated GUIs.  This file is used to generate 
    CommonFuncs.o - a Link-able Object for the SAS-C (V6.58) compiler.

    This a link-able object because there are far too many shared 
    libraries for the Amiga OS as it is, I couldn't see cluttering 
    someone's hard drive with another one (especially my own!).


@{b}HISTORY@{ub}
    24-Sep-2000 - Added DisplayTitle() & UserInfo() functions.
    17-Sep-2000 - Added SetTagPair(), Guarded_FreeLV(), &
                  Guarded_AllocLV() functions.
    28-Aug-2000 - Added GetPathName() function.
    18-May-2000 - Added FontXDim() function.
    17-May-2000 - Added GetScreenModeID() function.
    19-Jan-2000 - Changed FileReq() to check for NULL parameter. 
                  Added File_DirReq() function.


@{b}AUTHOR@{ub}
@{b}    James T. Steichen
    2217 N. Tamarack Dr.
    Slayton, Mn. 56172-1155, USA
    jimbot\@rconnect.com

@{ub}
@{b}NOTES@{ub}
@{b}@{fg shine}    $VER: @{b}CommonFuncs.c@{ub} 2.0 (24-Sep-2000) by J.T. Steichen

@{fg text}@{ub}
@{b}COPYRIGHT@{ub}
    @{b}CommonFuncs.c@{ub} & CommonFuncs.h (c) 1999-2000 by J.T. Steichen

@endnode
@Node "ComputeFont()" "ComputeFont()"
@{fg shine}ComputeFont()@{fg text}

@{b}NAME@{ub}
@{b}    ComputeFont()

@{ub}
@{b}SYNOPSIS@{ub}
    void ComputeFont( struct Screen   *screen,
                      struct TextAttr *font,
                      struct CompFont *cfont,
                      UWORD            width,
                      UWORD            height
                    );


@{b}DESCRIPTION@{ub}
    Initialize the CompFont structure according to the supplied
    values in the font, width & height.  If the results won't fit
    the screen dimensions, use topaz (8) in the computations
    instead.


@{b}NOTES@{ub}
@{b}@{fg shine}    GfxBase has to be open BEFORE calling this function!
@{fg text}@{ub}
@endnode
@Node "ComputeX()" "ComputeX()"
@{fg shine}ComputeX()@{fg text}

@{b}NAME@{ub}
@{b}    ComputeX()

@{ub}
@{b}SYNOPSIS@{ub}
    UWORD size = ComputeX( UWORD fontxsize, UWORD value );


@{b}DESCRIPTION@{ub}
    This function returns (fontxsize * value + 4) / 8


@{b}NOTES@{ub}
@{b}@{fg shine}    This function will probably be changed to private later.
@{fg text}@{ub}
@endnode
@Node "ComputeY()" "ComputeY()"
@{fg shine}ComputeY()@{fg text}

@{b}NAME@{ub}
@{b}    ComputeY()

@{ub}
@{b}SYNOPSIS@{ub}
    UWORD size = ComputeY( UWORD fontysize, UWORD value );


@{b}DESCRIPTION@{ub}
    This function returns (fontysize * value + 4) / 8


@{b}NOTES@{ub}
@{b}@{fg shine}    This function will probably be changed to private later.
@{fg text}@{ub}
@endnode
@Node "DisplayTitle()" "DisplayTitle()"
@{fg shine}DisplayTitle()@{fg text}

@{b}NAME@{ub}
@{b}    DisplayTitle()

@{ub}
@{b}SYNOPSIS@{ub}
    void DisplayTitle( struct Window *wptr, char *windowTitle );


@{b}DESCRIPTION@{ub}
    Display the given text as a title for the given Window.


@{b}NOTES@{ub}
@{b}@{fg shine}    The title is silently limited to 79 characters in length.
@{fg text}@{ub}
@endnode
@Node "FGetS()" "FGetS()"
@{fg shine}FGetS()@{fg text}

@{b}NAME@{ub}
@{b}    FGetS()

@{ub}
@{b}SYNOPSIS@{ub}
    char *str = FGetS( char *buffer, int readlength, FILE *fptr );


@{b}DESCRIPTION@{ub}
    This function is identical to the C library function fgets()
    except that it changes the \\n at the end of a line to a \\0.

@endnode
@Node "FileReq()" "FileReq()"
@{fg shine}FileReq()@{fg text}

@{b}NAME@{ub}
@{b}    FileReq()

@{ub}
@{b}SYNOPSIS@{ub}
    int len = FileReq( char *filename, struct TagItem *taglist );


@{b}DESCRIPTION@{ub}
    Display the ASL file requester with the given taglist.


@{b}NOTES@{ub}
@{b}@{fg shine}    This function is identical to File_DirReq() except that we
    don't use the Directory parameter.

    The suggested taglist items should be:

    ASLFR_Window,          (ULONG) WindowPointer // definitely needed!

    ASLFR_TitleText,       (ULONG) "Example title..." 
    ASLFR_InitialHeight,   200,
    ASLFR_InitialWidth,    400,
    ASLFR_InitialTopEdge,  16,
    ASLFR_InitialLeftEdge, 50,
    ASLFR_PositiveText,    (ULONG) "OKAY!",
    ASLFR_NegativeText,    (ULONG) "CANCEL!",
    ASLFR_InitialPattern,  (ULONG) "#?",
    ASLFR_InitialFile,     (ULONG) "",
    ASLFR_InitialDrawer,   (ULONG) "RAM:",
    ASLFR_Flags1,          FRF_DOPATTERNS,
    ASLFR_Flags2,          FRF_REJECTICONS,
    ASLFR_SleepWindow,     1,
    ASLFR_PrivateIDCMP,    1,
    TAG_END
@{fg text}@{ub}
@endnode
@Node "File_DirReq()" "File_DirReq()"
@{fg shine}File_DirReq()@{fg text}

@{b}NAME@{ub}
@{b}    File_DirReq()

@{ub}
@{b}SYNOPSIS@{ub}
    int len = File_DirReq( char           *filename, 
                           char           *dirname,
                           struct TagItem *taglist
                         );


@{b}DESCRIPTION@{ub}
    Display the ASL file requester with the given taglist.  Return
    the size of the file selected as well as the filename & Directory.

    The suggested taglist items should be:

    ASLFR_Window,          (ULONG) WindowPointer // definitely needed!

    ASLFR_TitleText,       (ULONG) "Example title..." 
    ASLFR_InitialHeight,   200,
    ASLFR_InitialWidth,    400,
    ASLFR_InitialTopEdge,  16,
    ASLFR_InitialLeftEdge, 50,
    ASLFR_PositiveText,    (ULONG) "OKAY!",
    ASLFR_NegativeText,    (ULONG) "CANCEL!",
    ASLFR_InitialPattern,  (ULONG) "#?",
    ASLFR_InitialFile,     (ULONG) "",
    ASLFR_InitialDrawer,   (ULONG) "RAM:",
    ASLFR_Flags1,          FRF_DOPATTERNS,
    ASLFR_Flags2,          FRF_REJECTICONS,
    ASLFR_SleepWindow,     1,
    ASLFR_PrivateIDCMP,    1,
    TAG_END

@endnode
@Node "FindIcon()" "FindIcon()"
@{fg shine}FindIcon()@{fg text}

@{b}NAME@{ub}
@{b}    FindIcon()

@{ub}
@{b}DESCRIPTION@{ub}
    Find the icon associated with pgmname (if any) & process the
    ToolTypes array in the icon with ToolProc().


@{b}SYNOPSIS@{ub}
    void *rval = FindIcon( void              *(ToolProc)(char **), 
                           struct DiskObject *dobj,
                           char              *pgmname
                         );


@{b}INPUTS@{ub}
    ToolProc() - a Pointer to a function that will perform an
                 operation on the ToolTypes array from the Icon
                 if the icon was found.

    dobj       - storage (for a later call to FreeDiskObject())

    pgmname    - The name of the icon to look for (without the
                 ".info" at the end of the string). 


@{b}NOTES@{ub}
@{b}@{fg shine}    If the user starts a program from the CLI, & the icon is in
    the same directory, we will get the ToolTypes from the icon
    instead of using the built-in defaults.
@{fg text}@{ub}
@endnode
@Node "FindTools()" "FindTools()"
@{fg shine}FindTools()@{fg text}

@{b}NAME@{ub}
@{b}    FindTools()
 
@{ub}
@{b}DESCRIPTION@{ub}
    Locate a tools array for a given name.


@{b}SYNOPSIS@{ub}
    char **toolarray = FindTools( struct DiskObject *diskobj,
                                  char              *filename,
                                  BPTR               directory_lock
                                );


@{b}INPUTS@{ub}
    filename = null-terminated name of file to look for.
    lock     = directory to look for file in.
    diskobj  = storage (for a later call to FreeDiskObject()) 


@{b}WARNINGS@{ub}
@{b}    Be sure to call FreeDiskObject() later in your program.
    FindTools() doesn't do this because it doesn't know what 
    you're going to do with the ToolTypes. 
@{ub}
@endnode
@Node "FontXDim()" "FontXDim()"
@{fg shine}FontXDim()@{fg text}

@{b}NAME@{ub}
@{b}    FontXDim()

@{ub}
@{b}SYNOPSIS@{ub}
    int length = FontXDim( struct TextAttr *font );


@{b}DESCRIPTION@{ub}
    Determine the horizontal distance for one character in the given
    font.

@endnode
@Node "GetPathName()" "GetPathName()"
@{fg shine}GetPathName()@{fg text}

@{b}NAME@{ub}
@{b}    GetPathName()
  
@{ub}
@{b}SYNOPSIS@{ub}
    char *path = GetPathName( char *pathbuf, char *filename, int size );


@{b}DESCRIPTION@{ub}
    Return with the Path portion of a filename string.

@endnode
@Node "GetToolBoolean()" "GetToolBoolean()"
@{fg shine}GetToolBoolean()@{fg text}

@{b}NAME@{ub}
@{b}    GetToolBoolean()

@{ub}
@{b}DESCRIPTION@{ub}
    Find the tooltype boolean that matches the given name.


@{b}SYNOPSIS@{ub}
    boolean ans = GetToolBoolean( char **toolptr,
                                  char  *name,
                                  int    defaultBool
                                );


@{b}INPUTS@{ub}
    toolptr     = pointer from FindTools() call.
    name        = tool we're searching the icon for.
    defaultBool = default boolean to return if the tool isn't found.


@{b}NOTES@{ub}
@{b}@{fg shine}    The following strings will return a Boolean value of TRUE:
        
        "TRUE", "YES", "OK" & "OKAY"

    any other value will return FALSE.
@{fg text}@{ub}
@endnode
@Node "GetToolInt()" "GetToolInt()"
@{fg shine}GetToolInt()@{fg text}

@{b}NAME@{ub}
@{b}    GetToolInt() 

@{ub}
@{b}DESCRIPTION@{ub}
    Find the tooltype integer that matches the given name.


@{b}SYNOPSIS@{ub}
    tool_int = GetToolInt( char **toolarray,
                           char  *toolname,
                           int    default_val
                         );


@{b}INPUTS@{ub}
    toolarray   = pointer from FindTools() call.
    toolname    = tool we're searching the icon for.
    default_val = default integer to return if the tool isn't found.

@endnode
@Node "GetToolStr()" "GetToolStr()"
@{fg shine}GetToolStr()@{fg text}

@{b}NAME@{ub}
@{b}    GetToolStr()

@{ub}
@{b}DESCRIPTION@{ub}
    Find the tooltype string that matches the given name.


@{b}SYNOPSIS@{ub}
    toolstring = GetToolStr( char **toolarray,
                             char  *toolname,
                             char  *default_tool
                           );


@{b}INPUTS@{ub}
    toolarray    = pointer from FindTools() call.
    toolname     = tool we're searching the icon for.
    default_tool = default string to return if the tool isn't found.

@endnode
@Node "GetUserResponse()" "GetUserResponse()"
@{fg shine}GetUserResponse()@{fg text}

@{b}NAME@{ub}
@{b}    GetUserResponse - Get a button response from the user.

@{ub}
@{b}SYNOPSIS@{ub}
    int ans = GetUserResponse( char *info, char *title, int *errnum );


@{b}FUNCTION@{ub}
@{b}@{fg shine}    Return -1 if there's no window, otherwise return the ordinal
    of the button the user pressed.  This means that there can be
    more than two choice buttons for the User to choose from.

@{fg text}@{ub}
@{b}INPUTS@{ub}
    info   - Information string for the user to act on.
    title  - Title of the Problem Requester.
    errnum - Optional error number.


@{b}NOTES@{ub}
@{b}@{fg shine}    GetUserResponse() will return 0 for the right-most button,
    instead of n, where n is the number of buttons.  This is the
    behavior of the EasyRequest() function (so don't blame me!).

    Call SetReqButtons() before using this function &
    be sure to call SetNotifyWindow( wptr ) BEFORE using this 
    function for the first time!
@{fg text}@{ub}
@endnode
@Node "Guarded_AllocLV()" "Guarded_AllocLV()"
@{fg shine}Guarded_AllocLV()@{fg text}

@{b}NAME@{ub}
@{b}    Guarded_AllocLV()

@{ub}
@{b}SYNOPSIS@{ub}
    struct ListViewMem *lvm = Guarded_AllocLV( int numitems, 
                                               int itemsize
                                             );


@{b}DESCRIPTION@{ub}
    Allocate the memory associated with a ListView Gadget.

@endnode
@Node "Guarded_FreeLV()" "Guarded_FreeLV()"
@{fg shine}Guarded_FreeLV()@{fg text}

@{b}NAME@{ub}
@{b}    Guarded_FreeLV()

@{ub}
@{b}SYNOPSIS@{ub}
    void Guarded_FreeLV( struct ListViewMem *lvm );


@{b}DESCRIPTION@{ub}
    Free the memory associated with a ListView Gadget & reset 
    the Guard. 

@endnode
@Node "HSV2RGB()" "HSV2RGB()"
@{fg shine}HSV2RGB()@{fg text}

@{b}NAME@{ub}
@{b}    HSV2RGB()

@{ub}
@{b}SYNOPSIS@{ub}
    struct ColorCoords *ans = HSV2RGB( struct ColorCoords *input );


@{b}DESCRIPTION@{ub}
    Convert an HSV (Hue, Saturation & Luminance) coordinate into
    RGB (red, green & blue).


@{b}NOTES@{ub}
@{b}@{fg shine}    red, green & blue are values from 0 to 255 (normally).

@{fg text}@{ub}
@{b}WARNINGS@{ub}
@{b}    If you want the input structure for later, save it before
    passing it to this function, since it modifies it & returns it.

@{ub}
@endnode
@Node "Handle_Problem()" "Handle_Problem()"
@{fg shine}Handle_Problem()@{fg text}

@{b}NAME@{ub}
@{b}    Handle_Problem()

@{ub}
@{b}SYNOPSIS@{ub}
    int ans = Handle_Problem( char *info, char *title, int *errnum );


@{b}DESCRIPTION@{ub}
    Get a Yes/No Response from the user.


@{b}FUNCTION@{ub}
@{b}@{fg shine}    Return -1 if the user selected the ABORT (far-right) button,
    else return the errnum value (normally 0).

@{fg text}@{ub}
@{b}INPUTS@{ub}
    info   - Information string for the user to act on.
    title  - Title of the Problem Requester.
    errnum - Optional error number (normally NULL).


@{b}NOTES@{ub}
@{b}@{fg shine}    Be sure to call SetNotifyWindow( wptr ) BEFORE using this 
    function for the first time!
@{fg text}@{ub}
@endnode
@Node "HideListFromView()" "HideListFromView()"
@{fg shine}HideListFromView()@{fg text}

@{b}NAME@{ub}
@{b}    HideListFromView()

@{ub}
@{b}SYNOPSIS@{ub}
    void HideListFromView( struct Gadget *listview_gadget,
                           struct Window *window_pointer
                         );


@{b}DESCRIPTION@{ub}
    Turn off the Given ListView Gadget for the window, so that it
    can be modified elsewhere.


@{b}SEE ALSO@{ub}
    ModifyListView()

@endnode
@Node "MakeHexASCIIStr()" "MakeHexASCIIStr()"
@{fg shine}MakeHexASCIIStr()@{fg text}

@{b}NAME@{ub}
@{b}    MakeHexASCIIStr()

@{ub}
@{b}SYNOPSIS@{ub}
    unsigned int length = MakeHexASCIIStr( char *output, 
                                           char *input,
                                           int   inputlength
                                         );


@{b}DESCRIPTION@{ub}
    Take an input binary string & generate a displayable ASCII 
    string that displays the HexaDecimal value of each byte as
    well as the ASCII representation (for characters >= 0x20 &
    <= 0x7E).

    Output will be as follows:

    /------------ Hex Bytes ----------\\ /--- ASCII ----\\

    22334455 22334455 A7223344 7F223344 "3DU"3DU."3D."3D 


@{b}WARNINGS@{ub}
@{b}    The output buffer has to be FOUR times as long as the input
    buffer!  The maximum value for inlen should be 20 bytes, with
    16 being the nominal value.
@{ub}
@endnode
@Node "ModifyListView()" "ModifyListView()"
@{fg shine}ModifyListView()@{fg text}

@{b}NAME@{ub}
@{b}    ModifyListView()

@{ub}
@{b}SYNOPSIS@{ub}
    void ModifyLsitView( struct Gadget *listview_gadget,
                         struct Window *window_pointer,
                         struct List   *listview_contents,
                         struct Gadget *string_gadget
                       ); 


@{b}DESCRIPTION@{ub}
    Change the Given ListView Gadget for the window to the 
    new parameters, which will re-display it.


@{b}SEE ALSO@{ub}
    HideListFromView()

@endnode
@Node "NotifyUser()" "NotifyUser()"
@{fg shine}NotifyUser()@{fg text}

@{b}NAME@{ub}
@{b}    NotifyUser() - Internal to CommonFuncs.o only (PRIVATE!)

@{ub}
@{b}SYNOPSIS@{ub}
    int ans = NotifyUser( char          *info, 
                          char          *title,
                          struct Window *wptr, 
                          int           *errnum
                        );


@{b}DESCRIPTION@{ub}
    Get a response from the user.


@{b}FUNCTION@{ub}
@{b}@{fg shine}    Return -1 if the user selected the far-right button (ABORT?),
    else return 0 (CONTINUE?).

@{fg text}@{ub}
@{b}INPUTS@{ub}
    info   - Information string for the user to act on.
    title  - Title of the Problem Requester.
    wptr   - The window to open the Requester on.
    errnum - Optional error number (normally NULL).

@endnode
@Node "OpenLibs()" "OpenLibs()"
@{fg shine}OpenLibs()@{fg text}

@{b}NAME@{ub}
@{b}    OpenLibs()

@{ub}
@{b}SYNOPSIS@{ub}
    int result = OpenLibs( void );


@{b}DESCRIPTION@{ub}
    Open the three most-commonly used libraries (V39+) - 

       intuition.library, graphics.library & gadtools.library.


@{b}RETURN VALUE@{ub}
@{b}    Negative integer if a library could NOT be opened, zero if
    all was successful.
@{ub}
@endnode
@Node "RGB2HSV()" "RGB2HSV()"
@{fg shine}RGB2HSV()@{fg text}

@{b}NAME@{ub}
@{b}    RGB2HSV()

@{ub}
@{b}SYNOPSIS@{ub}
    struct ColorCoords *ans = RGB2HSV( struct ColorCoords *input );


@{b}DESCRIPTION@{ub}
    Convert an RGB color coordinate set into HSV (Hue,
    Saturation & Luminance).


@{b}NOTES@{ub}
@{b}@{fg shine}    red, green & blue are values from 0 to 255 (normally).

@{fg text}@{ub}
@{b}WARNINGS@{ub}
@{b}    If you want the input structure for later, save it before
    passing it to this function, since it modifies it & returns it.
@{ub}
@endnode
@Node "ReportAllocLVError()" "ReportAllocLVError()"
@{fg shine}ReportAllocLVError()@{fg text}

@{b}NAME@{ub}
@{b}    ReportAllocLVError()

@{ub}
@{b}SYNOPSIS@{ub}
    void ReportAllocLVError( void );


@{b}DESCRIPTION@{ub}
    Display a requester informing the User the error that 
    Guarded_AllocLV() found.


@{b}SEE ALSO@{ub}
    Guarded_AllocLV(), Guarded_FreeLV()

@endnode
@Node "SanityCheck()" "SanityCheck()"
@{fg shine}SanityCheck()@{fg text}

@{b}NAME@{ub}
@{b}    SanityCheck - Get a Yes/No Response from the user.

@{ub}
@{b}SYNOPSIS@{ub}
    Boolean answer = SanityCheck( char *question );


@{b}FUNCTION@{ub}
@{b}@{fg shine}    Return TRUE if the User pressed the 'YES' button.
    Return FALSE if the User pressed the 'NO' button.

@{fg text}@{ub}
@{b}INPUTS@{ub}
    question - question the User has to respond to.


@{b}NOTES@{ub}
@{b}@{fg shine}    Be sure to call SetNotifyWindow( wptr ) BEFORE using this 
    function for the first time!
@{fg text}@{ub}
@endnode
@Node "SetNotifyWindow()" "SetNotifyWindow()"
@{fg shine}SetNotifyWindow()@{fg text}

@{b}NAME@{ub}
@{b}    SetNotifyWindow()

@{ub}
@{b}SYNOPSIS@{ub}
    (void) SetNotifyWindow( struct Window *wptr );


@{b}DESCRIPTION@{ub}
    Set the window pointer that Handle_Problem() & other User-
    Requesters will use for the EasyRequest() call.

@endnode
@Node "SetReqButtons()" "SetReqButtons()"
@{fg shine}SetReqButtons()@{fg text}

@{b}NAME@{ub}
@{b}    SetReqButtons

@{ub}
@{b}SYNOPSIS@{ub}
    (void) SetReqButtons( char *newbuttons );


@{b}DESCRIPTION@{ub}
    Set the buttons for the Information requester to the given 
    format string.


@{b}NOTES@{ub}
@{b}@{fg shine}    The user of this function should return the buttons to a
    known string after Handle_Problem() or the other User-
    requesters are called.
@{fg text}@{ub}
@endnode
@Node "SetTagItem()" "SetTagItem()"
@{fg shine}SetTagItem()@{fg text}

@{b}NAME@{ub}
@{b}    SetTagItem()

@{ub}
@{b}SYNOPSIS@{ub}
    void SetTagItem( struct TagItem *taglist, ULONG tag, ULONG value );


@{b}DESCRIPTION@{ub}
    This function searches the given taglist for the given tag.  If
    the tag is found, its value (ti_Data) is changed to the given
    value.  This function completes the functionality for using 
    TagLists.

@endnode
@Node "SetTagPair()" "SetTagPair()"
@{fg shine}SetTagPair()@{fg text}

@{b}NAME@{ub}
@{b}    SetTagPair()

@{ub}
@{b}SYNOPSIS@{ub}
    void SetTagPair( struct TagItem *taglist, ULONG tag, ULONG value );


@{b}DESCRIPTION@{ub}
    Add a Tag & value to a TagItem list.  If taglist is NULL, 
    nothing is done by this function.
    This function completes the functionality for using TagLists.


@{b}NOTES@{ub}
@{b}@{fg shine}    taglist is really an array of ULONG values organized into pairs.

@{fg text}@{ub}
@{b}WARNINGS@{ub}
@{b}    No check is done to see if there is space in the Tag list
    for the added pair (so why not reserve space by using: 
    {TAG_IGNORE, NULL} in the taglist you provide?).
@{ub}
@endnode
@Node "UserInfo()" "UserInfo()"
@{fg shine}UserInfo()@{fg text}

@{b}NAME@{ub}
@{b}    UserInfo()

@{ub}
@{b}SYNOPSIS@{ub}
    void UserInfo( char *message, char *windowtitle );


@{b}DESCRIPTION@{ub}
    Tell user some information.


@{b}NOTES@{ub}
@{b}@{fg shine}    Be sure to call SetNotifyWindow( wptr ) BEFORE using this 
    function for the first time!
@{fg text}@{ub}
@endnode
@Node "getScreenModeID()" "getScreenModeID()"
@{fg shine}getScreenModeID()@{fg text}

@{b}NAME@{ub}
@{b}    getScreenModeID()

@{ub}
@{b}SYNOPSIS@{ub}
    ULONG mode = getScreenModeID( struct TagItem *taglist, 
                                  struct Screen  *screen,
                                  char           *req_title
                                ); 


@{b}DESCRIPTION@{ub}
    Obtain a user-selected (via ASL) ScreenModeID value.  NULL will
    be returned if you supply a NULL value for the screen pointer,
    or if you press & release the Cancel Gadget on the Requester.

@endnode