Skip to content

Forms and Frames

Chapter 8-1
Forms and Frames

Forms

A form serves as a template for data notes in a database. Forms are notes of class NOTE_CLASS_FORM.
Subforms are also forms of class NOTES_CLASS_FORM and may be inserted into a form.


Components of a Form Note and A Subform Note

A form note consists of three items: a $TITLE item, a $INFO item, and one or more $Body items.

A subform note consists of four items: a $TITLE item, a $INFO item, a $Flags item, and one or more $Body items.


$TITLE

The $TITLE item must be the first item in a form note. It is a text item that contains a string specifying the name of the form.


$INFO

The second item in a form note is a rich text item called $INFO. It consists of a CDDOCUMENT data structure, which contains information that pertains to all documents created using the form. For a description of the CDDOCUMENT structure, see the Reference.


$Flags

The $Flags item is an additional item and is used to identify a subform from a form note. The following flag values must be set to create a subform and are defined in stdnames.h:

DESIGN_FLAG_ADD
DESIGN_FLAG_NO_COMPOSE
DESIGN_FLAG_SUBFORM
DESIGN_FLAG_HIDE_FROM_V3


$BODY

Following the $TITLE and $INFO items is a sequence of one or more $BODY items, which are rich text items that define the layout and data types of all the fields in the form.

A form contains variable data (the fields in which you can enter or edit data) and static, unchanging data, such as field labels and whitespace on the document page. The fields are defined by the CDFIELD data structure, while the rest of the form is defined by a sequence of other Composite Data records, usually CDTEXT items.


Defining Fields with the CDFIELD Data Structure

The CDFIELD data structure contains all the information needed to define a field, including:

  • The name assigned to the field
  • The data type of the field (TYPE_TEXT, TYPE_NUMBER, TYPE_COMPOSITE, and so on)
  • Font in which data will be displayed in the field
  • Field formulas (if any)


For a full description of the CDFIELD structure, see the Reference.


Defining Non-Field Form Data

The non-field data in a form (field labels, whitespace, and so on) is often used to label fields and to position them on the work page. For example, to define a form containing two text fields separated by a blank line, the $BODY item would contain:

  • A CDFIELD item defining the text field as desired
  • A CDTEXT item containing the null string ("") to display a blank line
  • A second CDFIELD item defining the second text field


Of course, in this example the $BODY item would also contain the appropriate paragraph-related CD structures (CDPARAGRAPH, CDPABDEF, CDPABREF, and so on).


The READFORM Sample Program

The sample program READFORM opens a database called readform.nsf, opens the form note for the form titled "test form 1," reads the $TITLE item that contains the title of the form, and stores the title in a buffer to be displayed later.

Next, READFORM reads the $BODY item and calls EnumCompositeBuffer to search for each CDFIELD record in $BODY.

NOTE: Version 3.0 of the C API added a fourth parameter to the EnumCompositeBuffer function, a void pointer to user-defined data. This allows the action routine and the calling routine to share data without requiring the data to be global. READFORM passes a pointer to an output character buffer in this fourth parameter.


READFORM: Action Routine FormFields - Reading Field Names and Datatypes

/
* FORMFIELDS() -- Action routine invoked by EnumCompositeBuffer.

* For each field in a form, the $Body field of the Form note will
* contain a record of type CDFIELD, which defines that field. If the
* current record is a CDFIELD record, this routine extracts the
* field name and data type and writes these to the buffer pointed to
  by the pCtx parameter. If the current record is not a CDFIELD record,
  this routine simply returns.
/

