form.h

Go to the documentation of this file.

/** @file form.h
 *  @brief Form data structures, enums, types, end process declarations
 *  @author Bill Waller
 *  Copyright (c) 2025
 *  MIT License
 *  billxwaller@gmail.com
 *  @date 2026-02-09
 */
 
#ifndef _FORM_H
#define _FORM_H 1
#include <cm.h>
 
#ifndef _COMMON_H
typedef struct Init Init;
#endif
 
#define FIELD_MAXLEN 1024
#define FIELD_MAXCNT 100
#define F_NOMETAS 1  /**< flag - no metacharacters allowed in field input */
#define F_NOTBLANK 2 /**< flag - field input cannot be blank */
#define F_NOECHO 4   /**< flag - do not echo field input on the screen, \
    e.g. for password fields */
 
/** FormAction Directives */
typedef enum {
    FA_CONTINUE =
        302,   /**< continue processing the form, e.g. after accepting a field */
    FA_ACCEPT, /**< accept the form, e.g. after accepting a field and all fields
                 are valid */
    FA_HELP,   /**< display the help information for the form, e.g. after
                 accepting   a field and the user requests help */
    FA_CANCEL, /**< cancel the form, e.g. after accepting a field and the user
                 cancels the form */
    FA_REFUSE, /**< refuse the form, e.g. after accepting a field and the field
                 value is invalid */
    FA_CALC,   /**< process the form, e.g. after accepting a field and
                 calculating the values of other fields based on the accepted
                 field value */
    FA_EDIT,   /**< edit the form, e.g. after accepting a field and allowing the
                 user to edit the form fields */
    FA_END     /**< end the form processing, e.g. after accepting a field and all
                 fields are valid and the form is accepted */
} FormAction;
 
/** Form field formats */
typedef enum {
    FF_STRING,      /**< a string field format, e.g. for accepting a name or other
                       text input */
    FF_DECIMAL_INT, /**< a decimal integer field format, e.g. for accepting an
                       age or other numeric input */
    FF_HEX_INT,     /**< a hexadecimal integer field format, e.g. for accepting a
                       color code or other hexadecimal input */
    FF_FLOAT,       /**< a floating point field format, e.g. for accepting a price or
                       other decimal input */
    FF_DOUBLE,      /**< a double precision floating point field format, e.g. for
                       accepting a more precise decimal input */
    FF_CURRENCY,    /**< a currency field format, e.g. for accepting a price or
                       other monetary input, formatted as a decimal number with two
                       decimal places and a currency symbol */
    FF_YYYYMMDD,    /**< a date field format, e.g. for accepting a date input,
                       formatted as a string in the format "YYYY-MM-DD" */
    FF_HHMMSS,      /**< a time field format, e.g. for accepting a time input,
                       formatted as a string in the format "HH:MM:SS" */
    FF_APR,         /**< an APR field format, e.g. for accepting an annual percentage
                       rate input, formatted as a decimal number with two decimal places
                       and a percent symbol */
    FF_INVALID      /**< an invalid field format, used for error handling and
                       validation purposes */
    /** Future Implementation of Additional Field Formats
     * FF_EMAIL - an email field format, e.g. for accepting an email address
     * input, formatted as a string that matches a regular expression for valid
     * email addresses
     * FF_PHONE - a phone number field format, e.g. for accepting a phone number
     * input, formatted as a string that matches a regular expression for valid
     * phone numbers
     * FF_URL - a URL field format, e.g. for accepting a URL input, formatted as
     * a string that matches a regular expression for valid
     */
} FieldFormat;
 
/** ff_tbl - a table of field format strings used in the Form description
 *  file to identify field data types
 *  the index of the field format in this table corresponds to the FieldFormat
 *  enum values, e.g. ff_tbl[FF_STRING] = "string", ff_tbl[F_DECIMAL_INT] =
 *  "decimal_int", etc.
 */
extern char ff_tbl[][26]; /**< a table of field format strings used in the Form
                     description file to identify field data types, e.g.
                     "string", "decimal_int", "hex_int", etc. The index of the
                     field format in this table corresponds to the FieldFormat
                     enum values, e.g. ff_tbl[FF_STRING] = "string",
                     ff_tbl[FF_DECIMAL_INT] = "decimal_int", etc. This table is
                     used for parsing the form description file and determining
                     the field formats for each field in the form. */
 
