Skip to content

Tables

Chapter 7-2
Tables

Introduction

This chapter explains how to create a table in the rich text field of a document.


CD Table Records

A table in a rich text field consists of a CDTABLEBEGIN record, one or more CDTABLECELL records, and a CDTABLEEND.


Creating a Table

To create a table in a rich text field, initialize the necessary CD records, convert them to Domino canonical format in a buffer in the proper sequence, and then call NSFItemAppend to append the buffer to the rich text field of an open note.

A table cannot be the first paragraph in a rich text field; there must be at least one paragraph before it. Therefore, initialize and append at least a CDPABDEFINITION, a CDPABREFERENCE, and a CDTEXT record with a 0-length string before the first CDTABLEBEGIN.

The Notes editor imposes the following rules on tables in rich text fields:

  • Editor tables must occupy their own paragraphs. That is, before outputting a CDTABLEBEGIN record, you must create an empty paragraph. You can do this minimally by outputting a CDPARAGRAPH record followed by a CDTEXT record with text of 0 length. The LeftMargin field of the CDTABLEBEGIN record is the margin at which the leftmost border is painted. After the table has been started with a CDTABLEBEGIN record, records that define the table cells must be output. The first record that defines a cell is the CDTABLECELL record. Among other items, this record contains the left and right margins of the cell. These margins represent the extreme margins that any paragraph in the cell can use. In other words, no paragraph in the cell can have a left margin or first line left margin less than that of the cell's left margin.
    Likewise, no paragraph can have a right margin greater than the cell's right margin. Note that these margins are not the locations of the cell borders. The border positions are implied by the HorizInterCellSpace and the widths of the cell contents (Cell.RightMargin - Cell.LeftMargin).
  • Each cell must have at least one paragraph. CDPARAGRAPH, CDPABDEFINITION, CDPABREFERENCE, and CDTEXT records are enough. All PABs referenced by paragraphs in a table must have PABFLAG_DISPLAY_RM set in the Flags WORD. This forces Notes to honor and display the right margin of the paragraph. CD records for following cells are packed one directly after another. After you create the top row of CDPABDEFINITIONS, we suggest that you reuse these existing cell paragraph PABIDs in CDPABREFERENCEs in the remaining cell paragraphs. This saves memory and reduces needless calculations.
  • After you define all the cells, you must define a CDTABLEEND record. This signifies that you have completely specified the table. Also note that there must be at least one paragraph following a table in any rich text field. You can do this minimally by outputting a CDPARAGRAPH, a CDPABREFERENCE, and a CDTEXT record with a 0-length string.


You must observe several general rules when creating a table, since they are enforced by the user interface when it attempts to display a table that you have created programmatically:

  • The maximum RightMargin for any paragraph is 22.75 inches.
  • The maximum table width is 22.75 inches - LeftMargin inches.
  • The maximum number of rows in a table is 255.
  • The maximum number of columns in a table is 64.
  • The minimum intercell distance is 0.0625 inches (1/16th of an inch).



Required CD Records

This section shows the data structures of the required CD records.

When you initialize these data structures, you must zero any fields that you do not initialize with specific values. This is also true of partially-used flags fields. In other words, if only the low 5 bits of a flags word are set, you must set the high 11 bits to 0.

Required CD Records for Defining Tables

/  Begin Table Record - This record specifies the beginning
    of a table. It contains interesting information about the
    format and size of the table.
/
typedef struct
{
 BSIG Header;
 WORD LeftMargin;
 WORD HorizInterCellSpace;
 WORD VertInterCellSpace;
  WORD V4HorizInterCellSpace;
 WORD V4VertInterCellSpace;
 WORD Flags;
} CDTABLEBEGIN;

Header                Standard BSIG with Signature set to
                      SIG_CD_TABLEBEGIN
LeftMargin            Left margin (in twips) of the table.
                      1 INCH = 72 POINTS, and 1 POINT = 20 TWIPS
HorizInterCellSpace   Space (in twips) between each cell and its
                     column border.
VertInterCellSpace    Space (in twips) between each cell and its
                      row border.
