Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/480.lha/SmartField/Docs/Function Descriptions.pp/Function Descriptions

Text File | 1991-02-06 | 53.6 KB | 1,275 lines

FUNCTION DESCRIPTIONS


Low-Level Console Functions: Character Output

These functions handle all console display by outputting to the console
device the required escape sequences.  Each function requires a pointer to
the IOStdReq structure created either 1) by your calling program or 2) by the
field_open() function and pointed to by the WriteReq pointer in your
FieldHeader structure.  Some of the supplied functions were not required by
the SmartFields system but were included just for completeness in case you
decided to write your own console program.


void con_char_backspace( wreq )
    struct IOStdReq *wreq

    This function backspaces the cursor one character position to the left,
    deleting the character to the left of the cursor and moving all
    characters to the right of the cursor one character position to the left.


void con_char_delete( wreq )
    struct IOStdReq *wreq

    This function deletes the character under the cursor and moves all
    characters to the right of the cursor one character position to the left.


void con_char_insert( wreq )
    struct IOStdReq *wreq

    This function moves all characters at and to the right of the cursor one
    character position to the right and inserts a blank space at the current
    cursor position.


void con_char_mult_delete( wreq, chars )
    struct IOStdReq *wreq
    int chars

    This function deletes chars number of characters at and to the right of
    the cursor, moving the characters to the right of the cursor chars
    character positions to the left to fill in for the deleted characters.
    Any value for chars less than 0 or greater than 999 will cause unexpected
    results.  Because of the nature of the console's delete command, a value
    of 0 for chars will default to 1.


void con_display_erase( wreq )
    struct IOStdReq *wreq

    This function erases from the cursor to the end of the console display.


void con_events( wreq, flags, set_or_reset )
    struct IOStdReq *wreq
    ULONG flags
    UBYTE set_or_reset

    This function sets which raw input events the console device is to
    monitor for activity.  If you've ever used the console device for
    monitoring raw input, you should be familiar with the large quantity of
    data that must be handled.  We suggest that you use the Intuition IDCMP
    to monitor raw input instead.  This function is not required for
    SmartFields operation but was provided just for completeness.  The
    operation of this function is not guaranteed and is provided "as is."

    Use the values SET_EVENTS or RESET_EVENTS as defined in console/console.h
    to indicate whether you want to set or reset (in other words, monitor or
    not monitor) the specified events.  When you first open the console
    device, the default is to not monitor for any of the raw input events.
    Use the intuition/intuition.h IDCMP flags for flags to indicate which of
    the raw input events you want to begin or quit monitoring.


void con_graphic_rend( wreq, style, foreground, background )
    struct IOStdReq *wreq
    USHORT style
    USHORT foreground
    USHORT background

    This function sets the console text attributes:

    style
        Set this to any combination of the following values as defined in
        console/console.h:  CON_PLAIN, CON_BOLD, CON_ITALIC, CON_UNDERSCORE,
        and CON_INVERSE.  The style is reset to CON_PLAIN before the desired
        style is rendered each time this function executes so that the
        effects of this function are not cumulative.

    foreground
        The foreground is the color of the characters displayed by the
        console device.  A value less than zero or greater than seven will
        produce unexpected results.  Note that with the default Workbench
        screen colors, a foreground color of 0 will result in blue letters, 1
        in white, 2 in black, and 3 in orange.

    background
        This is the color of the background of each character displayed by
        the console device.  Note that with Topaz 80, the default Workbench
        font used by the console device, the background will be a square 8x8
        pixels in size.  Two warnings:  if the foreground and background
        values are equal, the characters will be invisible.  Also, any time a
        character is deleted, an 8x8 pixel square the color of the background
        will appear at the right side of the field (or the console display if
        fields are not being used).  This is a quality inherited from the
        nature of the console device.

    If you have any questions on how colors are rendered with the console
    device, use the included graphic rendition test program, g.c.  Note that
    in most cases, a background color equal to the default background color
    of the window will produce the best results.


void con_left_offset( wreq, x )
    struct IOStdReq *wreq
    int x

    This function sets the console left offset (the left margin of the
    console display) to horizontal pixel position x as measured from the left
    edge of the window.  Note that the left-most pixel position in the window
    is 0.


void con_line_erase( wreq )
    struct IOStdReq *wreq

    This function erases the console display to the end of the current line
    as established by the con_line_length() function.  The default end of the
    line is the right window border.


void con_line_length( wreq, length )
    struct IOStdReq *wreq
    int length

    This function sets the length of the console line to length characters.
    Because this is the length of every console line and not just the current
    line, this in effect sets the right margin of the console display.  Thus,
    this function must be called each time the cursor moves to a new field
    because fields are not all necessarily the same length.


void con_line_next( wreq )
    struct IOStdReq *wreq

    This function moves the cursor to column 1 of the next console line.
    Remember that rows (lines) and columns can vary in location during the
    duration of a program and are based on the left and top offsets of the
    console display as set by the con_left_offset() and con_top_offset()
    functions.  Caution: if the cursor is near the bottom border of the
    window such that there is not enough room for the next line to be
    completely displayed, the ENTIRE console display will be scrolled up one
    line to make room for the next line.


