Piper's Pit BBS/FTP: ibm 0020 - 0029/ibm0020-0029/ibm0028.tar/ibm0028/CSCAP321.ZIP/READ.ME

Text File | 1990-12-20 | 99.9 KB | 2,616 lines

                             C-scape 3.2 read.me

        Copyright (c) 1990, Oakland Group, Inc.  All rights reserved.









CONTENTS:

1:  INTRODUCTION

2:  EXAMPLE PROGRAMS
    2.1: cscape
    2.2: demofm
    2.3: demomous
    2.4: demofram
    2.5: demoslug
    2.6: demosled
    2.7: demofsav
    2.8: demoflod
    2.9: demohelp
    2.10: demotty
    2.11: demomode
    2.12: graphics demo programs
    2.13: the C-scape demo

3:  WHAT'S BEEN FIXED

4:  WHAT'S NEW

5:  WHAT'S IMPROVED IN THIS RELEASE

6:  NEW FEATURES

7:  UPGRADING YOUR CODE
    7.1:  auxiliary functions
    7.2:  kb_Idle
    7.3:  ted_funcs
    7.4:  num_fexit
    7.5:  sled_Remap
    7.6:  topping seds
    7.7:  _arg macros

8:  NEW SLED FUNCTIONS

9:  NAMING SEDS

10:  THE NEW FEXIT

11:  USER-DEFINED SCANCODES

12:  NEW BOB FEATURES
    12.1:  Dependent bobs
    12.2:  Independent bobs

13:  NEW AUXILIARY FUNCTION INFORMATION

14:  HIGHLIGHTING FIELD CHARACTERS

15:  KB_IDLE
    15.1:  Converting your old code

16:  OAKLAND DEBUGGING AID

17:  MEMORY USE AND THE SIZE OF EXECUTABLES

18:  A FEW OAKLAND CODE CONVENTIONS
    18.1:  OGLOBAL and OEXTERN
    18.2:  static and OSTATIC
    18.3:  FNULL

19:  ERROR CODES

20:  OAKLAND GROUP BBS

21:  FORTHCOMING FROM OAKLAND

22:  UPDATES TO THE MANUAL
    22.1:  Updates To The 3.1 Manual
    22.2:  Updates To The 3.0 Manual
    22.3:  Updates To The 3.0 Manual Addendum

23:  ERRATA FOR THE MANUAL
    23.1:  Errata For The 3.1 Manual
    23.2:  Errata For The 3.0 Manual
    23.3:  Errata For The 3.0 Manual Addendum



1:  INTRODUCTION

    Thank you for purchasing C-scape 3.2!

    This document is the READ.ME for C-scape.  It updates and supplements the
    C-scape Manual and Function Reference.  This document contains information
    essential to using C-scape.

    Please see your distribution media for INSTALL.TXT.  INSTALL.TXT describes
    installation, compiling and linking for your particular operating system.

    For important information on using C-scape with graphics, consult the file
    GRAPHICS.TXT on your distribution media (DOS version and Apollo UNIX
    version, only).

2:  EXAMPLE PROGRAMS

    The following programs are included on your distribution media.  They
    demonstrate the use of various parts of C-scape.

    We hope that these programs will help you get to know C-scape better, that
    you tinker with them, and that you will use them as a code source from
    which you can cut and paste to your own C-scape application.

    Please refer to the installation document INSTALL.TXT to find out where
    these programs reside on your particular distribution.  See that same
    document for instructions on compilation and linking.

2.1: cscape

    CSCAPE.C is a simple data entry screen.  It is the "hello, world" of
    C-scape.

2.2: demofm

    DEMOFM.C is a sample program that demonstrates one of the recommended ways
    of handling a framer menuing system that is driven by both the mouse and
    the keyboard.  It demonstrates the detection of mouse double-clicks and
    button1-,  2-, or 3-down events.

    This example is one of the most important and powerful.  The control
    construct illustrated is one that employs quick-keys and framer menuing
    system selections to pass command message values to a controlling loop.
    Look & Feel uses this same mechanism.

2.3: demomous

    DEMOMOUS.C demonstrates the use of the mouse with C-scape.  If you have not
    installed a mouse driver, DEMOMOUS displays a message to that effect.

2.4: demofram

    DEMOFRAM.C demonstrates the framer menuing system.  Press any key to get
    started.  Press Escape from the top menu to leave.  Press F1 to get help on
    any item in the menu.  Makes use of the DEMOFRAM.HLP help file.

2.5: demoslug

    DEMOSLUG.C demonstrates the slug menuing system.  A popup window asks you
    if you wish to create a horizontal or vertical menuing system.  Press
    Escape from the top-most menu to leave.

2.6: demosled

    DEMOSLED.C demonstrates how to create a screen from several smaller
    screens.  It includes a scrolling, resizing list (sled), a notepad text
    editor (ted), and mouse support.  It stores and retrieves data from the
    ASCII file DEMOSLED.DAT.  Press Escape to leave the program.

2.7: demofsav

    DEMOFSAV.C demonstrates saving a screen to a screen file.  The screen
    "test" is saved to a file called "test.lnf". Use DEMOFLOD to load the saved
    screen file.

2.8: demoflod

    DEMOFLOD.C demonstrates loading a screen from a screen file.   It loads the
    "test" screen from the "test.lnf" screen file.  You must create this screen
    file by running DEMOFSAV or with Look & Feel.

2.9: demohelp

    DEMOHELP.C is data entry screen that uses the C-scape help system to
    provide context sensitive help.  Press F1 to get help.  DEMOHELP.HLP is the
    accompanying help text file.

2.10: demotty

    DEMOTTY.C is an example of using a character map window to display text in
    a TTY-like fashion.  Consult the comment preface to this program for
    pertinent information about cmap windows.

2.11: demomode

    DEMOMODE.C is a small utility program for determining and changing the
    video mode on an IBM PC or compatible.  Compile and link DEMOMODE.C and
    then type "demomode -h" on the command line for instructions.

2.12: graphics demo programs

    These programs are DEMOGRAF.C, DEMODRAW.C, DEMOGRAB.C, DEMOCLOK.C,
    DEMOSWAP.C, and DEMOPCX.C.  For more information on these programs, consult
    the file GRAPHICS.TXT on your distribution media (DOS version and Apollo
    UNIX version, only).

2.13: the C-scape demo

    The C-scape demo program appears in the distribution separate from the
    example programs.  It provides examples of various parts of the library,
    including windowing, menuing, graphics, idle functions, and mouse support.

3:  WHAT'S BEEN FIXED

     Please note that this is not a comprehensive list of the bugs we've
     fixed.  It mentions the more salient fixes to 3.1 that appear in 3.2.

     -   sdouble_fexit now makes valid use of the scratchpad.

     -   sfloat_funcs now properly validates the value of data entries that
         occur at the boundary of the validation range.

     -   double_funcs now employs the space key, the "e" key, and Backspace and
         Delete in accordance with the Function Reference description.

     -   hex_funcs now have a calculator-style entry and employ the space key
         to clear the field.

     -   long_funcs no longer truncate the entry after the first comma when
         using the "," format command.

     -   The behavior of the numeric formatting has been changed in an UPWARD
         INCOMPATIBLE manner.

         Fixed decimal formatting invoked through placing a digit 1-9 in a
         field's format string has been rewritten.  Now, the position of an
         existing decimal point is preserved and the number of digits to the
         right of the decimal point is affected by the format string.  If there
         are more digits to the right of the decimal point than are specified
         in the format string, then the extra digits are used to round the last
         specified digit and the extra digits are discarded.  If there are less
         digits to the right of the decimal point, then the number is padded
         with 0's to the specified number of digits.

     -   Attribute changes can now be effected on the trailing '\n' of a
         menu_Printf statement.

     -   Problems with failing _fexits when scrolling with the mouse have been
         remedied.

     -   You can now move from the last field of an embedded sed into the next
         field in the parent sed when pressing ENTER without exiting the parent
         sed.  The exception is if the embedded sed uses menu_funcs or
         gmenu_funcs.  Selecting an item from an embedded menu exits the
         nesting parent sed(s) so that the choice may come out of sed_Go.

     -   ted_LeftWord now works correctly.

     -   We fixed a bug in the sfile_ code that would render a screen in a file
         unreadable if the screen contain over 1000 characters of text.  The
         sfile_ code routines automatically repair previously damaged files.

     -   You can now call sed_Repaint to repaint a sled or to repaint a sed
         that nests a sled.  You no longer need to additionally call
         sled_Repaint.  This also solves the problem wherein an embedded sled
         with space between the column fields would allow the parent sed to
         bleed through when painted.

         Note that you must call sed_Repaint after you load a sled with
         sled_SetColVar and before you call sed_Go.  If you do not do this, the
         sled will appear to have trash in its fields until you enter the sled
         and do something which scrolls the sled.  If you call sed_Repaint
         before you _Go, things will be fine.

     -   tm_Now, tm_Copy and tm_Zero, routines in TMNOW.C, have been rewritten
         and no longer refer to the globals tm_result and result.  This stops
         them from generating undefined error variables when they are used
         apart from the other Tm_ modules.

     -   Mouse handlers now return the mouse code MOU_NOFIELD when the mouse is
         clicked over a sed but not in a field (as is documented in the
         manual).

     -   Field formatting now occurs before field validation in field fexit
         functions.

     -   The record position of the first active field is now correctly set for
         the case in which you add fields to a sed that was opened with an
         empty menu.

     -   The help system now strips the '\n' from border titles.

     -   Framers now use the help system in the manner described in the manual.

     -   We fixed the values of some pseudo-scancodes (like BOB_ codes, for
         example) that conflicted with DOS keyboard scancodes.

     -   Video modes 0 and 1 now work on a CGA display.

     -   We have fixed problems with the handling of names for deleted fields.

     -   Black and white PCX files now load correctly on a multi-plane display.

     -   We have fixed some problems involving the painting of children and of
         shadows; and with the color of the cursor in graphics mode.