V4HorizInterCellSpace Defaults to 0. (Spare in V3)  
V4VertInterCellSpace  Defaults to 0. (Spare in V3)
Flags                 Bits to follow
                     0     1 if Fit to window is desired
                           0 if Fit to windows is not desired
                     1-15  0
                      CDTABLE_AUTO_CELL_WIDTH (0x0001)
                      CDTABLE_V4_BORDERS (0x0002)  

/  Table Cell Record - This record defines a cell within a table.
    It contains interesting information about the format and size
    of the cell.
/

typedef struct
{
BSIG Header;
BYTE Row;
BYTE Column;
WORD LeftMargin;
WORD RightMargin;
WORD FractionalWidth;
BYTE Border;
BYTE Flags;
WORD v42Border;
BYTE RowSpan;
 BYTE ColumnSpan;
WORD BackgroundColor;
} CDTABLECELL;

Header           Standard BSIG with Signature set to
                SIG_CD_TABLECELL
Row              Specifies the row number (0 based).
Column           Specifies the column number (0 based).
LeftMargin       Left margin (in twips) of the cell.
RightMargin      Right margin (in twips) of the cell.
FractionalWidth  20" (in twips) * CellWidth / TableWidth (used
                only if the CDTABLEBEGIN record has the
                fit to window bit asserted).
Border           Bits to follow
                0-1    Left border
                2-3    Right border
                4-5    Top border
                6-7    Bottom border
                TABLE_BORDER_NONE, TABLE_BORDER_SINGLE, and
                TABLE_BORDER_DOUBLE are the allowed values
                for the borders (see shift and mask CDTC_xxx values).
Flags          Only two are currently in use:
                  CDTABLECELL_USE_BKGCOLOR - Set if background color is specified.
                 CDTABLECELL_USE_V42BORDERS - Set if table was created with
                                               Notes Release 4.5 or later.
v42Border        Sets wider borders in Notes Release 4.5 or later
                 (see shift and mask CDTC_xxx_V42_xxx values).
ColumnSpan       Must be set to 0.
RowSpan          Must be set to 0.
BackgroundColor  Sets background color.

/  End Table Record - This record specifies the end of a table. /
typedef struct  
{
   BSIG Header;
   WORD SpareWORD;
   WORD SpareFlags;
} CDTABLEEND;

Header        Standard BSIG with Signature set to SIG_CD_TABLEEND
SpareWORD     Must be set to 0.
SpareFlags    Must be set to 0.


The MKTABLE Sample Program

The source code of the MKTABLE sample program consists of 4 files:

  • mktable.h Header file with function declarations and constant definitions
  • mktable.c Main file
  • cdrecord.c Routines that deal with paragraph and text CD records
  • cdtable.c Routines that deal with table CD records


The file cdrecord.c contains the following functions for appending CD records to a buffer:

  • CDPutPabdef creates a paragraph definition Paragraph Attribute Block (PAB) and writes it to a buffer.
  • CDPutPabref creates a PAB reference and writes it to a buffer.
  • CDPutPara creates a paragraph record and writes it to a buffer.
  • CDPutText creates a text block, fills it in, and writes it to a buffer.


The data in the buffer must be in Domino canonical format.

The file cdtable.c has references to the three rules shown above - just search for the word "Rule" using your favorite editor.

The file cdtable.c contains the following functions for creating tables in a rich text format:

CDPutTable creates a complete table based on the number of rows, columns, table width, textlist of cell text entries, and so on, and writes it to a buffer.
CDPutTableBegin creates a CDTABLEBEGIN record in the supplied buffer.
CDPutCell creates a CDTABLECELL record in the supplied buffer.
CDPutTableEnd creates a CDTABLEEND record in the supplied buffer.

The data in the buffer must be in Domino canonical format.

NOTE: Some C API programs do not perform host/canonical conversion when accessing or creating low-level structures in rich text. Canonical conversion is not strictly necessary for programs that run only on Intel-architecture platforms such as Windows. However, the source code for such programs is not portable. Source code that does perform host/canonical conversion will run on any platform supported by Domino and Notes, including UNIX platforms. For more information on canonical format requirements, read the "Domino Canonical Format" chapter in this guide.

Also note that cdrecord.c and cdtable.c routines use the ODSWriteMemory function to convert the CD structures from machine-specific format into Domino canonical format. To reference data from one of these structures (PABID, LeftMargin, and so on), copy the structure and use the ODSReadMemory function to convert the data back into the machine-specific format.