void con_line_prev( wreq )
    struct IOStdReq *wreq

    This function moves the cursor to column 1 of the previous console line.
    Caution: if the cursor is near the top border of the window such that
    there is not enough room for the previous line to be completely
    displayed, the ENTIRE console display will be scrolled down one line to
    make room for the previous line.


void con_line_scroll_down( wreq )
    struct IOStdReq *wreq

    This function scrolls the entire console display down one line, deleting
    the bottom line and inserting a blank line at the top of the display.
    Note that the console display is initially defined to be just inside the
    window borders, but can be later defined horizontally by the
    con_left_offset() and con_line_length() functions and vertically by the
    con_top_offset() and con_page_length() functions.


void con_line_scroll_up( wreq )
    struct IOStdReq *wreq

    This function scrolls the entire console display up one line, deleting
    the top line and inserting a blank line at the bottom of the display.


void con_page_length( wreq, length )
    struct IOStdReq *wreq
    int length

    This function sets the length (actually height) of the console display to
    length rows from the top of the display, which is initially the top
    border of the window but can be redefined by the con_top_offset()
    function.  Note that this is an offset from the top of the console
    display, and not an absolute position in the window.


void con_put_char( wreq, character )
    struct IOStdReq *wreq
    UBYTE character

    This function outputs the specified character to the console.


void con_put_line( wreq, string, max )
    struct IOStdReq *wreq
    UBYTE *string
    int max

    This function outputs to the console a null-terminated string of at most
    max characters in length.  If string contains fewer than max characters,
    the characters up to but not including the terminating null will be
    output to the console.


void con_put_string( wreq, string )
    struct IOStdReq *wreq
    UBYTE *string

    This function outputs a null-terminated string to the console.


void con_read( rreq, input_buffer )
    struct IOStdReq *rreq
    UBYTE *input_buffer

    This function reads as many characters as possible from the console into
    the specified input buffer, returning the actual number of characters
    read.  Note that the buffer should be declared by your calling program to
    be at least as large as CONSOLE_BUFFER_SIZE as defined in console/
    console.h.  This function returns immediately even if no characters are
    read.  Be careful to supply a pointer here to the READ request and not
    the write request.


void con_top_offset( wreq, y )
    struct IOStdReq *wreq
    int y

    This function sets the console top offset (the top of the console
    display) to vertical pixel position y as measured from the top edge of
    the window.  Note that the topmost pixel position in the window (which is
    hidden by the title bar) is 0.


void con_write( wreq, string, length )
    struct IOStdReq *wreq
    UBYTE *string
    int length

    This function outputs a string of exactly length characters to the
    console.  This function does not check for a terminating null.



Low-Level Console Functions: Cursor Movement

These functions handle all console cursor movement by outputting to the
console device the required escape sequences.  Each function requires a
pointer to the IOStdReq structure created either 1) by your calling program
or 2) by the field_open function and pointed to by the WriteReq pointer in
your FieldHeader structure.  With all of these cursor movement functions, if
the cursor moves past the end of the current line, it will appear at the
beginning of the next line.  Or if the cursor moves back past the beginning
of the current line, it will appear at the end of the previous line.  Also be
careful, because if the cursor moves back past the beginning of the display
or forward past the end of the display, the entire display will scroll to
make room for a previous or next line to which the cursor moves.


void cursor_invisible( wreq )
    struct IOStdReq *wreq

    This function renders the cursor invisible.


void cursor_jump_left( wreq, positions )
    struct IOStdReq *wreq
    int positions

    This function moves the cursor positions character positions to the left
    on the console display.  A value for positions less than 0 or greater
    than 999 will cause unexpected results.  Because of the nature of the
    console's cursor movement commands, a value of 0 for positions will
    default to 1.



void cursor_jump_right( wreq, positions )
    struct IOStdReq *wreq
    int positions

    This function moves the cursor positions character positions to the right
    on the console display.  A value for positions less than 0 or greater
    than 999 will cause unexpected results.  Because of the nature of the
    console's cursor movement commands, a value of 0 for positions will
    default to 1.


void cursor_left( wreq )
    struct IOStdReq *wreq

    This function moves the cursor one character position to the left on the
    console display.


void cursor_place( wreq, x, y )
    struct IOStdReq *wreq
    int x
    int y

    This function moves the cursor such that the upper left corner of the
    cursor is located at the xth horizontal pixel position and the yth
    vertical pixel as measured from the upper left corner of the window.
    Note that the upper left corner of the window (at the top of the title
    bar just to the left of the close gadget) is pixel position (0,0).


void cursor_pos( wreq, row, col )
    struct IOStdReq *wreq
    int row
    int col

    This function moves the cursor to the rowth row (horizontal rows) and
    colth column (vertical columns) relative to the top and left edges of the
    console display, respectively.  The top edge of the console display is
    initially defined as the eleventh vertical pixel position (the twelfth
    pixel), or the second pixel below the window's title bar.  This may be
    changed, however, with the con_top_offset() function.  The left edge of
    the console display is initially defined as the fourth horizontal pixel
    position (the fifth pixel), but may be altered with the con_left_offset()
    function.


void cursor_right( wreq )
    struct IOStdReq *wreq

    This function moves the cursor one character position to the right on the
    console display.