4:  WHAT'S NEW

    These are library features added to version 3.2 from 3.1:

     -   There are several new auxiliary messages.  See the section on NEW
         AUXILIARY FUNCTION INFORMATION for a detailed discussion of this
         topic.

     -   kb_Idle has been changed in an UPWARD INCOMPATIBLE manner.  See the
         section on KB_IDLE for more information.

     -   Each menu of a slug menuing system now has sedmou_GreedyTrack as its
         default mouse handler.  slug_fkey now has a check for MOU_CLICK.

     -   HELP_KEY is a new scancode we have defined for use on systems that
         have a dedicated help key.  (FN1 still works to call the help system.)

     -   C-scape now supports the keys FN11 and FN12.

     -   C-scape's source code now uses ANSI-C style function declarations.
         This makes it possible to use C-scape with new C and C++ compilers.
         (For UNIX we have added a "de-ANSI-fy" option to our unarchiving
         utility, which converts the source back to K&R style C.)

     -   menu_Printf now uses either varargs (older C) or stdargs (ANSI) to run
         on platforms such as the DG Aviion, Sun 4, and other RISC systems that
         do not use a stack-based parameter passing mechanism.

     -   The OS/2 version now supports the use of multiple threads.  Refer to
         the OS/2 section of the DOS version of INSTALL.TXT.

     -   C-scape has a new border, bd_mouse2, which has the same functionality
         as bd_mouse, along with a horizontal scroll bar.

     -   The ocountry_struct now contains two additional pieces of information,
         both of which are strings that appear for end users.  The first is
         ocountry.errmsg, which contains the error message that a field
         function displays when it fails; by default, this string is "Invalid
         Entry".  The second is ocountry.helpxrefmsg, which appears at the
         bottom of cross-referenced help windows; by default, this is "Press
         Esc to leave help, Backspace for previous help screen".

         You can change either of these by setting the structure member equal
         to a new value.  For instance, to change the error message for San
         Bernardino, placing the following piece of code into your application:

             ocountry.errmsg = "Sorry, dude, no way.";


     -   The pop_ functions now use a new structure, popparms_struct (defined
         in POPDECL.H).  This structure has four elements:

             int shadow;
             byte shadowattr;
             int height;
             int width;


         The shadow element is an int that declares the size of the popup's
         shadow; shadowattr sets the color of the popup when a shadow is cast
         on it; height and width set the default values for the popup windows.
         The default shadow is 0 characters wide; its default shadow color is
         0x08 (grey on black); its default height is 10; and its default width
         is 20.

         You can change any of these values by setting the structure member
         equal to a new value.  For instance, to change the default shadow size
         of popups, place the following piece of code into your application:

             popparms.shadow = 1;   /* gives the popup a 1 char shadow */


     -   You can now have a cursor in cmap window.  See DEMOTTY.C for more
         information.

     -   The numeric field functions no longer call senter or sexit in the
         fexit function.  This means that the value in the field is not written
         out to the variable until sexit is called for all the fields as
         control leaves the sed.  This allows you to use spc_Abort with numeric
         field functions.  Note that this is an UPWARD INCOMPATIBILITY if your
         code assumes that variables contain correct information as soon as
         control leaves each field.  If you wish numeric field functions to
         operate as they did in C-scape 3.1 (updating the field variable during
         fexit), then define DOSEXIT and recompile FNHEX.C, FNSFLOAT.C, and
         FNSTDVAL.C.

     -   win_Grab is a new function for use with PMAP windows.  It saves the
         portion of the video display that corresponds to the window into the
         window's PMAP.   See section 2.3 of GRAPHICS.TXT and refer to the
         demograb.c example on your distribution media (DOS version and Apollo
         UNIX version, only).

     -   You can now have multiple Display Managers and switch between graphics
         and text modes.  See section 2.5 of GRAPHICS.TXT.  Also, refer to the
         example demoswap.c that is provided on your distribution media (DOS
         only).

     -   seds can now be named.  sed_SetName, sed_GetName, and sed_Find are new
         functions.  See the section NAMING SEDS in this document.

     -   You can now highlight one of the first 16 characters of a field and
         use that character for menu selection searches.  This involves several
         new functions and a new menu_Printf command ("@fh").  See the section
         HIGHLIGHTING FIELD CHARACTERS in this document.

     -   For increased flexibility, we have removed the sed_Top call in the
         mouse handlers.  If you click on an occluded window (sed) it is not
         brought automatically to the top.  If you wish to top the window (sed)
         then attach the aux_Top auxiliary function to that sed or call sed_Top
         in your own auxiliary function (when it receives the WINA_STARTGO
         message).

     -   aux_Top is a library auxiliary function that tops a window when it
         receives the WINA_STARTGO message.

     -   pop_Edit, pop_Menu, pop_Prompt, and pop_View are now mouse-sensitive.
         Press the Escape key or click the mouse outside the popup to remove
         the pop up.  The mouse handler is sedmou_GreedyTrack.  Any border
         attached to these popups now has the BD_MOVE feature.  (Note that
         pop_Message and pop_Text are not mouse-sensitive because these popups
         are only painted to the display.  They have no fields to which to pass
         control and so sed_Go is never called on them).

     -   bob_funcs now allow you to attach independent, as well as dependent,
         bobs.  See the section on NEW BOB FEATURES of this document for
         details.

     -   Independent bobs now move when their parents are moved.  See the
         section on NEW BOB FEATURES for more information.

     -   The default row, column, height and width specifiers for the popups
         have been fixed so that you do not get a little tiny sed.

     -   We have re-written the mouse handlers and restructured our Greedy
         mechanism.

         NOTE:  If you have a screen that needs Greedy mouse action and that
         screen has children (embedded screens) then the ultimate ancestor must
         have the Greedy handler (sedmou_GreedyTrack or sedmou_GreedyClick) and
         the children (however nested) must each have a non-Greedy handler
         (sedmou_Track or sedmou_Click).

         The exception to this is slug_funcs.  Every slug screen gets a Greedy
         handler.  slug_Open handles this automatically, but if you want to
         create a slug yourself (by coding or in Look & Feel), make sure that
         it all has a Greedy handler.

     -   The framer menuing system mouse handler, sedmou_Track, now operates in
         click and drag mode; and is SAA compliant.

     -   We now have two new mouse handlers, winmou_GreedyTrack and
         winmou_Track, which allow use of the mouse on windows other than seds,
         such as pmap and cmap windows.  (winmou_GreedyTrack is a greedy mouse
         handler for dialogue boxes.)  To attach either to a window, use the
         new function win_SetMouse, which behaves identically to sed_SetMouse:

             win_SetMouse(win, winmou_Track);

         For more information on use of winmou_Track, see the file DEMOWRLD.C
         in the C-scape demo program.

5:  WHAT'S IMPROVED IN THIS RELEASE

    These are some of the changes in C-scape 3.2 that have made it more
    efficient than 3.1:

     -   You can now call sed_Repaint on a sled.  It is no longer necessary to
         explicitly call sled_Repaint on either a standalone sled or one
         embedded in a sed.  When a sled in involved, sed_Repaint includes the
         functionality that was previously only in sled_Repaint.

     -   Changing attributes in a menu_Printf now allocates a text block whose
         size is tailored to fit the text to which the attribute pertains.  It
         no longer allocates the full default minimum block size if it does not
         need to.

     -   ted_funcs no longer use the sed's generic data pointer as a pointer to
         the cut buffer.  They now use the field's second data pointer.  Note:
         this is an UPWARD INCOMPATIBILITY.

     -   The default minimum size of a text block in the text buffer has been
         reduced from 200 bytes to 22 bytes.  The growth strategy for text
         blocks has been changed to be more efficient.

     -   The built-in mouse handler for the framer menuing system,
         sedmou_Framer, is now SAA compliant.

     -   Text editing is more efficient.

     -   sled_Remap now returns an int instead of a boolean.  SED_MOVED,
         SED_INVALID, and SED_STUCK are the possible return values, instead of
         TRUE and FALSE (as it used to).  This routine returns SED_MOVED if it
         is successful (where it used to return TRUE); SED_INVALID if the user
         has entered invalid data and the current field's fexit fails (where it
         used to return FALSE); and finally, it returns SED_STUCK if it is
         unable to scroll the sled (where it used to return FALSE).  Note: this
         is an UPWARD INCOMPATIBILITY.

     -   sled_SetColVar and sled_InsertRows are more error-resistant.

     -   sled_SetColVar now returns a boolean value indicative of whether or
         not it was successful.  (The most likely cause of failure would be the
         lack of memory to expand the sled column data array.)

