STRUCTURE DEFINITIONS struct Field ------------ This is the structure which all fields use. It has the following format: struct Field { struct Field *PrevField; struct Field *NextField; UBYTE *Buffer; UBYTE *UndoBuffer; UBYTE *DupBuffer; UBYTE FrontPen; UBYTE BackPen; UBYTE Style; UBYTE Enabled; struct FieldMask *Mask; USHORT Flags; SHORT Left; SHORT Top; SHORT Right; SHORT Bottom; SHORT MaxChars; SHORT NumChars; SHORT DispChars; SHORT BufferPos; SHORT DispPos; struct IntuiText *FieldTitle; struct Border *FieldBorder; struct Image *FieldImage; SHORT FieldID; APTR UserPtr; LONG Reserved1; LONG Reserved2; }; The individual elements are defined as follows: struct Field *PrevField This is a pointer to the previous field in your field list. Perhaps the easiest way to set up field lists is to pre-initialize them as global variables so that all routines in your program may access them. Unlike Intuition gadgets which should be defined in reverse order so that the NextGadget pointer points to an already defined gadget, you should define the fields in the order of cursor travel, linking them together with the PrevField pointer. Of course, the PrevField pointer for the first field in the list should be set to NULL. Then before you display the fields, you should call the field_link() function to set the NextField pointers. If you open your field devices with the field_open() function, however, this is done for you. struct Field *NextField This is a pointer to the next field in your field list. If you are pre-initializing your fields, set this field to LATER (which is defined in toolkit/toolkit.h as NULL) for all fields except the final field which can be set to NULL. This field is then filled in when you call the field_link() or field_open() functions. Because many of the SmartFields functions access this pointer, be sure to set this parameter immediately. UBYTE *Buffer This is a pointer to the null-terminated string which will hold the contents of the field. It should be defined to be at least as large as MaxChars to prevent the overwriting of succeeding locations in memory. All functions (except the field_reshow() function) expect this buffer to exist and will crash if this pointer is invalid. UBYTE *UndoBuffer This is a pointer to a null-terminated string which will hold the "undo" contents of the field. The contents of a field are copied into its undo buffer when the cursor first appears in the field or if the contents of the field are deleted with the field_delete() function. The contents of this buffer are then replaced into the field when the field_restore() function is called. This buffer does not have to be defined, but if it is, it should be defined to be at least as large as MaxChars to prevent the overwriting of succeeding locations in memory. If you do not wish to provide an UndoBuffer, set this pointer to NULL. Then if a user invokes a command which would require an UndoBuffer (such as CTRL-X and CTRL-R), the screen will flash indicating that the buffer does not exist. Because only one field at a time may be active, you may supply a single undo buffer for multiple fields. The buffer must be defined to be at least as large as the largest MaxChars value in any of the fields using this buffer. Because providing a single undo buffer for many fields can confuse the user, this method is not recommended. UBYTE *DupBuffer This is a pointer to a null-terminated string which will hold the contents of the field after the field has been cleared by the field_clear() function. Then upon invocation of the field_dup() function, the contents of this buffer will be copied into the field. This buffer does not have to be defined, but if it is, it should be defined to be at least as large as MaxChars to prevent the overwriting of succeeding locations in memory. If you do not wish to provide a DupBuffer, set this pointer to NULL. Then if a user invokes the dup command (CTRL-D) which requires the DupBuffer, the screen will flash indicating that the buffer does not exist. UBYTE FrontPen This is the foreground color of the field characters. This has nothing to do with the color of the text in the field title which you specify in the IntuiText structure, however. The FrontPen can be any value from 0 to 7, and other values may produce strange results. Only values 0 through 3 are valid for fields in windows rendered in the Workbench screen. These values represent the colors blue, white, black, and orange, respectively, with the default Workbench settings. UBYTE BackPen This is the color of the background of the field characters. This parameter must have the same values as listed above for the FrontPen. Note that if the FrontPen and BackPen are equal, the field text will be invisible. If you set the BackPen equal to a color other than the background color of the window, the field_clear() function renders a square the size of the input field in the BackPen color. Use the graphic rendition test program to view this effect. UBYTE Style This is the style of the field text. Use the flags as defined in console/console.h: CON_PLAIN, CON_BOLD, CON_ITALIC, CON_UNDERSCORE, CON_INVERSE. You can also OR the flags to produce a combined effect. For example: CON_ITALIC | CON_UNDERSCORE will create an underlined- italic style. UBYTE Enabled This flag determines whether input is accepted into this field. Use the FIELD_ENABLED and FIELD_DISABLED flags as defined in console/ fields.h to provide for upward compatibility. Do not change this flag manually. Instead, use the field_disable() and field_enable() functions. struct FieldMask *Mask This is a pointer to the input mask for the field. See the FieldMask structure definition for more information. If this is set to NULL, then no input checking is done and all input characters are accepted. USHORT Flags This field is not used at this time, but was provided for future use. For upward compatibility, set this field to 0 and do not modify it. SHORT Left, Top These contain the horizontal and vertical window pixels of the upper left corner of the first character in the field. See the "Field Layout" section for more information. SHORT Right, Bottom These contain the calculated horizontal and vertical pixels of the bottom right end of the field. You may initialize these values to zero because the field_refresh() function calculates these based on the maximum number of characters allowed in the field and the size of each character according to the tf_XSize and tf_YSize parameters contained in the IFont structure pointed to in the Window structure. SHORT MaxChars This is the maximum number of characters including the terminal null that may be input into this field. Thus, there will be no more that MaxChars-1 characters visible in the field at any time. Be sure to define all buffers used by this field to be at least MaxChars long. Once set for a field, this value should not be modified until the field is removed from the window. SHORT NumChars This is the current number of characters in the field's buffer not including the terminal null. Thus, this value will always be less than MaxChars (because MaxChars will always be at least one character larger because of the terminal null). Do not modify this value in the calling program. If you wish to change the contents of a field, change the contents of the Buffer, then call the field_redisplay() function. SHORT DispChars This is the number of characters currently visible in the field. This is not currently used but was provided for upward compatibility. Initialize this parameter to zero and do not modify it. SHORT BufferPos This is the current cursor position in the Buffer of the field. Note that the first character in the field occupies BufferPos zero (because the buffer is a string). A value does not imply that the field is currently active. The currently active field is pointed to by the CurrentField parameter in the FieldHeader structure. The BufferPos value is stored even after the cursor has left this field so that when the cursor returns, it will return to the exact position it was in when it left. Warning: do not modify this value. Use one of the cursor positioning functions instead. SHORT DispPos This parameter is not currently used but was provided for upward compatibility. Initialize this parameter to zero and do not modify it. struct IntuiText *FieldTitle This is a pointer to an IntuiText structure which will be displayed as the field title by the field_refresh() function. If you wish no title, set this pointer to NULL. If you desire more than one title, link the text together using the NextText pointer in the Intuitext structure. The text will be rendered in reference to the Left and Top edges of the field. struct FieldBorder *FieldBorder This is a pointer to a Border structure which will be rendered in reference to the Left and Top edges of the field. If you do not want a border, set this pointer to NULL. If you want more than one border, link the borders together using the NextBorder pointer in the Border structure. struct Image *FieldImage This is a pointer to an Image structure which will be rendered in the window's rastport in reference to the Left and Top edges of the field. If you do not want an image, set this pointer to NULL. If you want more than one image, link the images together using the NextImage pointer in the Image structure. The field_refresh() function renders the field in the following order: images, borders, title, field text. SHORT FieldID This field is provided for your own use to label and identify the fields. The most common use of this field is in switch statements. This parameter is ignored by SmartFields. APTR UserPtr This is a pointer provided for your own use. This parameter is ignored by SmartFields. LONG Reserved1, Reserved2 These parameters were provided for future expansion. Initialize these parameters to zero and do not modify them. struct FieldHeader ------------------ This structure should be globally defined in your calling program, one structure for each set of fields in a window. Note that you can have multiple sets (lists) of fields for each window (although only one is recommended), but you can have only one window per field list. If you elect to open the devices required for console use yourself, be sure to place their pointers in this structure so that the SmartFields functions can use them. The FieldHeader structure has the following format: struct FieldHeader { struct Window *Window; struct MsgPort *WritePort; struct IOStdReq *WriteReq; struct MsgPort *ReadPort; struct IOStdReq *ReadReq; LONG ConsoleError; UBYTE *Buffer; struct FieldMask *Mask; SHORT TypeMode; APTR UserPtr; LONG Reserved1; LONG Reserved2; struct Field *FirstField; struct Field *FinalField; struct Field *CurrentField; SHORT BufferPos; }; The individual elements are defined as follows: struct Window *Window This is a pointer to the window containing the fields. Note that you cannot link fields from different windows in the same list. It is the responsibility of your calling program to open and close the window. struct MsgPort *WritePort struct IOStdReq *WriteReq struct MsgPort *ReadPort struct IOStdReq *ReadReq These are the message ports and read/write requests that need to be set up for the window's console device. This is all handled by the field_open() and field_close() functions if you wish to let SmartFields do the dirty work for you. The field_open() function sets these values to NULL then attempts to open each one. The field_close() function then attempts to close each device with a non- zero pointer. LONG ConsoleError This is a flag containing the success of opening the console device for the window. If the device could not be opened or has not been opened, it will contain the value of CONSOLE_ERROR as defined in console/console.h. The field_open() and field_close() functions will open and close the console device if you choose. UBYTE *Buffer This is a pointer to the buffer which is used for console input. It is the responsibility of the calling program to declare a buffer of at least CONSOLE_BUFFER_SIZE as defined in console/console.h to be used by the SmartFields program. This buffer is handy because you can also use it for any other function in your calling program that needs a very temporary buffer. By "very" we mean that any call to a SmartFields function may trash its contents. struct FieldMask *Mask This is a pointer to the input mask used by the console_input() function to filter input. See the FieldMask structure definition for more information. If you specify NULL for this parameter, no input checking will be done and all console input will be accepted. If you wish to mask out input for individual fields, use the Mask parameter in the Field structure. SHORT TypeMode This is the current type mode, either INSERT_TYPE_MODE or TYPEOVER_TYPE_MODE as defined in console/console.h. In Insert type mode, all characters you type are inserted in the field at the current cursor position, and all characters at and to the right of the cursor are moved one character position to the right to make room for the character typed. The cursor does not move. If you attempt to type in a field that is full, the screen will flash indicating that there is no more room to insert characters. This is the mode that the Intuition string gadgets use. In typeover mode, however, all characters you type replace the character under the cursor, and the cursor moves one character position to the right. If the field is full, the character you type just replaces the final character in the field. This is initialized for you by the field_open() function. APTR UserPtr This is a pointer provided for your own use and is ignored by SmartFields. LONG Reserved1, Reserved2 These variables are provided for future expansion. struct Field *FirstField This contains a pointer to the first field in the field list. This is automatically filled in by the field_open() function. struct Field *FinalField This contains a pointer to the final field in the field list. struct Field *CurrentField This contains a pointer to the current field in the field list. If there is no current field, then this pointer will be NULL. SHORT BufferPos This is a storage variable used to pass values between the field_click() function and your calling program. See the field_click() function description for more information on its use. struct FieldMask ---------------- This structure is used by the field_input() function to determine if the character typed is accepted in the current field. You define a FieldMask structure for each field in which you wish to restrict input. Normally a field will accept any displayable character as input. If you wish to restrict the field's input in any way, for example limiting it to only alphabetic or numeric characters, you would define a FieldMask structure for that field and set the Mask parameter of the field's Field structure equal to the address of the mask you create. More than one field may share the same mask. The FieldMask structure has the following format: struct FieldMask { ULONG Element[MASK_ELEMENTS]; }; MASK_ELEMENTS is defined in console/field.h as 8. Thus there are 8 long integers of 32-bits each or 256 total bits in the FieldMask structure, which just happens to correspond to the number of ASCII characters. While it is true that not all 256 ASCII characters are displayable, having this format allows the mask creation and verification functions to use bit shifts instead of time-consuming multiplication and division. Upon user input, the field_input() function checks to see if the current field has a mask. If it does, it checks whether the bit in the mask corresponding to the character input has been set to 1. If it has (and there is room for the character in the field), the character is placed in the field. If the corresponding bit is set to zero, then the screen will flash. Note that this applies only to displayable characters and not to any control code or function key. This structure can also be used by the console_input() function to restrict all console input. You define a FieldMask structure and record its address in the Mask parameter of either the FieldHeader or ConsoleHeader structure (depending on which structure you are using). struct ConsoleHeader -------------------- The elements have the same meaning as in the FieldHeader structure. They have the following format: struct ConsoleHeader { struct Window *Window; struct MsgPort *WritePort; struct IOStdReq *WriteReq; struct MsgPort *ReadPort; struct IOStdReq *ReadReq; LONG ConsoleError; UBYTE *Buffer; struct FieldMask *Mask; SHORT TypeMode; APTR UserPtr; LONG Reserved1; LONG Reserved2; }; Notice that the ConsoleHeader structure is actually a subset of the FieldHeader structure. This means that you can pass a pointer to a FieldHeader structure to any SmartFields function that is expecting a pointer to a ConsoleHeader structure (but NOT vice-versa). Structure Definitions 01/13/90 © Copyright 1990 Timm Martin All Rights Reserved Worldwide /*-- END --*/