/** @struct Text
   @brief structure for form fields */
typedef struct {
    int line;           /**< the line number on the form window where this text string
                           should be displayed */
    int col;            /**< the column number on the form window where this text string
                           should be displayed */
    char str[SCR_COLS]; /**< the text string to be displayed on the form window
                         */
    int len;            /**< the length of the text string, used for display and formatting
                           purposes */
} Text;
 
/** @struct Field
   @brief structure for form fields */
typedef struct {
    int line;                         /**< the line number on the form window where this field should be
                                         displayed */
    int col;                          /**< the column number on the form window where this field should
                                         be displayed */
    int len;                          /**< the length of the field input area, used for display and
                                         formatting purposes */
    int ff;                           /**< the field format, represented as an integer corresponding to
                                         the FieldFormat enum values, e.g. FF_STRING, FF_DECIMAL_INT, etc.
                                         This is used for validating and formatting the field input values
                                         according to their specified formats. */
    char input_s[FIELD_MAXLEN];       /**< the input string for this field, used for
                                   storing   the user's input value for this field
                                   during form   processing */
    char accept_s[FIELD_MAXLEN];      /**< the accepted string for this field, used
                                   for  storing the validated and accepted value for
                                   this  field after processing the user's input
                                   during  form processing */
    char display_s[FIELD_MAXLEN];     /**< the display string for this field, used
                                   for storing the formatted string that will be
                                   displayed in the field input area on the form
                                   window during form processing, based on the
                                   accepted value and the field format */
    cchar_t display_cc[FIELD_MAXLEN]; /**< display complex character array */
    char filler_s[FIELD_MAXLEN];      /**< the filler string for this field, used for
                                   storing the string that will be used to fill the
                                   field input area on the form window during form
                                   processing, based on the field length and the fill
                                   character specified in the form structure */
    cchar_t filler_cc[FIELD_MAXLEN];  /**< filler complex character array */
} Field;
 