6:  NEW FEATURES

     In addition to the functions listed below, please consult the following
     additional sections in this document.  They contain new functions not
     described here:.



         Section to consult               functions new to C-scape 3.2



         HIGHLIGHTING FIELD               sed_SetHiColors
         CHARACTERS                       sed_GetHiRegAttr
                                          sed_GetHiSelAttr
                                          sed_SetFieldHiChar

         NAMING SLEDS                     sed_SetName
                                          sed_GetName
                                          sed_Find

         NEW SLED FUNCTIONS               sled_GetCol

         (separate document,              disp_GetCurrent
         GRAPHICS.TXT)                    disp_SetCurrent
                                          win_Grab

         (DEMOTTY.C, example program)     cmwin_GetResize
                                          cmwin_SetResize

     These functions are new to this C-scape release, 3.2:

     kb_CheckWait is a function called in C-scape field functions.

         boolean kb_CheckWait(wait)
             unsigned wait;  /* 100'ths of sec to timeout before returning */


     kb_CheckWait returns TRUE if a key or mouse event is ready; FALSE,
     otherwise.  A return value of TRUE means that the next call to kb_Read
     returns immediately.

     The wait parameter specifies how long kb_CheckWait waits for an event.  If
     the wait is 0, it returns immediately after checking; this is equivalent
     to calling kb_Check.  If wait is greater than 0, it keeps checking until
     wait hundredths of a second have elapsed.  If wait is -1, it keeps
     checking until an event is ready.

     kb_Stuff is a function that stuffs a scancode representing a keyboard or
     mouse event in an event stash.   The stash can only hold one event.  If
     you call this function repeatedly, only the last scancode stuffed is in
     the stash.  kb_Stuff is used so that the next time that kb_Read or
     kb_Check is called, the scancode that was stuffed into the stash is the
     scancode that is immediately returned.  kb_Stuff is equivalent to the old
     sed_SetMouseCode, but its name is more accurate.  It has the following
     prototype:

          void kb_Stuff(int scancode);


     There are two new bob_ functions in the library:  bob_IsParentMove reports
     whether or not a bob is set to be moved when its parent is moved.
     bob_SetParentMove sets whether or not a bob is moved when its parent is
     moved.

          boolean bob_IsParentMove(bob)
              bob_type bob;   /* TRUE if moves with parent; FALSE, if not */

          void bob_SetParentMove(bob, move)
              bob_type bob;
              boolean move;   /* TRUE sets to move with parent; FALSE, not */


    C-scape has several new field functions that are not listed in the manual.
    These are click_funcs, radio_funcs, and togint_funcs.

     field func        var type      description

     click_funcs       boolean *     Treats the field as a menu choice.
                                     Supports grid movement among fields.
                                     Pressing the first letter of a field or
                                     Enter selects that choice and exits the
                                     sed.

     radio_funcs       boolean *     Allows for the exclusive selection of one
                                     field from a group of fields, each of
                                     which has the same field name.  Requires
                                     at least one writeable position.

     togint_funcs      int *         Allows the user to cycle through a list of
                                     choices by pressing the space bar.  The
                                     field's second data pointer contains
                                     choice definitions.  Copies the number of
                                     the final choice into the field's
                                     variable.

     The menu_Printf code for click_funcs should be the same as that for
     menu_funcs.  The menu_Printf code for togint_funcs should be the same as
     that for toggle_funcs.

     Here is an example of radio_funcs in use:

       boolean choco, vanilla, cherry;

       /* . . . */

       menu_Printf(menu, "@f{flavor}[# chocolate]\n", &choco, &radio_funcs);
       menu_Printf(menu, "@f{flavor}[# vanilla  ]\n", &vanilla, &radio_funcs);
       menu_Printf(menu, "@f{flavor}[# cherry   ]\n", &cherry, &radio_funcs);



     The following functions were included in the previous release, but not
     documented.   They are presented here.

     nowrite_funcs is a new field function:

          OGLOBAL field_funcs_struct nowrite_funcs = {
              stdNoCur_fenter,
              std_fexit,
              menu_fkey,
              string_senter,
              FNULL,  VAR_STRING
          };

     This field function treats a field with an attached string variable as a
     menu choice.  It supports grid movement among fields and is identical to
     menu_funcs except it uses string_senter.  The text of the menu choice is
     determined by the contents of the field's string variable.  Hence, it can
     be changed at run-time but the user may not edit the field.  Upon exit the
     value of the field is not written back to the variable, but the baton
     value is equal to (field number + 1).


     disp_MapMono:

         VOID disp_MapMono(mono)
             boolean mono;

     If mono is TRUE this maps colors for mono displays.  Higher values are
     generalized as lighter than lower values, with the range being from 0-7
     (8-F are modulo-ed, but bolding and blinking are preserved) therefore:

         fore < back (e.g. 0x31) maps to 0x70
         fore > back (e.g. 0x25) maps to 0x07


     disp_ReInit:

         boolean disp_ReInit(dmode)
             dmode_fptr dmode;


     This routine installs a new display manager without closing down the
     window manager.  It restores the mode that existed prior to disp_Init,
     changes the display mode, and repaints the display.  You can use it to
     change from 25-line text mode to EGA 43-line text mode (or VGA 50-line
     text mode) and back:

         disp_Init(def_ModeText, FNULL);
         /* ... */
         disp_ReInit(pc_ModeEGA43);
         /* ... */
         disp_ReInit(def_ModeText);


     Do not use this to change from text mode to graphics mode.  See the
     example program DEMOSWAP.C for that.


     ufunc_Open:

         bob_type ufunc_Open(ufunc, idata)
             ufunc_fptr ufunc;
             int idata;


     This function creates a bob from a user function.  Returns the bob if
     successful; NULL if not.  The idata argument is a value that is passed to
     the user function upon invocation.  Look & Feel uses this construction in
     its generated code for framers and slugs.  See the chapter "NEW BOB
     FEATURES" in this document for more information about bobs.


     sed_GetCurrFieldData:

         VOID *sed_GetCurrFieldData(sed, datano);
             sed_type sed;
             int datano;


     Similar to sed_GetFieldData except that it refers to the current field.


     sed_IsFieldName:

         boolean sed_IsFieldName(sed, fld, name)
             sed_type sed;
             int fieldno;
             char *name;

     This function checks if field 'fld' in sed 'sed' has the name 'name'.  If
     the so, the function returns TRUE; otherwise, FALSE.


     sed_SetVarValue and sed_SetNameVarValue:

         boolean sed_SetVarValue(sed, fieldno, value)
             sed_type sed;
             int fieldno;
             VOID *value;

         boolean sed_SetNameVarValue(sed, name, value)
             sed_type sed;
             char *name;
             VOID *value;

     sed_SetVarValue copies data into the field variable according to its
     number.  It places the value 'value' in field number 'fieldno'.

     sed_SetNameVarValue copies data into the field variable. This function is
     useful when you wish to set the value of a field that has a name but where
     you don't know its variable (such as when you load screens from an
     sfile).  sed_SetNameVarValue sets the variable of the field named name
     equal to the value value.



7:  UPGRADING YOUR CODE

    If you are upgrading from C-scape 3.1 to C-scape 3.2, be aware that the new
    version contains several changes that are UPWARDLY INCOMPATIBLE.  This
    section explains how to update your code to run with the new version.  Make
    sure you completely replace ALL the C-scape header files and that you
    compile ALL your application's code with the new version.

7.1:  auxiliary functions

    Make sure your auxiliary functions return the value 1 for the default
    case.  Some of the new messages interpret a return value of 0 (zero) as
    equivalent to failure and perform an undesired action.  For example,
    returning 0 from a WINA_MOVE message prevents the window from being moved.

    The old SED_FENTER message is now treated as a SED_PREFENTER message.  The
    old SED_FEXIT message is now treated as a SED_POSTFEXIT message.  We have
    defined SED_FENTER to be SED_PREFENTER and SED_FEXIT to be SED_POSTFEXIT,
    so your existing code should compile without modification.  See the section
    "NEW AUXILIARY FUNCTION INFORMATION" for more information.

7.2:  kb_Idle

    You must make a minor change to your keyboard idle functions.  See the
    section on KB_IDLE for a detailed discussion of this issue.

7.3:  ted_funcs

    ted_funcs no longer use the sed's generic data pointer as a pointer to the
    cut buffer.  They now use the field's second data pointer.

    When you define the virtual field for your ted, you must ensure that it has
    at least two data pointers.  Do this with menu_Printf's "d" operator.  For
    instance:

    menu_Printf(menu, "@fd2[]", buffer, &ted_funcs, "This is a prompt string.",
        NULL);


7.4:  num_fexit

    The numeric field functions no longer call senter or sexit in the fexit
    function.  This means that the value in the field is not written out to the
    variable until sexit is called for all the fields as control leaves the
    sed.  This allows you to use spc_Abort with numeric field functions.
    However, your code may no longer work if it assumes that variables contain
    correct information as soon as control leaves each field.

    If you need to perform this action, use the following in an auxiliary
    function:

        case SED_POSTFEXIT:
            sed_DoFieldSexit(sed, sed_GetFieldNo(sed));
            break;


    This copies the record data to the field variable.

