Programming With Table Identifiers
A table identifier is the number by which your program addresses a table in a TXTextControl. With it, your code reads and changes the text and the attributes of a table from anywhere in the document, whether or not the input position is inside that table.
Identifiers are optional, but they are recommended whenever the program, rather than the end user, changes a table's text or attributes. Read on for how identifiers are assigned, when they survive saving and pasting, and which events report them.
What a Table Identifier Is
A table has one of two kinds of identifier:
- A user-defined identifier. Your program sets it when it inserts the table with the TableInsert method, in its optional
TableIdparameter, a number from 10 to 32,767. It doesn't need to be unique, and it remains valid when the table is saved and reloaded. - An identifier that TX Text Control selects. When you set no identifier, TX Text Control returns one of its own. It is unique, but it does not remain valid when the table is saved and reloaded.
Keep or Lose an Identifier When Tables Are Inserted
What happens to an identifier depends on where a table, or a part of one, is inserted:
- Inside another table. The inserted table becomes a part of the existing table, and its identifier is lost.
- Outside of all existing tables, with a user-defined identifier. A new table is created and its identifier remains valid. TX Text Control informs your program with the TableCreated event that a new table has been created. To give the table a different identifier, set the event's NewTableId parameter.
- From another application. Such a table cannot have a user-defined identifier. TX Text Control sends an identifier it selected itself with the TableCreated event, and your program can change it in the same way.
Handle Tables Loaded From a Document
When tables are imported with the Load method, TableCreated events occur only in two cases:
- the text is inserted into an existing document, or
- an imported table has no user-defined identifier.
A table with a user-defined identifier that is saved and reloaded raises no event.
React When a Table Is Deleted
When a table is deleted completely, TX Text Control informs your program with the TableDeleted event.
Access a Table by Its Identifier
The following properties take a table identifier. They get information about a table or set its attributes regardless of whether the current input position is inside this table:
| Member | Description |
|---|---|
| TableCellText | Gets or sets the text contents of a certain table cell. |
| TableColumns | Gets a table's number of columns. |
| TableRows | Gets a table's number of rows. |
When more than one table with a certain identifier exists, these properties work with the originally inserted table. In a chain of linked windows, you can use them with any TXTextControl in the chain, regardless of which control contains the table.