/** @struct Form */
typedef struct {
    int fg_clr_idx;               /**< the foreground color for the form window */
    int bg_clr_idx;               /**< the background color for the form window */
    int bo_clr_idx;               /**< the border color for the form window */
    int lines;                    /**< the number of lines for the form window */
    int cols;                     /**< the number of columns for the form windowi */
    int begy;                     /**< the screen line number for the upper left corner of the form
                                     window */
    int begx;                     /**< the screen column number for the upper left corner of the
                                     form window */
    WINDOW *win;                  /**< ncurses window structure for form */
    WINDOW *box;                  /**< ncurses window structure for form box border */
    char title[MAXLEN];           /**< the title of the form, displayed in the form box
                                     border */
    FILE *in_fp;                  /**< input stream pointer, e.g. for reading from a file or pipe
                                   */
    FILE *out_fp;                 /**< output stream pointer, e.g. for writing to a file or pipe
                                   */
    int in_fd;                    /**< input file descriptor, e.g. for reading from a file or pipe
                                   */
    int out_fd;                   /**< output file descriptor, e.g. for writing to a file or pipe
                                   */
    char mapp_spec[FIELD_MAXLEN]; /**< the menu application description file
                                     spec */
    char provider_cmd
        [MAXLEN]; /**< the provider command, which can be executed in the
                     background to provide dynamic content for a program called
                     by the menu application. This command can be used to
                     generate or retrieve data that will be displayed on the
                     form or used for processing the form fields, allowing for
                     dynamic and interactive forms that can adapt to changing
                     data or user input during form processing. */
    char receiver_cmd
        [MAXLEN];     /**< the receiver command, which can be executed in the
                         background to process the output of a program called by the
                         menu application. This command can be used to handle the
                         results or output generated by a program that is executed
                         as part of the form processing, allowing for dynamic and
                         interactive forms that can respond to the results of
                         process programs or commands during form processing. */
    char cmd[MAXLEN]; /**< a command that can be executed in the foreground,
                         possibly taking control of the screen, by the menu
                         application, e.g. an editor. This command can be used
                         to allow the user to perform additional actions or
                         tasks as part of the form processing, such as editing a
                         file or running a script, providing a more interactive
                         and flexible user experience during form processing. */
    bool f_mapp_spec; /**< flag - mapp_spec verified */
    char help_spec
        [MAXLEN];          /**< the menu application help file spec, e.g. a qualified
                              path to a file containing help information for the menu
                              application and its associated forms. This file can be used
                              to provide context-sensitive help to the user during form
                              processing, allowing them to access relevant information
                              and guidance based on their current actions or the specific
                              form they are working with. */
    char in_spec[MAXLEN];  /**< the input file spec, e.g. a qualified path to a
                              file containing initial values for the form fields.
                              This file can be used to pre-populate the form
                              fields with existing data or default values during
                              form processing, allowing for a more efficient and
                              user-friendly experience when working with forms
                              that require input values. */
    char out_spec[MAXLEN]; /**< the output file spec, e.g. a qualified path to a
                              file where the accepted values for the form fields
                              will be written after form processing. This file
                              can be used to save or export the results of the
                              form processing, allowing for further use or
                              analysis of the accepted field values after the
                              form has been completed. */
    bool f_in_spec;        /**< flag - in_spec verified, indicating that the input file
                              spec has been validated and is ready for use during form
                              processing */
    bool f_out_spec;       /**< flag - out_spec verified, indicating that the output
                              file spec has been validated and is ready for use during
                              form processing */
    bool f_in_pipe;        /**< flag - in_spec is a pipe, indicating that the input
                              file spec is a command that can be executed to provide
                              input data for the form fields during form processing,
                              allowing for dynamic and flexible input sources for the
                              form fields. */
    bool f_out_pipe;       /**< flag - out_spec is a pipe, indicating that the output
                              file spec is a command that can be executed to handle
                              the accepted field values for the form fields during
                              form processing, allowing for dynamic and flexible
                              output handling for the form results. */
    bool f_help_spec;      /**< flag - help_spec verified, indicating that the help
                              file spec has been validated and is ready for use
                              during form processing */
    bool
        f_erase_remainder;    /**< flag - if set, causes the data above the cursor
                                 and to the right to be cleared when the user
                                 presses the enter key, e.g. to prevent leftover
                                 characters from previous field values from being
                                 left on the screen when a shorter value is entered
                                 in a field. This is essential for veteran keyboard
                                 users, accountants and the like, who rarely even
                                 look at the screen during data entry. */
    bool f_multiple_cmd_args; /**< flag: multiple command arguments */
    bool f_calculate;         /**< flag - if set, Form presents an option to perform an
                                 external query or calculation. */
    bool f_process;           /**< flag - if set, Form presents an option to perform an
                                   external query or calculation. */
    bool f_query;             /**< flag - if set, the action key label will be "query"
                                 instead of "process" or "calculate". */
    bool help;                /**< flag - if set, indicates that the user has requested help
                               during form processing, e.g. by pressing a help key or button.
                               This can be used to trigger the display of context-sensitive
                               help information for the form, providing guidance and
                               assistance to the user based on their current actions or the
                               specific form they are working with. */
    bool f_provider_cmd;      /**< flag - if set, indicates that the provider command
                                 has been verified and is valid for execution. This
                                 can be used to ensure that the provider command
                                 specified in the form structure is valid and can be
                                 executed successfully during form processing,
                                 allowing for dynamic content generation or retrieval
                                 as part of the form's functionality. */
    bool f_receiver_cmd;      /**< flag - if set, indicates that the receiver command
                                 has been verified and is valid for execution. This
                                 can be used to ensure that the receiver command
                                 specified in the form structure is valid and can be
                                 executed successfully during form processing,
                                 allowing for dynamic handling of the results or
                                 output generated by process programs or commands as
                                 part of the form's functionality. */
    bool f_cmd;               /**< flag - if set, indicates that the command has been verified
                                 and is valid for execution. This can be used to ensure that
                                 the command specified in the form structure is valid and can
                                 be executed successfully during form processing, allowing for
                                 additional actions or tasks to be performed as part of the
                                 form's functionality, such as editing a file or running a
                                 script. */
    char brackets
        [3];                  /**< the characters used to indicate field input areas in the form
                                 description file, e.g. "[]" for square brackets or "<>" for
                                 angle brackets. The first character is the left bracket and the
                                 second character is the right bracket. These characters may be
                                 left blank, especially if fill_char is used. The choice of
                                 brackets can affect the visual appearance of the form and how
                                 users perceive the input areas for each field, with some
                                 preferring the traditional look of brackets while others may
                                 prefer a cleaner look without them. The use of brackets can also
                                 help to visually separate the field input areas from other text
                                 on the form, making it easier for users to identify where they
                                 need to enter their input during form processing. */
    cchar_t brktl;            /**< the ncurses cchar_t representation of the left bracket
                                 character, used for displaying the left bracket in the
                                 form window during form processing. */
    cchar_t brktr;            /**< the ncurses cchar_t representation of the right bracket
                                 character, used for displaying the right bracket in the
                                 form window during form processing. */
    char fill_char[4];        /**< the character used to fill the field input areas in
                                 the form, e.g. "_" for underscores or " " for spaces.
                                 This character is used to visually indicate the input
                                 area for each field in the form, and it can be used in
                                 conjunction with brackets or on its own if brackets
                                 are not used. Many feel that using fill characters
                                 without brackets creates a cleaner and more modern
                                 look for the form, while others prefer the traditional
                                 look of brackets. The choice of whether to use
                                 brackets, fill characters, or both is a matter of
                                 personal preference and design style for the form. */
    int fidx;                 /**< the index of the currently selected field, used for
                                 highlighting and selection purposes during form processing.
                                 This index corresponds to the position of the field in the
                                 field array, allowing for easy access to the current field's
                                 data and properties during form processing. The fidx can be
                                 updated as the user navigates through the form fields,
                                 providing visual feedback and allowing for dynamic interactions
                                 based on the selected field. */
    int fcnt;                 /**< the number of fields in the form, used for iterating through
                                 the field array and managing field data during form processing.
                                 This count can be used to determine when the user has reached
                                 the end of the fields or to validate that all required fields
                                 have been completed before accepting the form. The fcnt can
                                 also be used to dynamically allocate resources or manage memory
                                 for the field data during form processing. */
    int didx;                 /**< an index to the array of text strings to be displayed on the
                                 form window, used for iterating through the text array and
                                 managing the display of text during form processing. This index
                                 can be updated as needed to control which text strings are
                                 currently being displayed on the form window, allowing for
                                 dynamic updates to the form's content based on user actions or
                                 other events during form processing. */
    int dcnt;                 /**< the number of text strings to be displayed on the form
                                 window, used for iterating through the text array and managing
                                 the display of text during form processing. This count can be
                                 used to determine how many text strings need to be displayed on
                                 the form window and to validate that all necessary text has
                                 been provided for display during form processing. The dcnt can
                                 also be used to dynamically allocate resources or manage memory
                                 for the text data during form processing. */
    Text *text[FIELD_MAXCNT]; /**< an array of pointers to the text structures
                              for the text strings to be displayed on the form
                              window, used for managing and displaying the text
                              content of the form during form processing. Each
                              pointer in this array corresponds to a Text
                              structure that contains the line, column, string,
                              and length information for a specific text string
                              to be displayed on the form window. This allows
                              for dynamic management of the text content on the
                              form, enabling updates and changes to the
                              displayed text based on user actions or other
                              events during form processing. */
    Field
        *field[FIELD_MAXCNT]; /**< an array of pointers to the field structures
                              for the fields in this form, used for managing and
                              processing the form fields during form processing.
                              Each pointer in this array corresponds to a Field
                              structure that contains the line, column, length,
                              field format, input string, accepted string,
                              display string, and filler string information for
                              a specific field in the form. This allows for
                              dynamic management of the form fields, enabling
                              validation, formatting, and processing of user
                              input based on the specified field formats and
                              properties during form processing. */
    Chyron *chyron;           /**< a structure for managing the chyron string and its
                             display properties on the form window during form processing.
                             The chyron can be used to provide instructions, feedback, or
                             other information to the user during form processing, and it
                             can be updated dynamically based on user actions or other
                             events to enhance the user experience and provide context-
                             sensitive information as needed. */
} Form;
// extern Form *form;
 
extern int field_editor(Form *);
extern int form_display_field(Form *);
extern int form_display_field_n(Form *, int);
extern int field_navigator(Form *);
extern int form_read_description(Form *);
extern int form_fmt_field(Form *, char *s);
extern int form_desc_error(Form *, int, char *, char *);
extern void form_help(char *);
extern int form_yx_to_fidx(Form *, int, int);
extern void form_display_chyron(Form *);
extern void display_field(Form *, cchar_t *, int, int);
#endif