home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / textinfo / cxl50ngs.arj / CXLTFMT.NMS < prev    next >
Encoding:
Text File  |  1989-04-30  |  6.0 KB  |  118 lines
  1.  
  2.     ^bMulti-Field Input Functions^b
  3.  
  4.     Three functions are needed to process multi-field formatted input from
  5.     windows:  winpbeg(), winpdef(), and winpread().  The winpbeg() function
  6.     marks the start of an input form.  The winpdef() function defines an
  7.     input field and is called for each input field to be defined. The
  8.     winpread() function marks the end of the input form and processes all
  9.     defined fields.  The formatted input capabilities are much like those of
  10.     the inputsf() and winputsf() functions.  The major difference is that
  11.     with the winpbeg()/winpdef()/winpread() combination, you can edit back
  12.     and forth between fields before finally accepting the input.
  13.  
  14.     For every input field you want to define, you must call winpdef(). This
  15.     will allocate memory to hold the input record information. The first two
  16.     parameters, wrow and wcol, specify where in the active window the field
  17.     will be loaded.
  18.  
  19.     The next parameter, str, is the address of the string buffer to receive
  20.     the input data.  The edited string will be terminated with a '\0'.  This
  21.     means if your format string is "AAAAA", your receiving field must be
  22.     string[6] to hold the terminating '\0'.  You can edit numeric
  23.     information as well. There are 4 conversion functions to convert numbers
  24.     to/from CXL fields:
  25.  
  26.         cvtic() - convert integer to CXL field string
  27.         cvtci() - convert CXL field string to integer
  28.         cvtfc() - convert real number to CXL field string
  29.         cvtcf() - convert CXL field string to real number
  30.  
  31.     The next parameter, format, is the input field format string. It
  32.     controls how each character is input and how large the input field will
  33.     be.  It consists of 1 or more format characters, and may have displayed
  34.     text in between any of the format control characters.  You may use
  35.     spaces in between the format control characters for readability.  Valid
  36.     format control characters are listed in the "Formatted Keyboard Input
  37.     Functions" section.  The case of the format control characters must be
  38.     as shown.  You can also specify a decimal point in the field.  Format
  39.     strings for winpdef() are just like those of inputsf() and winputsf()
  40.     except there are no command toggles.
  41.  
  42.     The next parameter in the winpdef() function is fconv.  These are
  43.     similar to the command toggles of inputsf() and winputsf() except that
  44.     the fconv character applies conversion to the whole field.  Valid fconv
  45.     characters are:
  46.  
  47.             ^b0^b   - apply no conversion
  48.             ^b'L'^b - convert letters to lowercase
  49.             ^b'M'^b - convert letters to mixed upper & lowercase
  50.             ^b'P'^b - password field (do not echo characters)
  51.             ^b'U'^b - convert letters to uppercase
  52.             ^b'9'^b - numeric field (right justify, space fill to the left of
  53.                   the decimal; and left justify, zero fill to the right of
  54.                   the decimal.
  55.  
  56.     After the fconv parameter comes the mode parameter.  This parameter
  57.     allows you to specify if the input field is going to create new data or
  58.     update old data.  If the mode parameter is 0, then the input field
  59.     will be used for entering new data. If the mode parameter is nonzero,
  60.     then the input field will be used to update the old data contained in
  61.     the str parameter.  If you specify 2 for mode, the cursor will appear
  62.     at the end of the line and if an editing key is pressed first, the field
  63.     will be used for updating, otherwise the field will be used to create
  64.     new information.  If you do choose to update, then the length of the
  65.     input str will be adjusted to the field size either by truncation or
  66.     padding with spaces.
  67.  
  68.     The next parameter in the winpdef() function is validate.  This
  69.     parameter is the address of an optional user validation/modification
  70.     function.  If no validation function is to be used, then specify NULL.
  71.     Your user validation/modification function must be declared like:
  72.  
  73.         int func(char *str);
  74.  
  75.     where str is the address of the input field that will be passed to it.
  76.     Once your user function has the address of the input field, you can
  77.     validate and/or modify the input field. Your function can also display
  78.     an error message, sound a bell, or just about anything. When your
  79.     function is done, it must return 0 for no error, or the position in the
  80.     field where the error occurred (starting with 1).
  81.  
  82.     The final parameter to winpdef(), help, is the address of the help
  83.     category string to assign to this menu item.  This is useful if you are
  84.     using the context-sensitive help system and you want to assign a
  85.     different help category to each field.  If you do not need to use this
  86.     feature, specify NULL for this parameter.
  87.  
  88.     The winpdef() function will return one of the following values:
  89.  
  90.         ^bW_NOERROR^b  - no error
  91.         ^bW_NOACTIVE^b - no active window
  92.         ^bW_INVCOORD^b - invalid coordinates
  93.         ^bW_ALLOCERR^b - memory allocation error
  94.         ^bW_NOFRMBEG^b - no begin of form specified (winpbeg() not called)
  95.         ^bW_INVFORMT^b - invalid format string (syntax error)
  96.  
  97.     Once you have defined all input fields with winpdef(), you call
  98.     winpread() to process them.  The user is allowed to move around and edit
  99.     all of the fields.  The input fields are validated on the fly and after
  100.     entering the last field.  Valid editing keys are listed in Appendix E.
  101.  
  102.     After the winpread() function returns, all fields defined with winpdef()
  103.     will be cleared.  The receiving strings of all defined fields will now
  104.     contain the data entered.  If Escape checking was on and [Esc] was
  105.     pressed, then all receiving strings will contain the values they held
  106.     before winpread() was called and W_ESCPRESS will be returned.
  107.  
  108.     The general structure for defining input fields looks like:
  109.  
  110.         winpbeg(...);
  111.         winpdef(...);
  112.         winpdef(...);
  113.         winpdef(...);
  114.         winpread();
  115.  
  116. !seealso cxlappn.ngo:"AppendixE"
  117.  
  118.