Cell Command

Because writing templates involves laying out a generalized table cells, creating cells and setting their properties are very important parts of the GENerel language. You create cells with the Cell command:

Cell #1,<#2>

where

When a new cell is created, any current cell is closed and the new cell is started. The new cell will start a default spacing from the previous cell (see #cellSkip variable). Alternatively, various movement commands can be used to position the next cell at any new position. The new cell will start with the default cell size (as set by editing properties or with a DefaultCellSize command).

Once a cell is created, you can set its properties with the Set command. The following section list all types of cells and all their possible properties.

The Types of Cells

The following list has all types of cells that can be created in GEDitCOM II templates and list their possible properties. A cell's properties are hierarchical. A cell at a higher level inherits all properties from lower level cells. For example, an Expression cell inherits all properties of Static, TextCell, and GenericCell cells.

A cell is created by the cell name being argument #1 to the Cell command. The cells in italics are abstract cells that define certain cell properties, but cannot be created in templates.


Details on Each Cell Type

GenericCell Cells

This cell is the base cell. All other cells inherit the properties of this cell type. The properties are:

TextCell Cells

This cell is the base cell for single-line text cells. It inherits properties from GenericCells and has the following additional properties:

cell Label <#1>

This cell is for label text. The optional parameter #1 sets the text for the cell. The text can alternatively be set and appended by using the text property.

Label cells inherit properties from GenericCells and TextCells and have the following additional properties:

cell Static <#1>

This cell is is for static text. The optional parameter #1 sets the text for the cell. The text can alternatively be set and appended by using the text property.

Static cells inherit properties from GenericCells and TextCells and have the following additional properties:

cell Expression #1

This cell defines a cell that displays text from the GEDCOM file. The required argument #1 must be a GEDCOM expression. The cell will display data of the last structure referenced by the expression. If the contents of the last structure is a record ID, you will need an extra expression tag (such as ".rec") to get the correct structure. If the last structure is a record, it will only update correctly if AppendedExpression is view or altView

When your cell will display text from another record, you can display it by setting the text of a static or label cell or by passing the GEDCOM expression used to extract that text to an expression cell. The advantage of an expression cell is the the text will automatically update if the user changes the text in the other record. Static or label cells will not update.

An Expression cell inherits properties from GenericCells, TextCells, and Static Cells and has the following additional properties:

cell EditValue

This cell will display a text editing field for editing data in the current GEDCOM tag. It is only suitable for editing a single line of text. If the current tag has more then one line, the cell will automatically be converted into a EditField cell.

In templates for PLAC structures in Individual and Family records, you should use an EditValue cell and it will automatically be converted to a place editing field. These fields automatically fill in place names as typed and have a drop down menu to select from a list of current places. Because the place editing field is a different type of Cocoa object, some properties cannot be set as for EditValue cells (most importantly, you have fewer options for cell height).

EditValue cells inherit properties from GenericCells and TextCells and have the following additional properties:

cell EditName

This cell will display a single-line editing field for editing data in the current GEDCOM structure and it is only appropriate for NAME tags in individual records. It automatically handles the GEDCOM format for names, which involves removing and restoring slashes used to indicate surnames.

EditName cells inherit properties from GenericCells, TextCells, and EditValue. They do not define any additional properties.

cell EditDate

This cell will display a text editing field for editing data in the current GEDCOM structure and is only appropriate for DATE tags. It automatically handles the GEDCOM format for dates.

EditDate cells inherit properties from GenericCells, TextCells, and EditValue. They do not define any additional properties.

cell EditFile

This cell will display a text editing field for editing path name of a multimedia object (the _FILE tag in OBJE records). Its only function is to notify GEDItCOM II when a path name has changed because it keeps track of objects while a file is opened. If the path name is edited in a generic EditValue cell, the multimedia image might get out of synch with the editing.

EditFile cells inherit properties from GenericCells, TextCells, and EditValue. They do not define any additional properties.

cell EditURL

This cell is for editing URL addresses for web sites. It will display as a link to the site and the link can be clicked to visit the site in your default browser. But, if you hold the option key down while clicking, the field will turn into an editing field that can be used to edit the URL address.

EditURL cells inherit properties from GenericCells, TextCells, and EditValue. They do not define any additional properties.

TextFieldCell Cells

This cell is the base cell for multi-line, text-based cells that contain a vertical scroll bar if needed to display all the text. It inherits properties from GenericCells and has the following additional properties:

cell StaticField <#1>

This cell is for static text that displays on multiple lines (and has a scroll bar if needed). The optional parameter #1 sets the text for the cell. The text can alternatively be set and appended by using the text property.

StaticField cells inherit properties from GenericCells and TextFieldCells and have the following additional properties:

cell ExpressionField #1

This cell defines a cell that displays text from the GEDCOM file. The required argument #1 must be a GEDCOM expression. The cell will display data of the last structure referenced by the expression. This data should be GEDCOM data that typically requires multiple lines (such as an address or notes). For single-line text from a GEDCOM expression, use an Expression cell instead. Furthermore, if the referenced data contains html text (as denoted by data enclosed in <div> elements), and ExpressionField cell will format that data for display as html text. Since ExpressionField cells display text only, the html content will be displayed, but cannot be edited. The only cell that allows editing and display of html content is the EditPane cell.

Analogous to Expression cells, ExpressionField cells are preferred over StaticField cells when you want the displayed text to update if the user changes the source text.

When #1 points to a _BOX tag in a GEDitCOM II place record, the ExpressionField cell will decode the bounding box and display a map. It will also watch all place record data that might affect the map and redisplay the map whenever needed (e.g., map style, points of interest, the bounding box, etc.).

An ExpressionField cell inherits properties from GenericCells, TextFieldCells, and StaticField Cells. A required extra property is the expression and that must be provide in argument #1 above. If the ExpressionField cell ends up displaying html content, properties not used by the html rendering engine (e.g., font, fontColor, fontSize, alignment, cellBackground, lineHeight), will be ignored.

ExpressionField cells also have the following additional property:

cell EditField

This cell will display a text editing field for editing the current GEDCOM tag using a field with multiple lines of text. If needed, the field will have a scroll bar.

EditField cells inherit properties from GenericCells and TextFieldCells and have the following additional properties:

cell EditPane <#1>

This cell creates a split screen with the pane portion created by this cell allowing free-format text editing in a scrolling window for editing the current GEDCOM tag. Furthermore, by beginning and ending the text with html <div> and </div> elements, respectively, the pane can be used to display any user-entered web content. The optional parameter #1 provides a hint to be placed in the editing field if the current GEDCOM tag has no content (it is ignored if the tag has content). The templates for displaying a record can create only a single EditPane cell. Furthermore, the EditPane cell cannot be contained in a GroupBox.

EditPane cells inherit properties from GenericCells (although changes a few) and has the following additional (or changed) properties:

Warning: If you create a vertical split (left or right position) in the middle of a template, all cells created prior to the EditPane might display with the wrong margins in the formatted pane of the window. To avoid this issue you have to either use a fixed width display (see DisplayWidth command) or have the EditPane cell be the first cell created for the window.

ButtonCell Cells

This cell is the base cell for all button cells. It inherits properties from GenericCells and has the following additional properties:

cell LinkButton <#1>

This cell is for a button to link to another record. The optional parameter #1 sets the text for the cell. The text can alternatively be set or appended by using the text property.

LinkButton cells inherit properties from GenericCells and ButtonCells and have the following additional properties:

cell CreateLinkButton <#1>

Depending on how it is used, this cell can create GEDCOM links between records or create any subordinate GEDCOM tag. The optional parameter #1 sets the text for the cell. The text can alternatively be set or appended by using the text property.

First, if this cell is used in a template for any of the following standard GEDCOM tags that link between records: NOTE, SOUR, OBJE, ASSO, REPO, FAMC, ALIA, SUBM, ANCI or DESI, or if it is used in a template for custom GEDCOM tags understood as links by GEDitCOM II: _INDI, _FAM, or _LOG, the user can click the button to create a new link. The user will be given the appropriate options for each link type (e.g., to select a SOUR record from a list of current SOUR records or to create a new SOUR record) and then the requested link will be created. This cell can only be used for non-existing data (it is a data saving cell). The browser style is responsible for insuring such tags are allowed at the cell's location.

Second, if the CreateLinkButton cell is used in any other template (usually a non-GEDCOM tag editing template), the cell can include optionalTag commands. Those commands will add optional tags to this cell. If the user clicks the button, they can select from the list of optional tags and a new GEDCOM line with that tag will be created.

The links or optional tags will be created at the level of the location of the template containing the cell. In other words, if the Show command that calls the template is in a main record editing, template, the link or tag will be at the main record level. If the Show command is within another tag editing template, the link or tag will be created subordinate that tag.

CreateLinkButton cells inherit properties from GenericCells, ButtonCells, and LinkButton Cells and have the following additional properties.

cell Multimedia <#1>

This cell is used to display multimedia. If the multimedia can be displayed in GEDitCOM II, it will appear in the cell. The optional parameter #1 sets the text for the cell. The text can alternatively be set or appended to using the text property.

Multimedia cells inherit properties from GenericCells, ButtonCells, and LinkButton Cells. The additional or modified properties are:

cell StructuresLink #1,<#2>

This cell will create a link to a child window that can display some subset of the data for the current window when clicked. The child window will be formatted for display using the "#1 Record Editing" template. The optional parameter #2 sets a parameter that will be passed to the template and can be read with a @contents GEDCOM expression in that template.

StructuresLink cells inherit properties from GenericCells and ButtonCells. They have no additional properties, but for them to be useful, you must link them to GEDCOM data using LinkAll commands.

cell CheckBoxEdit <#1>

This cell has a check box for editing a property with one of two possible values. The optional parameter #1 sets the text for the cell. The text can alternatively be set or appended by using the text property.

CheckBoxEdit cells inherit properties from GenericCells and ButtonCells and have the following additional properties:

cell PopupMenuEdit

This cell displays a popup menu for the user to select one of several settings for GEDCOM data. It inherits properties from GenericCells and has the following additional properties:

cell GroupBox

Group boxes contain any number of cells in an optionally bordered box. You start a group box with the cell GroupBox command and then create cells in the box. When the box in done, use and EndGroup command.

When in a group box, the left and right margins are relative to the box edges rather than the window edges. The top and bottom margins will use the current line separation (#lineSkip). Group boxes cannot be nested.

GroupBoxes inherit properties from GenericCells and have the following additional properties:

cell Palette

Palette cells are used for adding simple graphics to the window. They inherit properties from GenericCells, most importantly the properties to set the size of the cell. Once the cell is created, you use a series of commands (not properties) to draw things in the palette. The drawing coordinates are the pixels in the cell with the top-left corner being (0,0), x increasing to the right, y increasing moving down, and the bottom right corner being (width, height) of the cell. All drawing will be clipped to the boundaries of the cell.

The drawing commands are listed below. Line drawing commands use the current color and line width (set with PalDrawColor and PalLineWidth) commands. The fill commands use the current color:

cell PaneBar

PaneBar cells create a row of buttons whose only function is to provide links to other panes when writing browser styles that use display records in multiple panes. After the cell is created, use the AddPane command to add each button to the row of buttons. Other properties that can be set are listed below.

PaneBars inherit properties from GenericCells and have the following additional (or changed) properties:

Notes

  1. All commands that set colors should use a named color. Alternatively, a color can be one of the following color names: black, blue, brown, cyan, darkGray, gray, green, lightGray, magenta, orange, purple, red, white, and yellow. If it makes sense (e.g., for cell background), the color can be "none." Finally, a color be "Control Text" to set to the color the MacOS uses for controls (and that color depends on whether using light or dark mode).