7.5:  sled_Remap

    sled_Remap now returns SED_MOVED, SED_STUCK, or SED_INVALID instead of TRUE
    or FALSE.  C-scape 3.1 code that tests the return value of sled_Remap, such
    as:

        if (sled_Remap(sled, 1)) {
            /* ... */


    is wrong.   For C-scape 3.2, you should update it to be:

        if (sled_Remap(sled, 1) == SED_MOVED) {
            /* ... */


7.6:  topping seds

    The function sed_Top is no longer in the mouse handlers.  To top a window
    (move it in front of others), attach the aux_Top auxiliary function to it
    or call sed_Top in your own auxiliary function (which tops it when it
    receives the WINA_STARTGO message).

7.7:  _arg macros

    C-scape 3.2 no longer uses the _arg macros in its header files to turn off
    function prototyping.  Instead, we convert our code from ANSI-style C to
    K&R-style C using the -d flag in the unark utility.  If you need to use the
    _arg macros include the file argmacro.h.

8:  NEW SLED FUNCTIONS

    You must include SLED.H to use any of the sled functions.

    Please note that the header file SLEDWIN.H is now named SLED.H.  If in your
    older code you had included BOBSLED.H for sled function use then you need
    make no changes--BOBSLED.H includes SLED.H.  If you had explicitly used
    SLEDWIN.H then change the references to SLED.H.

    New routines have been added to the library to allow the protection and
    marking of rows and columns in sleds (Scrolling List EDitors).  Protection
    and marking can be done independently of each other.  Every attempt has
    been made to keep the sled functions as close as possible to their field
    counterparts.

    Note:  In the following discussion, row refers to row in a sled's column
    array, not in the field grid.

    Any row or column can be protected using the appropriate function calls.
    Any changes to a row or column's protection status take effect the next
    time sled_Remap, sled_Repaint, or sed_Repaint is called.  If you protect
    the current row or column without moving out of it IMMEDIATELY afterward,
    you will still be able to edit the field; once you exit, however, you will
    not be able to return.  You must include SLEDPROT.H to use any of the sled
    protection functions.

    Marking can be added to a sled by using the sled_Mark and sled_Attr
    routines.  As with protection, changes take effect the next time
    sled_Remap, sed_Repaint, or sled_Repaint are called.  All rows and columns
    will be marked with the same regular and selected attributes.  The
    attribute can be changed or inspected with sled_SetMarkAttr and
    sled_GetMarkAttr.  The attributes are uninitialized, so you should call
    sled_SetMarkAttr before you mark anything.  Both protecting and marking can
    be done to any sled row or column, whether it is currently displayed or
    not.

    Here are brief descriptions of functions for these purposes.

    sled_GetMarkAttr returns the current marking colors by placing them in the
    variables regular and selected:

         void sled_GetMarkAttr(sed, regular, selected);
             sed_type     sed;
             byte    *regular;
             byte    *selected;


    sled_SetMarkAttr sets the sled's marking colors to the values in regular
    and selected:

         void sled_SetMarkAttr(sed, regular, selected);
             sed_type sed;
             byte regular;
             byte selected;


    The sled_IsMarked routines use the following routines to check the mark
    status of a row or column:

         boolean sled_IsMarkedRow(sed, row);
             sed_type sed;
             int row;

         boolean sled_IsMarkedCol(sed, col);
             sed_type sed;
             int col;


    The sled_Mark routines (actually function macros) mark or unmark a row or
    column in a sled:

         void sled_MarkCol(sed, col);
             sed_type sed;
             int col;

         void sled_UnMarkCol(sed, col);
             sed_type sed;
             int col;

         void sled_MarkRow(sed, row);
             sed_type sed;
             int row;

         void sled_UnMarkRow(sed, row);
             sed_type sed;
             int row;


    The following functions allow you to protect a sled row or column and check
    the protected status of a sled row or column.  You must include SLEDPROT.H
    to use any of the sled protection functions:

         #include <sledprot.h> /* must include for these */

         void sled_ProtectRow(sed, row);
             sed_type sed;
             int row;

         void sled_ProtectCol(sed, col);
             sed_type sed;
             int col;

         boolean sled_IsProtectedRow(sed, row);
             sed_type sed;
             int row;

         boolean sled_IsProtectedCol(sed, col);
             sed_type sed;
             int col;


    The two routines, sled_PageUp and sled_PageDown, have been added to ease
    scrolling within a sled that has fixed rows at its top.  Each remaps a sled
    up or down by the number of scrollable rows in it:

         int sled_PageUp(sled);
             sed_type sled;

         int sled_PageDown(sled);
             sed_type sled;

    Like sled_Remap, these functions return SED_MOVED, SED_STUCK, or
    SED_INVALID.

    The following routine has been added for consistency with sled_GetRow and
    returns the sled's current column number:

         int sled_GetCol(sled);
             sed_type sled;


9:  NAMING SEDS

    You can now name seds.  This is analogous to the ability to name fields.

    sed_SetName names a sed.  Use NULL for name to remove a window's name.
    (Note: sed_SetName returns an integer denoting a handle for the name of the
    object.  This handle is an entry in an internal system list and is not
    otherwise needed by the C-scape user.)

         int sed_SetName(sed, name)
             sed_type sed;
             char *name;


    sed_GetName returns a pointer to the given sed's name.

         char *sed_GetName(sed)
             sed_type sed;


    sed_Find finds a sed by its name.

         sed_type sed_Find(name)
             char *name;


    sed_Find returns a pointer to the named sed, if found; NULL, otherwise.
    You can assign more that one sed the same name but sed_Find returns a
    pointer to only one of them.  If the name is not unique, it returns a sed
    with the specified name, but not necessarily any particular one.

    When you name seds, their names go into an internal symbol list.  This list
    is not closed by disp_Close or sed_Close.  If you want to release the
    storage that this list uses, call the new function oak_Close after calling
    disp_Close.  In most cases, you do not need to call oak_Close.  It has the
    following prototype:

          void oak_Close(void);


10:  THE NEW FEXIT

    C-scape 3.2 has a new version of the fexit function.

    Previously, any fexit that performed validation would contain code similar
    to the following:

         if (!valid_String( /* ... */ ) {

             tone();
             sed_BorderPrompt(sed, fnstring_errmsg);

             /* wait for a keystroke */
             while (!kb_Check()) {
                 ;
             sed_BorderPrompt(sed, sed_GetCurrFieldData(sed, 0));
             return(FALSE);
             }
         }

    When the user enters an invalid value into a field, this code sends the
    user an error message and then sits in a loop, waiting for a keystroke.
    This method works but has two drawbacks: it wastes CPU time on
    multi-tasking operating systems and it limits options for programming a
    custom error response.

    To address these problems, C-scape now has been changed in two ways.
    First, the fexit behaves differently.  When it receives an invalid entry,
    it calls the following piece of code:

         if (!valid_String( /* ... */ ) {
             kb_Stuff(sed, KEY_INVALID);
             return(FALSE);
         }


    kb_Stuff pushes a keystroke back onto the buffer.  Because fexit returns
    FALSE, control stays in the field and the pending scancode (KEY_INVALID)
    gets grabbed by the function special_key within that field's fkey
    function.  (special_key is a standard part of every field function's fkey.)

    Here we see the second change to C-scape.  special_key has a new case for
    KEY_INVALID:

         case KEY_INVALID:
             /* The validation in fexit failed: tell the user */
             tone();
             sed_BorderPrompt(sed, ocountry.errmsg);

             /* wait for a keystroke */
             kb_CheckWait(-1);

             sed_BorderPrompt(sed, sed_GetCurrFieldData(sed, 0));
             break;


    kb_CheckWait waits for a keystroke without removing it from the keyboard
    buffer (unlike kb_Check, which returns immediately, whether or not there is
    a keystroke).  Note that kb_CheckWait takes an argument, which is the
    amount of time it waits for a keystroke in milliseconds.  The argument of
    -1 makes it wait until a key is pressed.

    This scheme allows for customization without manipulation of field
    functions.  You need only write a new special function based on
    special_key.  You need only change your code if you have already rewritten
    new the field functions to perform customization.

    Also note that the numeric field functions no longer call senter or sexit
    in the fexit function.  This means that the value in the field is not
    written out to the variable until sexit is called for all the fields as
    control leaves the sed.  This allows you to use spc_Abort with numeric
    field functions.  However, your code may no longer work if it assumes that
    variables contain correct information as soon as control leaves each field.

11:  USER-DEFINED SCANCODES

    C-scape now provides a new method of customizing behavior: user-defined
    scancodes.  You can define up to 256 of your own scancodes, all of which
    must have the form KEY_USER(N), where N is an integer between 0 and 255.

    To create a new scancode, perform #define with the same form:

         #define MY_CODE KEY_USER(22)

    This piece of code creates the custom scancode MY_CODE.  You can pass your
    scancode into the keyboard buffer with a call to kb_Stuff:

         kb_Stuff(MY_CODE);

    This action ends up passing MY_CODE to the next function that seeks a
    scancode, such as a special function.

    For an example of this type of action, see the above section (THE NEW
    FEXIT) and its use of KEY_INVALID.  For instance, you can use your own
    scancode with validation, where your custom code causes a KEY_INVALID-like
    response with whatever additions you like.

12:  NEW BOB FEATURES

    bob_funcs now support independent, as well as dependent, bobs.  There are
    two new bob functions: bob_IsParentMove and bob_SetParentMove.

    The information below on DEPENDENT bobs is to clarify the presentation of
    this subject in the manual.  The only new material is a description of a
    fix to a problem with the ENTER key.

    To review, the principal difference between dependent and independent bobs
    is that dependent bobs are automatically painted when their parent is
    painted and clipped within the edges of their parent.  By contrast,
    independent bobs must be painted explicitly and can appear outside of their
    parent's edges.  Control passes automatically into a dependent bob;
    independent bobs act as popups that appear when a user presses Enter or
    clicks the mouse on the bob_funcs field.

    The information below on INDEPENDENT bobs is new.

    12.1:  Dependent bobs

    Dependent bobs are painted when the parent is painted and are clipped
    within the parent window.  By default, they move with the parent.  When you
    enter the bob_funcs field, control passes immediately to it.

    To make a dependent bob from a sed, attach the library special function
    spc_Embed to it and call the sed_CreateBob function with the BOB_DEPENDENT
    flag.  If you do not give the child sed spc_Embed, then the UP, DOWN, TAB
    (to go right a field) and SHFT_TAB (go left) keys will only move you within
    the bob and not let you move into the parent.

    Here is a summary of the effect of certain events in the embedded sed
    (dependent bob) with spc_Embed attached:

    ESC                   Exits the bob and all ancestors.   The sed_Go that
                          was called on the ultimate ancestor returns 0.

    ENTER                 Moves to the next field in the bob.  If the current
                          field is the last field in the bob, then control is
                          passed to the field in the parent sed below the
                          bob_funcs field.  If there is no field below in the
                          parent sed, then control stays in the bob.

                          Note:  menu_funcs and gmenu_funcs fields in a bob act
                          differently.  In fields with these functions, ENTER
                          exits the bob and all ancestors.  The sed_Go called
                          on the ultimate ancestor returns the value of the
                          baton set by menu_funcs or gmenu_funcs.  See the
                          Function Reference for more information on these
                          field functions.

    UP, DOWN, TAB,        Passes control to the field above, below, to the
    SHFT_TAB              right, or to the left, respectively.  If the field to
                          move to is in the parent sed, control goes there.  If
                          there is no field to move to, control remains in the
                          field.

    mouse                 Moves freely between fields in the bob and in
                          parent(s).

                          Note:  You must use a non-Greedy mouse handler on a
                          dependent bob.



    12.2:  Independent bobs

    Independent bobs are not painted when the parent is painted, but are
    painted separately.  They are not clipped within the parent window.   Note:
    They now move with the parent.  The position of the bob can be set
    independent of the position of the bob_funcs field.

    When you enter the bob_funcs field, control does not immediately pass to
    the bob.  bob_fkey waits for the ENTER key or the mouse click before
    activating the bob.  If the bob is a sed, then the sed is painted to the
    display and run.  When the sed is exited, it leaves the display.

    Independent bobs can be made from seds or from user functions.  This
    feature means that attaching a user function (ufunc) to a field employs the
    same mechanism as attaching a a sed to a field.  Making a bob from a user
    function (as opposed to a sed) gives you a function button (since selecting
    the field executes the function).

    When you make an independent bob from a sed use the sed_CreateBob function
    with the BOB_INDEPENDENT  flag.  Do not attach the library special function
    spc_Embed to that sed, in contrast to dependent bobs.

    Here is a summary of the effect of certain events in the attached sed
    (independent bob).   It is assumed that spc_Embed is not attached to the
    bob.

    ESC                Exits the bob, removing it from the screen.  Control
                       returns to the bob_funcs field in the parent.

    ENTER              Moves to the next field in the bob.  If the current
                       field is the last field in the bob, control remains in
                       the bob.  If there is no field below in the parent sed,
                       then control returns to the bob_funcs field in the
                       parent sed.

                       Note:  menu_funcs and gmenu_funcs fields in a bob act
                       differently.  For fields with these functions, ENTER
                       exits the bob and all ancestors.  The sed_Go that was
                       called on the ultimate ancestor returns the value of the
                       baton set by menu_funcs or gmenu_funcs.  See the
                       Function Reference for more information on these
                       functions.

    UP, DOWN, TAB,     Moves to a field above, below, to the right, or to the
    SHFT_TAB           left, respectively.  Movement is restricted to the bob.
                       If there is no field to which to move, then it remains
                       in the current field.

    mouse              Moves freely among the fields in the bob.

                       Note:  You must use a Greedy mouse handler on the bob:
                       sedmou_GreedyClick or sedmou_GreedyTrack.   If you are
                       using a Greedy handler, then the first click outside the
                       bob dismisses the bob and returns control to the parent
                       seds bob field.



    When you make an independent bob from a user function, use ufunc_Open:

             bob_type ufunc_Open(ufunc, idata)
                 ufunc_fptr ufunc;
                 int idata;


    ufunc_Open creates a bob from a user function.  It returns the bob if it is
    successful and NULL if it fails.  When invoked, the user function receives
    idata value as its second argument.

    If a user function returns 0, control remains in the bob_funcs field in the
    parent sed.  Any other value exits the sed and be returned from sed_Go.

13:  NEW AUXILIARY FUNCTION INFORMATION

    Auxiliary functions are now part of the object instead of the sed.  This
    means that non-sed windows can use auxiliary functions.  Messages operate
    either at the object level (AUX_ messages, such as AUX_START), the window
    level (WINA_ messages, such as WINA_MOVE), or at the sed level (SED_
    messages, such as SED_PREFEXIT).  Each level has new messages:

            sed messages              SED_PREFENTER
                                      SED_POSTFENTER
                                      SED_PREFEXIT
                                      SED_POSTFEXIT

            window messages           WINA_STARTGO
                                      WINA_ENDGO
                                      WINA_GO
                                      WINA_MOVE
                                      WINA_RESIZE
                                      WINA_BORDERCLICK

            object messages           AUX_START
                                      AUX_END
                                      AUX_GETVALUE

    You can also define your own messages with the AUX_USER macro (see below).

    These messages are sent by C-scape to an object's auxiliary function, if
    present.

    The SED_PRE and POSTFENTER messages are sent before and after the fenter
    function is called for each field.  The old SED_FENTER message is now
    treated as a SED_PREFENTER message.

    The SED_PRE and POSTFEXIT messages are sent before and after the fexit
    function is called for each field.  The old SED_FEXIT message is now
    treated as a SED_POSTFEXIT message.

    The WINA_STARTGO message is sent whenever a window is activated, before
    control is passed to it (or, for a sed, any of the fields).  The following
    things can make a window active:

        -calling win_Go (or sed_Go)
        -passing control to it with the mouse
        -passing control to it with sed_SetNextWin

    The WINA_ENDGO message is sent whenever control leaves a window.  This
    occurs in the ways stated above.

    When you call win_Go on a non-sed window (i.e., a cmwin or pmwin), win_Go
    sends a WINA_GO message to a window.  The code for this message should
    handle input to the window (as does a C-scape fkey function).  For example:

    int aux_Hoohah(win_type win, int msg, VOID *indata, VOID *outdata)
    {
        boolean quit = FALSE;
        int baton = 0;

        switch(msg) {
        case WINA_GO:
            while (!quit) {
                kb_Read();
                /* do stuff here ... */
            }
            return(baton);
        /* ... */


    The return value of the auxiliary function is returned from win_Go (just as
    a baton value is returned from sed_Go).  Refer to the example program
    DEMOTTY.C for more information.

    The three WINA_ messages, WINA_MOVE, WINA_RESIZE, and WINA_BORDERCLICK, are
    sent when a window is moved, resized, or has its border clicked,
    respectively.  Note: Each of these messages has indata.

    For WINA_BORDERCLICK, the indata is a mev_struct (Mouse EVent STRUCTure).
    It is declared as follows:

        mev_struct *mevp;
        mevp = (mev_struct *)indata;

    The mev_struct contains information about a mouse event being sent to the
    border.  You can get information about a mev_struct with the various mev_
    macros available.  Consult the file mevdecl.h for more information on these
    macros, such as mev_GetRow or mev_GetCol.

    For WINA_MOVE and WINA_RESIZE, the indata is an "opoint", which is a data
    type used by the Oakland Windowing Library (OWL).  An opoint (Oakland
    POINT) describes the position of a point in pixel coordinates.  It contains
    the two elements:

        x      the horizontal position of the point, relative to the display

        y      the vertical position of the point, relative to the display

    These values are in opcoords, an Oakland data type.  An opcoord is an int
    that we use to describe signed pixel coordinates.

    The structure is defined as follows:


       typedef struct {
           opcoord x;
           opcoord y;
       } opoint;


    For WINA_MOVE, the indata is the position of the upper-left corner of the
    screen, relative to the display, in pixels; for WINA_RESIZE, it is the new
    height and width in pixels.

    The AUX_START message is sent when you call sed_SetAux.

    The AUX_END message is sent when you call sed_Close or, when you call
    sed_SetAux to attach another, new auxiliary function to a sed.   In the
    latter case the AUX_END message is sent to the existing auxiliary function
    and then the new function is attached and it gets a AUX_START message.

    AUX_GETVALUE is a message used by the forthcoming C-cell product.

    If you wish to define your own auxiliary messages, use the macro
    AUX_USER().  This macro takes an integer and supplies a unique auxiliary
    message value.  For instance:

           #define MY_MESSAGE          AUX_USER(0)
           #define MY_OTHER_MESSAGE    AUX_USER(1)

14:  HIGHLIGHTING FIELD CHARACTERS

    C-scape now lets you highlight any character in a field.  C-scape first
    searches the field for a highlighted; if the field has no highlighted
    character, it performs a search based on the field's first alphanumeric
    character.  The field functions for creating selection fields are
    check_funcs, click_funcs, framer_funcs, gmenu_funcs, list_funcs,
    mark_funcs, menu_funcs, and slug_funcs.

    You can highlight one of the first 16 characters of a field by giving it
    special regular and selected attributes.

    To set the highlighted character of a field, use menu_Printf's new 'h'
    operator.  The "@fh" command takes an integer value, starting with 0
    (zero).  For example, a menu_Printf in which a highlighted character is set
    might be:

        menu_Printf(menu, "@fh1[Explode]", filename, &framer_funcs);


    In this case, the highlighted character is the second character in the
    field, "x".

    To set the highlighted character for the selection items from a list_funcs
    list, place an "@" immediately before the character you wish to highlight.
    For instance, if your choices are blue, black, and brown, the string in
    menu_Printf should be: "@blue,b@lack,b@rown".

    To set or the change a field's highlighted character after opening the
    field's sed, you can use the sed_SetFieldHiChar function (see below).

    For framer and slug menu systems, you can set a menu item's highlighted
    character in the frame_def or slug_list definition structure.  To do this,
    place the "@" character before the character in the text of the menu choice
    you wish to designate as the highlighted character.

    For example, a fragment from a framer definition for a HELP menu:

         /* ... */

         {         "@HELP",           NULL,             12 },
         {         "A @Lot",          help_alot,         0 },
         {         "A @Bit",          help_abit,         0 },
         {         FRAME_END                               },

         /* ... */

    This definition designates "H" as the highlighted character the "HELP" menu
    and "L" as the highlighted character for the "A Lot" choice; "B" for the "A
    Bit" choice.



    sed_SetHiColors sets the highlighted character attributes.

         void sed_SetHiColors(sed, hreg, hsel)
             sed_type sed;
             byte hreg;  /* HiChar attr when field is not current */
             byte hsel;  /* HiChar attr when field is current */


    msys_SetHiColors sets the highlighted character attributes for all the seds
    within a framer or slug menuing system.

         void msys_SetHiColors(sed, hreg, hsel)
             sed_type sed;
             byte hreg;  /* HiChar attr when field is not current */
             byte hsel;  /* HiChar attr when field is current */


    sed_SetHiColors sets the regular and selected attributes of the highlighted
    character 'character' for the fields of a sed.

    sed_SetHiColors does not automatically update the display.   You must call
    one of the _Update or _Repaint functions to see the effect.

    sed_SetFieldHiChar selects or changes a highlighted character.

         void sed_SetFieldHiChar(sed, fldno, pos)
             sed_type sed;
             int fldno;  /* field number of field to affect */
             int pos;    /* position in merge of HiChar character */


    sed_SetFieldHiChar highlights a particular character in a field.  The field
    is specified by its field number (0 indexed).  The highlighted character is
    specified by an integer denoting the position of the character in the
    field's merge.   0 is the first character of a field's merge.  The
    highlighted character may be one of the first 16 characters in a field,
    where values in the range 0 to 15 may enable a highlighted character.  Use
    a value less than 0 to disable highlighting.

    This function does not automatically update the display.   You must call
    one of sed _Update or _Repaint functions to see the effect immediately.

    sed_GetHiRegAttr returns the highlighted character's regular attribute.

         byte sed_GetHiRegAttr(sed)
             sed_type sed;


    sed_GetHiSelAttr gets the highlighted character's selected attribute.

         byte sed_GetHiSelAttr(sed)
             sed_type sed;


    NOTE: You cannot both mark a field and highlight characters in it.

15:  KB_IDLE

    C-scape 3.2 has a new version of kb_Idle, that is UPWARD INCOMPATIBLE with
    kb_Idle from previous versions.  This section of this document completely
    replaces the discussion of kb_Idle in Section 18.3.1 of the C-scape 3.1
    manual and in Section 15.3.1 of the C-scape 3.0 manual.

    kb_Idle attaches a user-supplied function to the OWL keyboard handler.
    Whenever kb_Read or kb_Check are called, they call the user function
    repeatedly while waiting for a key to be pressed.  This function can
    provide limited "background" processing while waiting for keystrokes.

    The user-supplied function receives a message (which is an integer) and a
    wait parameter (which is an unsigned integer); it returns an integer.  It
    has the following form:

       #include "scancode.h"

       int idle_Func(msg, wait)
           int msg;
           unsigned wait;
       /*
           Standard Idle user-function.
       */
       {
           switch(msg) {
           case IDLE_START:
               /* ... */
               break;
           case IDLE_READ: /* called by kb_Read */
           case IDLE_CHECK:    /* called by kb_Check */
               /* ... */
               break;
           case IDLE_STOP:
               /* ... */
               break;
           }
           return(KEY_NONE);
       }

    The message passed to the idle function has one of the following values:

    IDLE_START        Passed to the idle function when it is first attached to
                      kb_Read.  The idle function should initialize any data it
                      uses when it receives this message.

    IDLE_READ         Passed to the idle function when it is called from
                      kb_Read.  The idle function should carry out its intended
                      work when it receives this message.

    IDLE_CHECK        Passed to the idle function when it is called from
                      kb_Check.  The idle function should carry out its
                      intended work when it receives this message.

    IDLE_STOP         Passed to the idle function when it is disconnected from
                      kb_Read.  The idle function should close down data it
                      uses when it receives this message.

    The function's wait parameter is useful on a small number of unusual
    platforms supported by Oakland Group; it is not relevant on most systems
    and can be ignored.

    kb_Idle returns a scancode value (an integer), which kb_Read receives.
    This value is returned from kb_Read unless it's KEY_NONE; KEY_NONE keeps
    control in kb_Read, which continues to wait for a keystroke (and calls the
    idle function in the mean time).  If the idle function returns a value
    other than KEY_NONE, kb_Read gets it and passes it on as if it were a
    regular scancode.

    You can use the return value of an idle function to inform your program of
    various events.  For example, if your idle function processes data between
    keystrokes, you can send a message to your program telling it that the data
    processing is completed:

       #include "kbidle.h"

       int idle_Slack(msg, wait)
       /* ... */

           case IDLE_CHECK:
           case IDLE_READ:
               /* test if our data is ready */
               if (dataisready()) {
                   /* it is, signal our program */
                   return(KEY_USER(0));
               }
               else {
                   /* it isn't, proceed normally */
                   return(KEY_NONE);
               }
            /* ... */

    With this construction, processing continues until finished, at which point
    the idle function exits.

    Calling kb_Idle with a FNULL argument or a new idle function sends an
    IDLE_STOP message to the current idle function and disconnects it from the
    kb_Read function.  The use of FNULL is new to C-scape version 3.1; see
    Section 16.3 of this document for more information.

    You can use the standard idle function, idle_Clock, supplied in the runtime
    libraries, to place a running time clock at the bottom of the display:


           kb_Idle(idle_Clock);

    You must initialize the device interface with disp_Init before using
    kb_Idle.  You must also include kbidle.h in the code where you call your
    idle function.

    Because it is called repeatedly, an idle function should be simple and
    fast.  A slow idle function could affect your program's performance.  On
    operating systems that support multi-tasking, such as OS/2, it does not
    make sense to use kb_Idle.  You should instead set up a real background
    process using the methods provided by the operating system.

15.1:  CONVERTING YOUR OLD CODE

    To convert your old idle function to a new idle function, do the following
    things:

    (1) make it return an int (instead of a void)

    (2) add a return statement in which it returns KEY_NONE

    (3) change the message IDLE_RUN to both IDLE_CHECK and IDLE_READ, so that:

       case IDLE_RUN:
           /* ... */

    becomes

       case IDLE_READ:
       case IDLE_CHECK:

    That's all you need to do.

16:  OAKLAND DEBUGGING AID

    This is not an example program but rather a debugging aid.

    To help in tracking down memory problems we have included a file called
    OAKMEMOK.C with the program examples.  The functions contained in
    OAKMEMOK.C replace the library memory handling routines used by C-scape.
    The C-scape library memory allocation routines are simple shells around
    calls to the C run time library allocators.  OAKMEMOK.C has some additional
    functionality:

     -   it places a guard byte before and after each block at the time of
         allocation;

     -   it keeps a linked list of each block that is allocated, with a tag
         that identifies which C-scape object has been allocated or freed; and,

     -   it checks the integrity of the guard bytes for each block of memory in
         the linked list whenever an allocation is made.

    To test memory allocation errors, use the function alloc_test.  The
    allocation routines use this function to perform the check of the linked
    list of memory blocks.  This function takes two arguments: a prompt and a
    mode.  alloc_test returns 0 if the heap is OK.  If one of the blocks has
    had its guard bytes overwritten then it returns the tag value of the bad
    block (which matches the block number of the corrupted block from the
    report).  Here is alloc_test:

        int alloc_test(char *msg, int mode)

    The msg variable holds a string.  When alloc_test prints a listing or dump,
    it prints this string, which allows you to determine the source of the bug
    from the calls to alloc_test.

    The value of mode determines the verbosity of the report:

    0   silent
    1   print summaries
    2   print dump list - the entire list of blocks and tags

    If there is a memory fault, alloc_test returns a value that

    alloc_test uses printf to print information.

    When the allocation routines call alloc_test, they pass a NULL msg and a
    mode 0.  If a bad block is detected, the allocation routine prints an error
    message noting the bad block's tag.  Again, printf prints the output.

    To use this routine, compile and link OAKMEMOK.C with your application.
    You must include the header DEBUG.H.

    (DOS users: if you are compiling under Microsoft, remember to pass the /NOE
    switch to the linker, so that references to the memory allocation routines
    are resolved by the functions in the OAKMEMOK.OBJ module, not the library.)

    If OAKMEMOK.OBJ is linked with your C-scape application code, every
    allocation automatically performs a check on the list of memory blocks and
    prints an error message if the check fails.

    To pinpoint the location(s) of your application's memory violations
    (usually caused by a bad pointer), you may need multiple calls to
    alloc_test.  Place calls to the function throughout the code, which will
    help you localize the error.  You may wish to compile the C-scape source
    modules pertinent to the error with the compiler debug switch set and then
    link these with your application--this will allow you to use a debugger to
    trace into the library and locate any memory that is being trashed there.
    You can use this method to track memory errors as in any code.

    Since alloc_test and other routines in OAKMEMOK.C use printf to perform
    output you can redirect this to an error output file by the DOS command
    line:

         myprogrm >myprogrm.err

    These routines will uncover most memory problems, but are fallible; if a
    memory block's contents have been damaged, but its guard bytes are intact,
    alloc_test will not detect a problem.  Despite this, OAKMEMOK.C is very
    useful for tracking down most memory errors.

17:  MEMORY USE AND THE SIZE OF EXECUTABLES

    C-scape and OWL are powerful libraries that do entail overhead.  The most
    simple C-scape application for DOS uses about 100K bytes, which comprises a
    kernel of windowing code.  As rough guide to a larger DOS application, you
    might consider the 370K bytes of Look & Feel (LNF).  LNF, by necessity,
    includes all the C-scape library functionality plus its LNF specific-code.

    While the base executable size is large, as your application grows the
    amount of C-scape code linked does not increase proportionally.  Most
    modules contain only one external function.  Also, the library uses
    function pointers to avoid linking unnecessary code.

    We understand that you may decide to use overlay linkage for large
    applications under DOS.  Nevertheless, we did not design C-scape or OWL for
    overlays and do not support this.  If you wish to use overlays, consider
    overlaying your application code (not the library code).  If you are using
    overlays and have questions, contact technical support for the manufacturer
    of your overlay compiler or linker.

    There are a few steps you can make to reduce your executable size.  If you
    know you are running only on particular display hardware (say, 80x25 text
    monochrome) then use pc_Mode7, not def_ModeText.  def_ModeText links in
    several drivers and choose among them at runtime.  Do not use a background
    window class if you do not need one.  The buffer allocated to store the
    entire screen is considerable, especially in graphics modes.  If you have
    many screens, you may wish to use screen files.  The library sfile code
    linked to your application may exceed what you save in your application
    code if you have only a few screens, however.  Close screens when you are
    finished with them and re-create them as necessary to use minimize memory
    use.

    We free what we allocate.  If you wish to examine the allocations made by
    the library you can use alloc_test to list the heap usage.  (See the
    section called OAKLAND DEBUGGING AID in this document).

    The most common routines in the library that make allocations are
    disp_Init, _Open calls, menu_Printf, sed_SetBorder, sed_SetTB, sed_Alloc,
    sed_InsertRows, running a ted or a sled, pop_ calls, and sfile_ routines.

    To roughly determine how much memory a sed will occupy, customize and run
    the following program:

    #include <stdio.h>
    #include <cscape.h>
    #include <sedwinod.h>

    #define NUMBEROFFIELDS 22 /* change this to the correct number of fields */

    void main() {
        printf("%d", sizeof(sed_xd) + sizeof(sedwin_od)
            + sizeof(struct menu_struct) +
            (NUMBEROFFIELDS * sizeof(struct field_struct)));
    }

    If you need the exact amount of memory used by a particular sed, determine
    it empirically.  You can do this by linking OAKMEMOK.C into your code and
    using alloc_test (with its verbosity level set to 2) before and after
    creating the sed, redirecting output to a file.  Compare the heap dumps and
    the amounts of memory used by the sed.

    If you anticipate nearing the limit of available memory, you should
    allocate a stash at the beginning of your application and free it when you
    need space to back out of an out-of-memory situation.  In addition, if you
    want an out-of-memory sed, allocate it at the start of the application and
    only repaint it as necessary.

    (DOS users: we do not supply a huge memory model version of the libraries.
    You can probably compile a huge model library without too much difficulty,
    but we are not able to support your efforts at this time.  We have a
    version of C-scape for the Phar Lap DOS|Extender and a version available
    for Rational Systems' DOS 16/M Extender, which allows you to use more than
    the standard 640K and compile in 386 protected mode.)

18:  A FEW OAKLAND CODE CONVENTIONS

    The following are some code conventions we use to insure code portability.
    While not required for DOS and OS/2, we suggest you incorporate such
    conventions into your C-scape application code for ease of porting to other
    operating systems.

18.1:  OGLOBAL and OEXTERN

    OGLOBAL is an Oakland storage-class specifier that is used in the
    definition of global data.  For example, to define a global variable called
    myint we write:

        OGLOBAL int myint;

        /* ... */

        myint = 5;


    If this definition occurs in one module and you wish to refer to the global
    data item in another module, then the other module must contain an external
    declaration.  For example:

        OEXTERN int myint;

        /* ... */

        if (myint == 5) {
            /* ... */
        }


    C-scape source makes extensive use of the OGLOBAL specifier in the .C files
    of C-scape and OWL, most notably before the definition of a particular
    field function's field_funcs_struct.

    Under most operating systems, DOS and OS/2 included, this OGLOBAL is
    defined by our headers to expand nothing; OEXTERN, expands to extern.
    However, the compilers of some operating systems, like VAX/VMS VAX C,
    require the definition of global data to use the keyword globaldef; and the
    external declaration, globalref.  Under such systems, the OGLOBAL and
    OEXTERN macros are defined in our headers to expand appropriately.

18.2:  static and OSTATIC

    static is a C language storage-class specifier used in the definition of
    data and functions.

    Some functions we wish to be public so that we can refer to them across
    modules.  Other functions we wish to be private; known only with in the
    module in which they are defined.  Private functions are defined as
    static.  The scope of a static function extends from the point of its
    definition in the source module to the end of the module.

    Because of the scope of static functions, we frequently declare the
    functions at the head of a module so that we may refer to the functions at
    any point in the source module, regardless of where they are defined.

    OSTATIC is an Oakland specifier that is used in the declaration of a static
    function.  Under most operating systems, the OSTATIC macro is defined to
    expand the static keyword.  The compilers of other systems may not allow
    the use  of the static keyword in a function declaration (only in its
    definition).  In this latter instance, OSTATIC expands to nothing.

    For example:

        /*
            ONE MODULE
        */

        OSTATIC int my_PrivateFunc(void);

        int my_PublicFunc(void)
        {
            return(my_PrivateFunc());
        }

        static int my_PrivateFunc(void)
        {
            return(5);
        }


        /*
            ANOTHER MODULE
        */

        extern int my_PublicFunc(void);

        int myint;

        /* ... */

        myint = my_PublicFunc();


18.3:  FNULL

    C-scape 3.2 library code now makes a distinction between a data pointer and
    a function pointer.  If you need to specify a null function pointer you
    should use FNULL instead of NULL.  Though Microsoft C, Turbo C, and most
    compilers for DOS, UNIX, and OS/2 don't require this distinction, compilers
    for other systems may.  You should do this for the sake of code
    portability.

    For example, where you used to write:

         disp_Init(def_ModeText, NULL);

    you should now write:

         disp_Init(def_ModeText, FNULL);


    Other pointers affected by this change include null pointers in references
    to borders, mouse handlers, user supplied functions, class functions,
    explode functions, auxiliary functions, special functions, and the
    component functions of field_funcs.

    Below is a summary of the functions or structures mentioned in the C-scape
    3.0 and 3.1 Manual Function References and in the C-scape 3.0 Manual
    Addendum that are affected by this:

         Those that deal with borders:

              - frame_Open
              - slug_Open
              - pop_View, _Edit, _Prompt, _Menu, _Message, _Text
              - the hx_struct or hv_struct that help_Init receives

         with mouse handlers:

              - sed_SetMouse

         user supplied functions:

              - kb_Idle
              - the slug_def structure that you pass to slug_Open
              - the frame_def structure that you pass to frame_Open
              - ufunc_Open

         class functions:

              - disp_Init

         explode functions:

              - sed_SetExplode

         auxiliary functions

              - sed_SetAux

         special functions:

              - sed_SetSpecial
              - sled_Open

         field_funcs component functions:

              - _senter
              - _sexit
              - _fenter
              - _fkey
              - _fexit

         In addition, the list of fsyminit_structs necessary for use with
         screen files is affected by this change.

         The fsyminit_struct has three members.  The first is a string, the
         second a function pointer, and the third a data pointer.  The type
         casts used for the last two members, as discussed in the manual, are
         (VOID_FPTR) and (VOID *).  Likewise, FNULL and NULL should be used
         when you wish to initialize these last two members of an
         fsyminit_struct list entry to a null value.

19:  ERROR CODES

    Error codes and messages are listed at the back of the C-scape Manual
    Function Reference.

    Codes you are unable to locate in the manual may be identified by
    consulting the source files CSERROR.H and OAKERROR.H.

20:  OAKLAND GROUP BBS

    Our BBS supports color ANSI screens.  Here is basic information to use it:

         BBS Phone Number:        [phone]

         Baud Rates               300, 1200 and 2400

         Line Protocol:           8  data bits
                                  1  stop bit
                                  No parity

         Download Protocols:      ASCII
                                  KERMIT
                                  XMODEM
                                  XMODEM-CRC
                                  YMODEM
                                  YMODEM/BATCH
                                  ZMODEM



    We encourage all to use the bulletin board as a forum by which to share
    C-scape ideas, comments and code.  If you have a problem and cannot solve
    it with the methods described above, call Oakland Group technical support.
    For more information on technical support, see the pamphlet "Oakland Group
    Technical Support and Training," which is part of the C-scape package.

21:  FORTHCOMING FROM OAKLAND

    As adjuncts to the C-scape Manual, two additional Oakland publications are
    mentioned in its Introduction.  Note that The Oakland Advanced Programming
    Guide and The C-scape Cookbook are both still under development.  The same
    is true of all references to C-Spot and C-Cell software.  All registered
    users of C-scape will be automatically notified when each of these items
    becomes available.

22:  UPDATES TO THE MANUAL

    In addition to this section, please consult the following sections of this
    document for updates to the manual:

         NEW FEATURES

         NEW SLED FUNCTIONS

         NAMING SEDS

         THE NEW FEXIT

         USER-DEFINED SCANCODES

         NEW BOB FEATURES

         HIGHLIGHTING FIELD CHARACTERS

22.1:  Updates To The 3.1 Manual

     -   Screen files now require that you include object class functions in
         the fsyminit_struct symbol table.  If you use seds, sleds and user
         functions and generated the screen files yourself, then you must add
         the following entries to your symbol table:

             { FSYM_CLASS },
             { "sedwin_Class",   (VOID_FPTR)sedwin_Class,    NULL },
             { "sledwin_Class,   (VOID_FPTR)sledwin_Class,   NULL }.
             { "ufunc_Class",    (VOID_FPTR)ufunc_Class,     NULL },


         Always include the entry of the delimiter "{ FSYM_CLASS }".

         If you purchased Look & Feel, it will automatically generate the
         fsyminit_struct symbol table for your screens and include the above
         classes appropriately.

     -   hex_funcs do not use a validation string.

     -   money_funcs and cmoney_funcs require at least 4 writeable positions.

     -   The use of menu_Printf (on a sed that you have already opened),
         sed_DeleteRows, sed_InsertRows, sed_DeleteField, sed_MoveField, or
         sed_SetTB can change the size of a sed's menu.  Borders with scroll
         lights or a scroll bar that reflect the menu size do not automatically
         update themselves.  To update the border, send it a scroll message.
         This does scroll the sed, but rather adjusts the border to the altered
         menu size.  Use this function:

              /* note that you give this function the sed as the 1st argument
              */
              bord_Do(sed, BDM_SCROLL, NULL, NULL);


22.2:  Updates To The 3.0 Manual

     -   The C-scape Manual Addendum is the principal update to the C-scape 3.0
         Manual.

     -   The integer values in the slug and framer menu definition structure
         should be positive and NON-ZERO (i.e., > 0).

     -   The border bd_exp no longer exists.  You can get the same results by
         using:

             sed_SetBorder(sed, bd_1);
             sed_SetExplode(sed, exp_std);


     -   Embedded seds must use spc_Embed to operate properly.

     -   The inner workings of sleds differ from their description in the
         manual (section 10.3.1).  Namely, spc_Sled does all the work of
         maintaining the sled.  The parent sed's field function, sled_funcs,
         does no sled work.  In fact, sled_funcs has been internally defined to
         be bob_funcs.  Because of these changes, sleds can also operate
         without being embedded.  To create an independent sled, after opening
         the sled with sled_Open, simply call sed_Repaint or sled_Repaint and
         sled_Go.  Refer to the source file spcsled.c for more information.

     -   hex_funcs do not use a validation string.

     -   money_funcs and cmoney_funcs require at least 4 writeable positions.

     -   Field formatting has a new command, c.  This command removes ALL
         whitespace from the field's record.

     -   The valid_String command code prefix {n}, for limiting the validation
         to the first n characters of the string, is valid for values of 0
         through 9.  A new command {s}, tells string validation to ignore ALL
         whitespace when making it's comparisons.  Example:  "{s}Hello" would
         validate "H e ll o ".

     -   The sed_Clear function no longer exists.

     -   The use of menu_Printf (on a sed that you have already opened),
         sed_DeleteRows, sed_InsertRows, sed_DeleteField, sed_MoveField, or
         sed_SetTB can change the size of a sed's menu.  Borders with scroll
         lights or a scroll bar that reflect the menu size do not automatically
         update themselves.  To update the border, send it a scroll message.
         This does scroll the sed, but rather adjusts the border to the altered
         menu size.  Use this function:

              /* note that you give this function the sed as the 1st argument
              */
              bord_Do(sed, BDM_SCROLL, NULL, NULL);


22.3:  Updates To The 3.0 Manual Addendum

     -   Screen files now require that you include object class functions in
         the fsyminit_struct symbol table.  You must add the following entries
         to your symbol table:

             { FSYM_CLASS },
             { "sedwin_Class",   (VOID_FPTR)sedwin_Class,    NULL },
             { "sledwin_Class,   (VOID_FPTR)sledwin_Class,   NULL }.
             { "ufunc_Class",    (VOID_FPTR)ufunc_Class,     NULL },


         Always include the entry of the delimiter "{ FSYM_CLASS }".  If you
         are using seds you need the sedwin_Class entry.  If you are using
         sleds then include the sledwin_Class entry.  If you are using slugs or
         framers include the ufunc_Class entry.

         If you purchased Look & Feel, Look & Feel will automatically generate
         the fsyminit_struct symbol table for your screens and include the
         above classes as appropriate.

     -   For code portability you should use FNULL as the second member of a
         fsyminit_struct, instead of NULL, if you need to specify a null
         function pointer.  A null third member, the data pointer, may be
         specified with NULL.  This is to insure compatibility with compilers
         that differentiate between data and function pointers.

     -   There is yet another border feature that you can enable with the
         sed_SetBorderFeature call:  BD_TOP.  Enabling this allows you to bring
         the window to the foreground by clicking the mouse on the border.

23:  ERRATA FOR THE MANUAL

23.1:  Errata For The 3.1 Manual

    The following are mistakes in the C-scape Manual and Function Reference.

       15    The last line of code on the page should use the attribute 0x70,
             not 0x07.  It should read:

                 menu_Printf(menu, "Before:Normal @a[%d] After:Reverse", 0x70);


       33    In the first sentence of the third paragraph "fields" should be
             "field":

                 The actual length of a field can be up to MAX_FIELD_LEN (1000)
                 characters long.


       45    At the top of the page the code fragment containing menu_Printf
             lack some needed quotes.  It should read:

                 menu_Printf(menu, "@f[%s]\n", NULL, &menu_funcs, p);


       52    The following should be added to the spc_Tone example:

                 #include <stdio.h>
                 #include <cscape.h>
                 #include <scancode.h>   /*  for F10 definition  */


       58    The last line of the code for the my_senter function should read:

                 sed_SetRecord(sed, sed_GetScratchPad(sed), fieldno);


       59    The last sentence of the third paragraph should omit "open,":

                 This saves the time it takes to close and reopen the sed.


       59    In section 5.13, Auxiliary Functions, the next to last sentence of
             the 2nd paragraph "before... Fenter" is duplicated.  It should
             read:

                 ...before each field's fenter functions, and after each field's
                 fexit function.

             Not:

                 ...before each field's fenter functions, and before each
                 field's fenter function.


       60    The aux_Standard code fragment has misplaced and missing
             semicolons. It should read:

                 int aux_Standard(sed, msg, indata, outdata)
                     sed_type sed;
                     int msg;
                     VOID *indata, *outdata;
                 {
                     switch(msg) {
                     case SED_PRESENTER:
                         /*  ...  */
                     }
                         return(TRUE);
                 }


       61    In the code fragment replace "MYMSG" with "MYSG_RESET".  It should
             read:

                 sed_DoAux(sed, MYMSG_RESET, NULL, NULL);


       63    The code example at the top of the page has a line which reads:

                 sed_MarkField(sed, fldno, reg, sel);


             The line should be:

                    sed_MarkField(sed, fldno, sel, sel);


             Also, "return(TRUE);" should be inserted between the last two
             closing curly braces.

       64    The line after this comment:

                 /* set value of field 1 (an integer, note cast) */


             should read:

                 *( (int *) sed_GetVar(sed, 1) ) = 22;


       66    sed_UnProtectField should be included in the see ref in the third
             sentence:

                 See sed_ProtectField, sed_IsProtectedField, and
                 sed_UnProtectField.


      158    The spc_Embed has a null case BOB_UP that falls thru to the UP
             case; BOB_DOWN falls thru to DOWN.  The cases for LEFT and RIGHT
             should be cases for SHFT_TAB and TAB, respectively.  Also the null
             cases BOB_LEFT and BOB_RIGHT fall thru to SHFT_TAB and TAB,
             respectively.  See the SPCEMBED.C source file in the C-scape
             library.

      160    The bob_fkey code given in the manual differs from the current
             implementation.  Please refer to the C-scape library source file
             FNBOB.C, instead.

      162    The first sentence beneath the diagram should read:

                 If you passed sed three to sed_GetAncestor it would return sed
                 two.


      176    The return statement of MyTed_fexit should be:

                 return(std_fexit(sed));


      180    The reference in the example MyTed_sexit to ted_RewindTB should be
             a reference to sed_RewindTB.

  184-185    The example code MyTed_fkey requires

                 #include <ctype.h>


             for the call to isprint in the default case of the switch
             statement.

      190    The return statement of MyTed_fexit should be:

                 return(std_fexit(sed));


      235    bd_bar does not support a title.

      244    In the last sentence on the page the reference to paragraph 1
             should be to paragraph 2.

     A-17    disp_GetMapEntry is described incorrectly.  It should read:

                 SYNOPSIS

                 VOID disp_GetMapEntry(index, bg, fg);

                 byte index;         /* index into the attribute map */
                 opixval *bg;            /* pointer to background color */
                 opixval *fg;            /* pointer to foreground color */

                 EXAMPLE

                 opixval fore, back;

                 disp_GetMapEntry(0x07, &back, &fore);


     A-21    The cmwin_Class description mentions "disp_Open", it should mention
             "disp_Init".

     A-24    The arguments for disp_SetMapEntry are:

                 byte index;
                 opixval back;
                 opixval fore;


     A-67    The line

                 sed_SetPosition(sed, disp_GetHeight() - 1, 0);

             should be

                 sed_SetPosition(timesed, disp_GetHeight() - 1, 0);


     A-79    In the table of menu_Printf commands the @ quote is used not
             only to quote "@", but "#" and "]".

                 @@, @#, @]


   A-89 -    You need to #include <pcmode.h> when using any of the pc_
     A-92    functions.

    A-101    pop_Text automatically paints the popup to the display. You do not
             have to explicitly call sed_Repaint.

    A-279    The example for sed_UnMarkField should include a call to
             sed_UpdateField(sed, 2) after the call to sed_MarkField.

    A-297    The synopsis to sled_SetColVar is missing the beginning line:

                 #include <sled.h>


  A-375 -    In all the examples for Tm_ functions any struct Tm call argument
    A-388    should be passed by reference, not value.

    A-377    In the example for tm_Adjust the call argument "date" should be
             "&date".

    A-380    The function name in the synopsis should be tm_DayOfWeek, not
             tm_FirstDay.

    A-396    The synopsis should read:

                 valid_String(string, vstr)


             not

                  valid_String(num, vstr)


      B-5    The variable type of bob_funcs is VOID.

     B-10    date_funcs require the inclusion of the your compiler's TIME.H
             file.

     B-15    The variable type of framer_funcs is VOID.  The VARSIZE member is
             missing from the field_funcs structure given in the Function
             Reference.  It is should be included as the last member of the
             structure and be 0.

     B-16    The variable type of gmenu_funcs is VOID.

     B-17    hex_funcs does not support validation.

     B-22    The variable type of menu_funcs is VOID.

     B-33    There are no sled_funcs.

     B-35    The variable type of slug_funcs is VOID.

     B-39    time_funcs require the inclusion of the your compiler's TIME.H
             file.

23.2:  Errata For The 3.0 Manual

    The following are mistakes in the C-scape Manual and Function Reference.

        3    The current release does not include an ANSI terminal driver.

       15    The first line of code at the top of the page should use the
             attribute 0x70, not 0x07.  It should read:

                 menu_Printf(menu, "Before:Normal @a[%d] After:Reverse", 0x70);


       30    In the first sentence of the third paragraph "fields" should be
             "field":

                 The actual length of a field can be up to MAX_FIELD_LEN (1000)
                 characters long.


       40    At the top of the page the code fragment containing menu_Printf
             lack some needed quotes.  It should read:

                 menu_Printf(menu, "@f[%s]\n", NULL, &menu_funcs, p);


       47    The following should be added to the spc_Tone example:

                 #include <stdio.h>
                 #include <cscape.h>
                 #include <scancode.h>   /*  for F10 definition  */


       51    The last line of the code for the my_senter function should read:

                 sed_SetRecord(sed, sed_GetScratchPad(sed), fieldno);


       52    The last sentence of the third paragraph should omit "open,":

                 This saves the time it takes to close and reopen the sed.


       54    sed_UnProtectField should be included in the see ref in the third
             sentence:

                 See sed_ProtectField, sed_IsProtectedField, and
                 sed_UnProtectField.


       90    spc_Embed should refer to section 10.1.1.

      116    (5) the integer value used in the slug definition structure should
             be a positive, NON-ZERO value.

      117    The type cast in the call to slug_Go should be a (VOID *), not a
             (char *).

      117    The data type of sdata in the example user function should be (VOID
             *), not (char *).

      118    (3) the integer value used in the frame definition structure should
             be a positive, NON-ZERO value.

      127    The spc_Embed has a null case BOB_UP that falls thru to the UP
             case; BOB_DOWN falls thru to DOWN.  The cases for LEFT and RIGHT
             should be cases for SHFT_TAB and TAB, respectively.  Also the null
             cases BOB_LEFT and BOB_RIGHT fall thru to SHFT_TAB and TAB,
             respectively.  See the SPCEMBED.C source file in the C-scape
             library.

      128    spc_Embed uses TABs not arrows.

  128-129    The bob_fkey code given in the manual differs from the current
             implementation.  Please refer to the C-scape library source file
             FNBOB.C, instead.

  142-143    In the example code pertaining to creating a sed with a ted field
             there should be a call to explicitly set the sed size (to ensure
             that the ted area is non-zero).  Use sed_SetHeight(sed) and
             sed_SetWidth(sed) before the sed_Repaint(sed) call;

      144    The return statement of MyTed_fexit should be:

                 return(std_fexit(sed));


      147    The reference in the example MyTed_sexit to ted_RewindTB should be
             a reference to sed_RewindTB.

  151-152    The example code MyTed_fkey requires

                 #include <ctype.h>


             for the call to isprint in the default case of the switch
             statement.

      156    The return statement of MyTed_fexit should be:

                 return(std_fexit(sed));


      157    The example should read:

                 case DEL:
                     if (ted_GetMark(sed) == TED_NOMARK) {
                         /* Delete the marked region (if there is one) */
                         ted_BlockDelete(sed);
                     }
                     else {
                         /* Delete a character */
                         ted_DeleteChar(sed);
                     }
                     break;


      159    The example should read:

                 case ALT_S:
                     /* ... */
                         if (ted_Search(sed, search, TED_FORWARD |
                 TED_AFTER)) {
                         sed_BorderPrompt(sed, FNULL);
                     }


      168    bd_bar does not support a title.

     A-15    disp_GetMapEntry is described incorrectly.  It should read:

                 SYNOPSIS

                 VOID disp_GetMapEntry(index, bg, fg);

                 byte index;         /* index into the attribute map */
                 opixval *bg;            /* pointer to background color */
                 opixval *fg;            /* pointer to foreground color */

                 EXAMPLE

                 opixval fore, back;

                 disp_GetMapEntry(0x07, &back, &fore);


     A-19    The cmwin_Class description mentions "disp_Open", it should mention
             "disp_Init".

     A-21    The arguments for disp_SetMapEntry are:

                 byte index;
                 opixval back;
                 opixval fore;


     A-63    The line

                 sed_SetPosition(sed, disp_GetHeight() - 1, 0);

             should be

                 sed_SetPosition(timesed, disp_GetHeight() - 1, 0);


     A-75    In the table of menu_Printf commands the @ quote is used not
             only to quote "@", but "#" and "]".

                 @@, @#, @]


   A-85 -    You need to #include <pcmode.h> when using any of the pc_
     A-88    functions.

     A-97    pop_Text automatically paints the popup to the display. You do not
             have to explicitly call sed_Repaint.

    A-103    sed_Clear no longer exists.

    A-263    The example for sed_MarkField should include a call to
             sed_UpdateField(sed, 2) after the call to sed_MarkField.

    A-297    The synopsis to sled_SetColVar is missing the beginning line:

                 #include <sled.h>


  A-355 -    In all the examples for Tm_ functions any struct Tm call argument
    A-368    should be passed by reference, not value.

    A-360    The function name in the synopsis should be tm_DayOfWeek, not
             tm_FirstDay.

    A-376    The synopsis should read:

                 valid_String(string, vstr)

             not

                 valid_String(num, vstr)


      B-5    The variable type of bob_funcs is VOID.

     B-11    date_funcs require the inclusion of the your compiler's TIME.H
             file.

     B-15    The variable type of framer_funcs is VOID.  The VARSIZE member is
             missing from the field_funcs structure given in the Function
             Reference.  It is should be included as the last member of the
             structure and be 0.

     B-16    The variable type of gmenu_funcs is VOID.

     B-17    hex_funcs does not support validation.

     B-22    The variable type of menu_funcs is VOID.

     B-33    There are no sled_funcs.

     B-35    The variable type of slug_funcs is VOID.

     B-39    time_funcs require the inclusion of the your compiler's TIME.H
             file.

23.3:  Errata For The 3.0 Manual Addendum

        3    In section 5.13, Auxiliary Functions, the next to last sentence of
             the 2nd paragraph "before... Fenter" is duplicated.  It should
             read:

                 ...before each field's fenter functions, and after each field's
                 fexit function.

             Not:

                 ...before each field's fenter functions, and before each
                 field's fenter function.


        7    The code example at the top of the page has a line which reads:

                 sed_MarkField(sed, fldno, reg, sel);

             The line should be:

                 sed_MarkField(sed, fldno, sel, sel);