void cursor_visible( wreq )
    struct IOStdReq *wreq

    This function renders the cursor visible.



Miscellaneous Console Functions

These are console-handling functions that do not fit into any of
the above categories.


long con_open( window, wreq, rreq )
    struct Window *window
    struct IOStdReq *wreq
    struct IOStdReq *rreq

    This function opens the console device, returning the value CONSOLE_ERROR
    as defined in console/console.h if the console device could not be
    opened.  You need to pass a pointer to the window, and to the window's
    read and write requests as opened either manually or by the field_open()
    function in your calling program.


void console_close( header )
    struct ConsoleHeader *header

    This function closes the console device and deletes the console's read
    and write requests and ports.  You can open all of the devices, ports,
    and requests required for console operation using the console_open()
    function.  However, if you decide to open these devices manually, be sure
    to fill the ConsoleHeader structure with the correct pointers before
    calling this function or the system will crash.

int console_input( header )
    struct ConsoleHeader *header

    This function attempts to read from the console device, returning the
    first character read.  If more than one character was read, the
    subsequent characters are discarded.  This function is useful for console
    programs where you handle your own input and output.  You can also use
    this function to monitor input from "noisy" requesters--requesters which
    have the NOISYREQ flag set which allows console input to be monitored.
    Thus you can create a yes/no requester that allows the use of either the
    mouse of keyboard shortcuts.

    This function will return the following based on the input:

        displayable characters
            The ASCII value of the character itself will be returned.

        cursor controls
            The cursor codes as defined in console/console.h will be
            returned.  They include: CON_CURSOR_UP, CON_CURSOR_DOWN,
            CON_CURSOR_LEFT, CON_CURSOR_RIGHT, CON_SHIFT_UP (which is the
            up-arrow key and the SHIFT key pressed simultaneously),
            CON_SHIFT_DOWN, CON_HELP, and CON_SHIFT_TAB.

        control keys
            This function will return the sum of CON_CONTROL (as defined in
            console/console.h) and the ASCII value of the character pressed
            simultaneously with the control key.

        function keys
            This function will return the values CON_F1 through CON_F10 as
            defined in console/console.h corresponding to function keys F1
            through F10, and values CON_SHIFT_F1 through CON_SHIFT_F10
            corresponding to function keys F1 through F10 pressed
            simultaneously with the SHIFT key.

        no character or unrecognizable character
            This function will return zero if no characters are read or if
            the code returned is not recognized by this function (which would
            most likely indicate an error condition of some sort).  Strangely
            enough, pressing CTRL-(hyphen) also returns zero.

        miscellaneous keys
            The codes as defined in console/console.h for the remaining
            miscellaneous keys may also be returned.  They include:
            CON_BACKSPACE, CON_DELETE, CON_ESCAPE, CON_ALT_ESCAPE, CON_HELP,
            and CON_RETURN.

        masked keys
            Note that you can mask out certain characters from input using a
            mask.  If the user inputs a masked-out character, zero will be
            returned.

    WARNING: The ALT-space combination returns the code 0xa0 which is
    accepted by the console_input() and field_input() functions.  Because
    ALT-space does not produce alternate imagery but does produce a different
    ASCII value, you may wish to eliminate this from the functions, either by
    checking for it explicitly or by changing the displayable character test
    in the console_input() and field_input() functions to buffer[where] >=
    0xa1.

    Note that not all characters and key combinations are accessible through
    the console device.  ONLY the following keys are:

        all of the lower ASCII characters (space through ~)
        all of the upper ASCII characters accessible through ALT-key
            combinations
        the TAB and shifted-TAB keys
        the ESCape, BACKSPACE, DELETE, RETURN, and HELP keys
        the arrow keys and shifted-arrow keys
        the function keys and shifted-functions keys
        the ALT-space and CTRL-RETURN keys
        all alphabetic control keys except:
            CTRL-h which is an equivalent for BACKSPACE
            CTRL-i which is an equivalent for TAB
            CTRL-j which is an equivalent for CTRL-RETURN
            CTRL-m which is an equivalent for RETURN
            CTRL-{ which is an equivalent for ESCape

    Thus, if you want more key combinations such as ALT-arrow keys or access
    to the Commodore-Amiga keys, you will have to use RAWKEY input instead.
    For a complete list of all possible return codes, see the "Keyboard
    Chart" section of this manual.


int console_open( window, header, buffer )
    struct Window *window
    struct FieldHeader *header
    UBYTE *buffer

    This function opens all of the devices, requests, and ports required for
    console operation.  This function returns 0 (or CONSOLE_OPEN_OK as
    defined in console/console.h) if everything was successfully opened, or a
    flag defined in console/console.h if an error occurred.  If an error
    occurs, you must shutdown your program immediately (and as gracefully as
    possible).  Note that the pointers themselves in the ConsoleHeader
    structure serve as flags as to whether the devices were opened
    successfully.  As long as you have not manually modified these pointers,
    you may call the console_close() function anytime after calling the
    console_open() function and be assured only the correct devices will be
    closed.  Be sure to initialize all ConsoleHeader structures to
    INIT_CONSOLE_HEADER as defined in console/console.h in case your program
    terminates before the console_open() function is called.  Specifically,
    this function:

        - initializes the ConsoleHeader structure.
        - creates the write port required for the console device.  If this
              port could not be created, CONSOLE_EXIT_WPORT is returned.
        - creates the write request required for the console device.  If this
              request could not be created, CONSOLE_EXIT_WREQ is returned.
        - creates the read port required for the console device.  If this
              port could not be created, CONSOLE_EXIT_RPORT is returned.
        - creates the read request required for the console device.  If this
              request could not be created, CONSOLE_EXIT_RREQ is returned.
        - opens the console device, returning CONSOLE_EXIT_CONSOLE if it
              could not be opened.
        - performs an initial read which "primes" the buffer.  This initial
              read is essential before calling the console_input() function
              for the first time.

    The arguments for this function are:

        window
            This is a pointer to the window in which you open the console
            device.

        header
            Pointer to the ConsoleHeader structure to be used by the console
            device.  You must define one of these structures in your calling
            program for each console device you maintain.

        buffer
            This is a pointer to the input buffer to be used by the console
            device.  You must define this in your calling program to be at
            least CONSOLE_BUFFER_SIZE bytes large (as defined in console/
            console.h).


Field Buffer Functions

These functions operate on the input buffers of the specified field.  The
operations are performed at the BufferPos character position of the buffers
pointed to by Buffer.  In each case, you pass a pointer to the field whose
buffer you want modified.


void buffer_char_delete( field )
    struct Field *field

    This function deletes a character in the BufferPos character position in
    the Buffer of the specified field.


void buffer_char_insert( field )
    struct Field *field

    This function moves all characters at and to the right of the BufferPos
    character position in the buffer of the specified field one character
    position to the right so that a character may be inserted.  The character
    to be inserted is NOT done so by this function.



Field Mask Functions

These functions are used to create and modify masks used to filter console
and field input.  For more information on masks, see the definition of the
FieldMask structure.  Each of the functions requires a pointer to the mask
you wish to modify, instead of the field using the mask.  This is because
many fields can share the same mask.  The functions also require a set
argument, which should be set to either MASK_ENABLE or MASK_DISABLE (defined
in console/fields.h) depending on whether you want to enable or disable the
specified characters from being input.  Note that this argument is an
unsigned long integer.


void mask_chars( mask, string, set )
    struct FieldMask *mask
    UBYTE *string
    ULONG set

    This function either enables or disables the characters in the null-
    terminated string pointed to by string.  Some examples:

        mask_chars( &yn_mask, "YNyn", MASK_ENABLE )
            ...for a simple single-character yes/no field
        mask_chars( &date_mask, "0123456789/- ", MASK_ENABLE )
            ...for a date field or social security number field


void mask_entire( mask, set )
    struct FieldMask *mask
    ULONG set

    This function either enables or disables the entire ASCII character set.
    Or, instead of using this function, you may pre-initialize a mask by
    setting the mask equal to MASK_ENTIRE_ENABLED or MASK_ENTIRE_DISABLED as
    defined in console/fields.h.


void mask_range( mask, low, high, set )
    struct FieldMask *mask
    UBYTE low
    UBYTE high
    ULONG set

    This function allows you to enable or disable a range of ASCII characters
    from low to high, inclusive.  For example:

        mask_range( &upper_mask, 'A', 'Z', MASK_ENABLE )
            ...to allow only upper-case alphabetic characters
        mask_range( &digit_mask, '0', '9', MASK_ENABLE )
            ...to allow only numeric digits
        mask_range( &alpha_mask, 'A', 'Z', MASK_ENABLE )
        mask_range( &alpha_mask, 'a', 'z', MASK_ENABLE )
            ...to allow only alphabetic characters

    Notice from the above example, you can make multiple mask function calls
    to configure a mask to your specifications.  You can also mix the
    different functions and different set flags.



Low-Level Field Functions

These functions are used to manage and display the field output.  They handle
all field calculations required, such as updating the NumChars and BufferPos
parameters, and then they call the low-level console functions to move the
cursor and display the field contents.  Unless you are handling your own
field I/O, your program will not need to call these functions because the
field_input() function will accept your input and handle the output for you.
Most of the functions require a pointer to the field on which you want to
perform the operation (usually the current field) and a pointer to the
console's write request as opened either manually by your program or by the
field_open() function.  To make these definitions easier to comprehend, even
though these functions are not necessarily performed on the current active
field (the field in which the cursor is located), their definitions will
assume they are.

There are a few definitions which need to be made:

    current buffer position
        This is the position in the field where the cursor would appear if
        the field was active.  It is stored in the BufferPos parameter of the
        Field structure.  Note that because BufferPos describes the current
        location in the field's buffer (which is a string, or in other words,
        just an array of characters), the first character occupies buffer
        position zero.  All manipulations done to the field's buffer is
        correspondingly displayed in the field on the screen.

    beginning of the field
        This is simply the beginning of the field, in other words, the first
        character position, and BufferPos will equal zero.

    absolute end of the field
        This is the position in the field where the cursor rests when the
        maximum number of allowed characters (MaxChars) has been entered into
        the field.  Note that because MaxChars is the length of the field
        including the terminal null, BufferPos will always be less than or
        equal to MaxChars - 2 (minus one because of the terminal null and
        minus another because BufferPos starts from zero).

    current end of the field
        If the field is not completely full, the current end of the field is
        one character position to the right of the position occupied by the
        last character currently in the field.  For example, if the field
        contains the word "Smart" (without the quotes), then NumChars (which
        is the number of characters currently in a field) will equal 5.  The
        last character in the field (the 't') occupies buffer position 4,
        therefore the current end of the field will be buffer position 5.
        Note that if the field contains trailing blanks, the end of the field
        may appear to be past the last character in the field.

        On the other hand, if the field is completely full, the cursor is
        considered to be at the absolute end of the field.  Since the cursor
        cannot extend past the absolute end of the field, the cursor will
        remain in the last character position in the field even after a
        character has been typed there.  If you are in typeover mode, you can
        continue typing, and each character you type will just be written
        over the last character in the field.