STATUS LNPUBLIC FormFields (char RecordPtr,
                             WORD RecordType,
                             DWORD RecordLength,
                             void pCtx)
{
char FieldString[256];
char szFieldName[128];
char szDataType[128];
char far pFieldName;
WORD binDataType;
char pBuf = (char )pCtx;

    switch (RecordType)
   {
    case SIG_CD_FIELD:
       {
           CDFIELD pCDField;    
           pCDField = (CDFIELD )RecordPtr;
           
       /
        * Get the data type of this field
        /

            binDataType = pCDField->DataType;
           switch (binDataType)
            {
              case TYPE_TEXT:
                   strcpy (szDataType, "Text");
                   break;

               case TYPE_TEXT_LIST:
                   strcpy (szDataType, "Multi-Value Text");
                   break;

               case TYPE_NUMBER:
                   strcpy (szDataType, "Number");
                   break;

               case TYPE_NUMBER_RANGE:
                   strcpy (szDataType, "Multi-Value Number");
                   break;

               case TYPE_TIME:
                   strcpy (szDataType, "Time/Date");
                   break;

               case TYPE_TIME_RANGE:
                   strcpy (szDataType, "Multi-Value Time/Date");
                   break;

               case TYPE_COMPOSITE:
                   strcpy (szDataType, "Rich Text");
                   break;

               default:
                   strcpy (szDataType, "Unknown Data Type");
                   break;
           }
        /
        * Now get the name of this field.
        /
       pFieldName = (RecordPtr + ODSLength(_CDFIELD) + pCDField->DVLength
                        + pCDField->ITLength + pCDField->IVLength);

          memcpy(szFieldName, pFieldName, pCDField->NameLength);
         szFieldName[pCDField->NameLength] = '\0';

        /
        *  Construct a string containing the field name and datatype
        *  and append it to a global buffer.
        /

            wsprintf(FieldString, "Field Name = %s,  Data Type = %s\n",
                    szFieldName, szDataType);
     lstrcat(pBuf, FieldString);
           break;
       }
       default:
       break;
   }

    return (NOERROR);
}

The action routine FormFields, invoked by EnumCompositeBuffer for each CD record in $BODY, checks to see if the CD record being examined is a CDFIELD record. If not, FormFields exits. If the record is a CDFIELD, FormFields reads the field name and data type from the data structure, then writes a string describing the fieldname and data type to the buffer pointed to by pCtx.

When FormFields has processed every CDFIELD record in the $BODY item, control returns to the main routine, which then displays the database title and the field information in a message box.

Frames

A frame serves as one section or pane, and can contain a form, folder, page, document, view, navigator, or frameset. A frameset consists of a collection of frames that may contain links and other relationships.


Components of a Frameset and Frame

A frameset note consists of a $TITLE item, a $Flags item, and a $Frameset item.


$TITLE

The $TITLE item must be the first item in a frameset note. It is a text item that contains a string specifying the name of the frameset.


$Flags

The $Flags item is an additional item and is used to identify a frameset note. The following flag values must be set to create a frameset and are defined in stdnames.h:

DESIGN_FLAG_ADD
DESIGN_FLAG_NO_COMPOSE
DESIGN_FLAG_FRAMESET
DESIGN_FLAG_HIDE_FROM_V3


$Frameset

Following the $TITLE and $Flags items is a $Frameset item.

A frameset contains a number of general properties and individual frame properties that define the layout and arrangement of data. This information is contained within the following CD records:

  • CDFRAMESETHEADER
  • CDFRAMESET
  • CDFRAME
  • CDRESOURCE


CDFRAMESET

The CDFRAMESET data structure contains all the general properties of the frameset, including:

  • Frame Border width (if enabled)
  • Frame Spacing width
  • Number of Frame Rows
  • Number of Frame Columns
  • Frame Types and Values


CDFRAME

The CDFRAME data structure contains all the properties of a single frame, including:

  • Scroll bar style
  • Frame margin width
  • Frame margin height
  • Frame name and length
  • Frame target name and length


CDRESOURCE

The CDRESOURCE data structure contains the information needed to define the content of the frame:

  • Type of resource (a named element, a link, a URL, etc.)
  • Resource class (view, document, etc..)
  • Resource name and length



For a full description of the these structures, see the Reference.


$DefaultFrameset

To launch the frameset when the database is opened you must append a $DefaultFrameset Item to the icon note. Please see the sample MAKEFORM for further information.