One more note: when the user performs a field function that is not allowed,
the screen will flash.  This is accomplished by calling the intuition.library
DisplayBeep() function, as defined by FLASH_SCREEN in console/console.h.  You
may substitute your own warning procedure if you wish.


void field_char_backspace( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function deletes the character under the cursor and moves all
    characters to the right of the cursor one character position to the left
    to fill in for the deleted character.  If the cursor is at the beginning
    of the field, the screen will flash, indicating that there are no
    characters to the left of the cursor to delete.


void field_char_delete( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function deletes the character under the cursor in the specified
    field.  If there is no character under the cursor (in other words, the
    cursor is one character position to the right of the last character in
    the field) or if the buffer is empty, then the screen will flash
    indicating that there is no character to delete.


void field_char_type( field, wreq, character, mode )
    struct Field *field
    struct IOStdReq *wreq
    UBYTE character
    int mode

    This function outputs the specified character to the specified field at
    the current cursor position.  mode is the typing mode, either
    INSERT_TYPE_MODE or TYPEOVER_TYPE_MODE as defined in console/console.h.

    If the mode is TYPEOVER_TYPE_MODE (the default), character is displayed
    at the cursor, replacing the character currently in that position, if
    any, and the cursor moves one character position to the right.  If the
    cursor is at the absolute end of the field, character will replace the
    last character in the field, but the cursor will not move, remaining over
    the character just typed.

    If the mode is INSERT_TYPE_MODE, character is inserted at the cursor,
    moving all characters at and to the right of the cursor one character
    position to the right to make room for the inserted character.  If the
    field is full, the screen will flash, indicating that there is no more
    room to insert any characters.


void field_copy( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function copies the current contents of the specified field to the
    field clip.  If the field is empty, the screen will flash indicating that
    there are no characters to be copied.  This function has an added
    safeguard that makes sure it doesn't copy more characters than the clip
    can handle.  The clip is initially defined in console/fields.h to be 80
    (FIELD_CLIP_SIZE) characters long, which is perhaps the longest single-
    line field you could have on a screen.  Note that all of the field
    functions assume a single-line field.


void field_cursor_left( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function moves the cursor to the beginning of the specified field.
    If the cursor is already at the beginning of the field, the screen will
    flash.


void field_cursor_right( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function moves the cursor to the current end of the specified field.
    If the cursor is already at the current end of the field, the screen will
    flash.


void field_cut( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function copies the current contents of the specified field to the
    field clip, then deletes the contents of that field.  This is
    accomplished by first calling the field_copy() function, and then calling
    the field_delete() function.  If the field is already empty, the screen
    will flash indicating that there are no characters to be cut.


void field_delete( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function deletes the entire contents of the specified field, copying
    the contents of the buffer to the UndoBuffer so that the field contents
    may be restored by the field_restore() function.  If the field is already
    empty, the screen will flash, indicating that there are no characters to
    delete.


void field_delete_backward( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function deletes the contents to the left of the cursor in the
    specified field, moving the cursor and the character under the cursor to
    the first position in that field.  All characters to the right of the
    cursor are also moved left to fill in for the deleted characters.  If the
    cursor is already at the beginning of the field, the screen will flash,
    indicating that there are no characters to the left of the cursor to be
    deleted.


void field_delete_forward( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function deletes the contents of the specified field under and to
    the right of the cursor.  The cursor will not move.  If the cursor is
    already at the current end of the field, the screen will flash,
    indicating that there are no characters to the right of the cursor to be
    deleted.


void field_dup( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function replaces the contents of the specified field with the
    contents of the DupBuffer.  If the DupBuffer is empty, the screen will
    flash, indicating that there are no characters to duplicate.  The
    DupBuffer remains intact, for it is maintained only by the field_clear()
    function.


void field_left( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function moves the cursor to the beginning of the specified field.
    If the cursor is already at the beginning of the field, the screen will
    flash.


void field_paste( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function replaces the contents of the specified field with the
    contents of the field clip.  If the contents of the field clip are longer
    than MaxChars - 1 characters, only MaxChars - 1 characters will be
    copied.  If the field clip is empty, the screen will flash, indicating
    that there are no characters to be pasted.


void field_restore( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function replaces the contents of the specified field with the
    contents of the UndoBuffer.  If the UndoBuffer is empty, the screen will
    flash, indicating that there are no characters to restore.  The
    UndoBuffer is filled with the contents of the Buffer every time the
    field_delete() or field_goto() functions are called.


void field_right( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function moves the cursor to the current end of the specified field.
    If the cursor is already at the current end of the field, the screen will
    flash.


void field_tab_backward( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function moves the cursor TAB_JUMP (as defined in console/console.h)
    character positions to the left in the specified field.  If the cursor is
    fewer than TAB_JUMP character positions from the beginning of the field,
    the cursor will just be placed in the beginning of the field.  However,
    if the cursor is already at the beginning of the field, the screen will
    flash, indicating that the cursor cannot move any further to the left.


void field_tab_forward( field, wreq )
    struct Field *field
    struct IOStdReq *wreq

    This function moves the cursor TAB_JUMP (as defined in console/console.h)
    character positions to the right in the specified field.  If the cursor
    is fewer than TAB_JUMP character positions from the current end of the
    field, the cursor will just be placed in the current end of the field.
    However, if the cursor is already at the current end of the field, the
    screen will flash, indicating that the cursor cannot move any further to
    the right.



Field Display Functions

These functions are used by your calling program to display entire fields or
lists of fields.  All of the functions require the following arguments:

    struct FieldHeader *header
        This is a pointer to the header structure used by all of the field(s)
        you wish to display, so that they can access the window structure and
        the console's write request.

    struct Field *first
        With these functions, you can display a single field or a sub-list of
        the entire field list for a window.  You pass to these functions a
        pointer to the first field in the sub-list you wish to display, which
        may not necessarily be the first field in the window's list.

    UINT count
        This is the number of fields you wish to display, or
        -1 if you want to display all fields until the end of the list (in
        other words, field->NextField is NULL).  The functions will display
        count number of fields or until the end of the field list, whichever
        comes first.  The number of fields actually displayed (which of
        course would be less than or equal to count) is returned.

        UINT is typedef'd in toolkit/toolkit.h as an unsigned integer.  When
        you specify count as -1 to display to the end of the list, the UINT
        declaration changes -1 to 65536, which cannot be reached with the
        integer field counter in each of the functions.  Thus, the entire
        list is displayed.

    struct Field *place
        This is a pointer to the field in which you want to place the cursor
        after the fields are displayed.  If you just want to display the
        fields but not make any field the current field, set this pointer to
        NULL.  WARNING: These functions leave the cursor invisible in the
        last field displayed, but do not update the CurrentField pointer in
        the header structure.  Therefore, if you specify place as NULL, you
        MUST call the field_goto() function before calling any of the field
        I/O functions (especially field_input()), otherwise the display may
        become corrupt.


int field_clear( header, first, count, place )
    struct FieldHeader *header
    struct Field *first
    UINT count
    struct Field *place

    This function clears the contents of the fields in the list, placing the
    current contents of each field in the field's DupBuffer (if it has one).
    The field contents are cleared using the graphics.library RectFill()
    function, clearing from Left,Top to Right,Bottom with the BackPen color.
    This function also calls the SetAPen() function, so if you plan on doing
    your own rendering after this function, be sure to set the A Pen back to
    your desired color.


int field_display( header, first, count, place )
    struct FieldHeader *header
    struct Field *first
    UINT count
    struct Field *place

    This function displays the contents of each field in the list.  Because
    it does not erase the current contents of a field, use this function only
    if the all of the fields are blank.  If you plan on changing a field
    which has existing input, use the field_redisplay() function.


int field_redisplay( header, first, count, place )
    struct FieldHeader *header
    struct Field *first
    UINT count
    struct Field *place

    This function deletes the current display of each field in the list,
    redisplaying each field based on its Buffer contents.  This function is
    extremely handy for formatted input fields.  For example, if you have a
    date field, you can allow the user to just type in the digits as mmddyy.
    Once the user presses RETURN, you can call this function to redisplay the
    field with the formatted date mm/dd/yy.  Do this by manually changing the
    contents of Buffer, then immediately calling this function.  Although the
    argument count will almost always be 1 for this function, it was provided
    for consistency with the other field display functions.


int field_refresh( header, first, count, place )
    struct FieldHeader *header
    struct Field *first
    UINT count
    struct Field *place

    This function displays the contents of each field in the list, plus
    renders each field's image, border, and title.  Because this function
    does not erase the current contents of a field, do not use it to
    redisplay a field whose contents have been changed.  Instead, use this
    function to 1) initially display a field or field list in a window and 2)
    to refresh the display of a field whose display may have been corrupted
    by window sizing or by your own graphic rendering.  Thus, if you have the
    REFRESHWINDOW flag set for your window, call field_refresh() BEFORE your
    BeginRefresh()/EndRefresh() function pair.  This is because
    BeginRefresh() locks layers which the console program uses to render its
    cursor.

    This function creates the field display in the following order:  1)
    renders the field's image, 2) border, 3) title, and 4) contents.  Note
    that any imagery under the field contents will be destroyed.

    This is also the only SmartFields function that determines the Right and
    Top edges of each field.  These parameters determine whether a field can
    be available for input, whether a field's contents may be displayed, and
    also sets the boundaries for field clearing and mouse clicks.  These
    parameters are calculated using the size of the window's default font,
    the size of the window's borders, and the size of the window itself.
    Therefore, if any of these factors change (such as after a window
    sizing), this function should be called.


int field_reshow( header, first, count, place )
    struct FieldHeader *header
    struct Field *first
    UINT count
    struct Field *place

    This function is identical to the field_redisplay() function, except that
    field_reshow() does not assume that each field has a Buffer.  As a matter
    of fact, this is the only SmartFields function that does not make that
    assumption.  You can use this function in a simple word processing
    program set up using SmartFields, for example.  In that situation, not
    every field would necessarily have input.



Miscellaneous Field I/O Functions

These three functions do not fit into any other category but are extremely
important.


struct Field *field_click( header, mouseX, mouseY )
    struct FieldHeader *header
    SHORT mouseX
    SHORT mouseY

    This function checks the entire field list corresponding to the specified
    header to see if the mouse was clicked in any of the fields.

    To monitor for mouse input, set the MOUSEBUTTONS IDCMP flag in your
    window structure.  When a MOUSEBUTTONS input event has been generated,
    check the IntuiMessage structure's Code parameter.  If it equals
    LEFT_MOUSE_BUTTON as defined in console/fields.h, call the field_click()
    function.  This function will then return a pointer to the field in which
    the mouse was clicked and fill the BufferPos parameter in the supplied
    FieldHeader structure with the character position in that field where the
    mouse was clicked.  If the mouse was clicked outside all of the fields in
    the list, NULL will be returned.

    Note that this function does not call the field_goto() function.
    Therefore, it is entirely up to your calling program whether you want to
    move the cursor to the field in which the mouse was clicked.  If you do,
    you must call the field_goto() function yourself.  For more information,
    see the example program, e.c.

    The area occupied by MaxChars characters in the default window font is
    considered to be the field's edges when checking for mouse clicks.  In
    addition to just being clicked within the field's borders, this function
    also checks to make sure that the field is enabled.  Also, the entire
    field must appear within the visible portion of the window (the same
    requirement as for an active field).  If the mouse is clicked within a
    field but past the current end of the field, the current end of the field
    is returned in the BufferPos parameter.


void field_goto( header, field )
    struct FieldHeader *header
    struct Field *field

    This function moves the cursor to the BufferPos character position in the
    specified field, makes it the current field by storing its address in the
    CurrentField parameter of the header structure, and copies the current
    contents of the specified field to its UndoBuffer.  These contents can
    then be restored at any time with the field_restore() function.

    It is essential that you use this function to move the cursor from field
    to field because this function performs these "housekeeping" duties
    required for the smooth operation of the SmartFields system in addition
    to the above:

        - establishes the field's graphic rendition characteristics
        - sets the console line length
        - makes the cursor visible only if the specified field is entirely
              visible within the window


int field_input( header )
    struct FieldHeader *header

    This function handles all of the input in the SmartFields system.
    field_input() reads from the console device, performs any field output as
    necessary, and returns a code detailing what action was taken or needs to
    be taken by the calling program.  These return codes are defined in
    console/fields.h.  This function performs the following actions:

        - attempts to read from the console device, returning zero if no
              characters are read.
        - checks to make sure there is a current field.  If there is no
              CurrentField, FIELD_NO_CURRENT is returned.
        - checks if the CurrentField is contained entirely within the visible
              portion of the window.  If not, FIELD_OFF is returned.
        - checks if the character pressed is allowed according to the
              CurrentField's established mask.  If not, the screen flashes,
              and FIELD_SWALLOW is returned.  Remember, if no mask is
              specified, all input characters are allowed.

    If the function makes it past these checks, it may perform a field
    maintenance function.  This includes typing, inserting, or deleting
    characters in a field or moving the cursor within a field.  If such an
    action occurs (which requires no intervention from your calling program),
    the value FIELD_SWALLOW will be returned.  Because FIELD_SWALLOW is the
    most-often returned value, you should make this your first check in your
    calling program.

    This function may also return some values which require program response.
    Actually, response is not required, so it is up to you to decide to which
    field inputs you want to respond.  They include:

        cursor movements
            - FIELD_RETURN ..... <RETURN> or <ENTER> keys
            - FIELD_PREVIOUS ... up-arrow key
            - FIELD_NEXT ....... down-arrow key
            - FIELD_FIRST ...... shifted up-arrow key
            - FIELD_FINAL ...... shifted down-arrow key

        individual keys
            - FIELD_ESCAPE ..... <ESCape> key
            - FIELD_HELP ....... <HELP> key

        function keys
            FIELD_F1 through FIELD_F10 is returned when the function keys F1
            through F10 are pressed, and FIELD_SHIFT_F1 through
            FIELD_SHIFT_F10 are returned when the shifted function keys F1
            through F10 are pressed.



Field List Maintenance Functions

This final group of functions perform all of the background functions which
create, destroy, and maintain your field lists.


int field_add_list( header, position, add, count )
    struct FieldHeader *header
    UINT position
    struct Field *add
    UINT count

    This function allows you to add a sub-list of fields to the existing (or
    non-existing) list of fields maintained by the FieldHeader structure
    pointed to by header.  This function will attempt to add count number of
    fields in the field sub-list pointed to by add, placing the add field in
    the specified position in the existing list if possible.  The actual
    position in which the sub-list was added is returned.  Note that you can
    specify -1 for position to add the sub-list to the end of the existing
    list, or 0 or 1 to add the sub-list to the beginning of the existing
    list.  Specifying -1 for count will add the entire sub-list (until field-
    >NextField is NULL).  Your calling program is required, however, to
    display the added fields itself.


void field_close( header )
    struct FieldHeader *header

    This function closes the console device and deletes the console's read
    and write requests and ports.  You can open all of the devices, ports,
    and requests required for SmartFields operation using the field_open()
    function.  However, if you decide to open these devices manually, be sure
    to fill the FieldHeader structure with the correct pointers before
    calling this function or the system will crash.


void field_disable( header, field )
    struct FieldHeader *header
    struct Field *field

    This function disables the specified field, which means it is no longer
    available for input.  At this time, there is no visual indication to the
    user that this field has been disabled other than the user cannot enter
    data in it.  You may wish to notify the user on your own by removing the
    field's border (by setting the border's FrontPen equal to the window's
    default background color) or something similar.  If the specified field
    is the current field when you call this function, the CurrentField
    pointer in the FieldHeader structure is set to NULL, and the cursor
    disappears.  Be sure to call this function instead of manually setting
    the Enabled flag to allow for upward compatibility.


void field_enable( field )
    struct Field *field

    This function enables the specified field for input, but does not make
    this field the current field.  To make this field the current field, call
    the field_goto() function.


struct Field *field_link( final )
    struct Field *final

    When you pre-initialize field structures in your calling program, you set
    all of the PrevField pointers to point to the previous field listed.
    Pre-initialization, however, does not allow you to set the NextField
    pointers.  By supplying a pointer to the final field in a field list,
    this function steps through the list using the PrevField pointer and sets
    the NextField pointer for each field, including the NULL pointer for the
    final field.  A pointer to the first field in the list is returned.  This
    function is automatically called by the field_open() function.  If you
    open the required SmartFields devices yourself, however, be sure to call
    the field_link() function because many of the SmartFields functions
    require a valid NextField pointer.


int field_open( window, header, initial, final, buffer )
    struct Window *window
    struct FieldHeader *header
    struct Field *initial
    struct Field *final
    UBYTE *buffer

    This function opens all of the devices, requests, and ports required for
    SmartFields operation.  This function returns 0 (or FIELD_OPEN_OK as
    defined in console/fields.h) if everything was successfully opened, or a
    flag defined in console/fields.h if an error occurred.  If an error
    occurs, you must shutdown your program immediately (and as gracefully as
    possible).  Note that the pointers themselves in the FieldHeader
    structure serve as flags as to whether the devices were opened
    successfully.  As long as you have not manually modified these pointers,
    you may call the field_close() function anytime after calling the
    field_open() function and be assured only the correct devices will be
    closed.  Be sure to pre-initialize all FieldHeader structures to
    INIT_FIELD_HEADER defined in console/fields.h in case your program
    terminates before the field_open() function is called.  Specifically,
    this function:

        - initializes the FieldHeader structure.
        - links the fields using the field_link() function.
        - creates the write port required for the console device.  If this
              port could not be created, FIELD_EXIT_WPORT is returned.
        - creates the write request required for the console device.  If this
              request could not be created, FIELD_EXIT_WREQ is returned.
        - creates the read port required for the console device.  If this
              port could not be created, FIELD_EXIT_RPORT is returned.
        - creates the read request required for the console device.  If this
              request could not be created, FIELD_EXIT_RREQ is returned.
        - opens the console device, returning FIELD_EXIT_CONSOLE if it could
              not be opened.
        - renders the cursor invisible.
        - performs an initial read which "primes" the buffer.  This initial
              read is essential before calling the field_input() function for
              the first time.

    The arguments for this function are:

        window
            This is a pointer to the window to contain the field list.  Note
            that you can have many field lists per window (although only one
            is recommended), but only one window per field list.

        header
            Pointer to the FieldHeader structure to be used by the field
            list.  You must defined one of these structures in your calling
            program for each field list you maintain.

        initial
            This is the field which you want to make the initial current
            field.  You may set this to NULL.  See the example "Vendor
            Maintenance" program e.c as to how setting this field may be
            advantageous.

        final
            This is a pointer to the final field in the field list and is
            used for the field_list() function.

        buffer
            This is a pointer to the input buffer to be used by the console
            device.  You must define this in your calling program to be at
            least CONSOLE_BUFFER_SIZE bytes large (as defined in console/
            console.h).


int field_remove_list( header, remove, count )
    struct FieldHeader *header
    struct Field *remove
    UINT count

    This function allows you to remove a sub-list of fields from the existing
    (or non-existing) list of fields maintained by the FieldHeader structure
    pointed to by header.  This function will attempt to remove count number
    of fields from the field list beginning with the field pointed to by
    remove.  The actual number of fields removed is returned.  Note that you
    can specify -1 for count to remove all fields until the end of the list.
    If you happen to remove the current field, the CurrentField pointer in
    the FieldHeader structure is set to NULL, and the cursor disappears.  It
    is up to your calling program to clear the imagery of the removed fields,
    however.


Function Descriptions  01/13/90
© Copyright 1990 Timm Martin
All Rights Reserved Worldwide

/*-- END --*/