tc_table

Read and edit table or tree rows, manage selection and expand or collapse nodes. Choose action. Also available: tc_field(action="is_visible"), tc_field(action="is_enabled"), tc_field(action="get_context_menu"), tc_app(action="get_parent").

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. ok=true means accepted; verify effects by reading state. target_check: present, unknown (uncheckable), off (disabled); present does not prove an effect. target_hidden=true means the target exists but is invisible; it describes the element, not its ancestors. Its absence says nothing; hidden targets may still act (e.g. activate). Invalid addresses are rejected only where the address can be checked; an unverified empty read may mean a missing target. failure_context describes state/editor/choices; its complete=false means incomplete diagnostics. Actions:

• add_rows(ref*, rows*) Add and fill 1–100 rows: rows=[{cells:[{column: element name, text: ...}]}], at most 1000 cells. Each cell uses text for an input column or checked=true/false for a checkbox column, never both. Requires finished row editing. Stops at the first refusal; earlier edits remain. results use 0-based input indexes; added=null means creation could not be confirmed. Each completed row is checked when filled, not after later rows. Does not save the document. (1C 8.3.12+)

• can_be_expanded(ref*, row_column=null, row_value=null) Whether a table row/group can be expanded. Pass row_column+row_value to target a specific row by a column name or title; omit them to use the current row. can_expand=true does not promise that tc_table(action="expand") will work: rows reporting true have been observed to stay collapsed. The reliable evidence is tc_table(action="expand")'s own value_before/value_after pair.

• change_row(ref*) Start editing the current table row/column. Activate the intended column first. Needs an existing row not already in edit mode. edit_mode confirms whether editing started; null means it could not be checked. For text input use set_cell_text for automatic preparation.

• choose_row(ref*) Choose/double-click the current row: selects and closes a choice form, opens an item's card in a list (a folder's own card, not its contents). changed tracks ACTIVE WINDOW change only. If false, read the destination field: selection may have succeeded without closing a window.

• collapse(ref*, row_column=null, row_value=null) Collapse a form group or table node. For tables, row_column+row_value targets a row by column name/title; omitted: current row. No collapsible node is not an error. changed=false only for equal successfully read value_before/value_after; null for form groups, read failures or readback=off. can_be_expanded applies only to table rows and does not guarantee an effect; verify before/after.

• copy_row(ref*, confirm=null) Copy the current table row. On catalog/document lists a confirmation dialog may appear — set confirm=True/False to auto-answer it (default None: no dialog handling). (1C 8.3.25+)

• delete_row(ref*, confirm=null) Deprecated alias for delete_rows(scope="current"). Use delete_rows for new calls. (1C 8.3.3+)

• delete_rows(ref*, confirm=null, scope='current', unmark=False) Delete current or selected rows (selected: 8.3.6+, standard context-menu Delete/Mark, preserving selection). confirm=true/false answers; null leaves confirmation open. Lists may mark instead of remove. deleted=null means unverified. unmark=true removes marks (8.3.6+), only in lists with a standard marking command, not ordinary tables. (1C 8.3.3+)

• deselect_all_rows(ref*) Clear the table's row selection. Needs platform 8.5.1 or newer — on every earlier one the platform has no such method. Plain row navigation drops the selection down to the current row, which is the only way to undo a multi-row selection there. (1C 8.5.1+)

• deselect_row(ref*) Remove the current table row from the selection. Needs platform 8.5.1 or newer — on every earlier one the platform has no such method. The closest thing there is to pass over the row with toggle_selection set: that toggles it, so a selected row becomes unselected. (1C 8.5.1+)

• end_edit_row(ref*, cancel=False) Finish editing the current table row. Set cancel to discard the edits instead of committing them.

• expand(ref*, row_column=null, row_value=null, subordinates=False) Expand a form group or table node; subordinates also expands child rows. For tables, row_column+row_value targets a row by column name/title; omitted: current row. No expandable node is not an error. changed=false only for equal successfully read value_before/value_after; null for form groups, read failures or readback=off. can_be_expanded applies only to table rows and does not guarantee an effect; verify before/after.

• find_rows(ref*, conditions*, columns=null, case_sensitive=False, max_rows=500, max_matches=50, text_format='plain') Search selectable rows of the CURRENT table, respecting filters/collapsed groups; never a database-wide search. conditions is an AND-list of {column: displayed TITLE, text, match: exact/contains/starts_with/ends_with}; literal, case-insensitive by default. Ignore search highlighting for comparison; plain removes it in results, raw retains it. Empty text matches displayed emptiness. columns selects returned titles. max_rows bounds checked rows, not client response; max_matches bounds matches. complete covers this table; matches_truncated marks omitted matches. No stable order/row IDs. Uses read_rows: clears selection, may reposition an unavailable cursor on older platforms; refuses unfinished row edits. (1C 8.3.6+)

• get_cell_text(ref*, column*) Read the current row's displayed cell (may contain search markup). column is an element NAME or 0-based index; digit strings are indexes. Unknown/ambiguous names refuse; a matching title suggests the name. null does not prove emptiness. A COLUMN GROUP displayed as one column may return neighbouring/group text indistinguishable from the intended value; other-kind members may return null. A nonexistent table can also return text=null.

• get_current_item(ref*) Get the current item of a table → {ref}. ref: the table.

• get_current_row(ref*) Get the current table row as [{column: value}]. Returns [] if there is no current row or its values could not be read. Needs platform 8.5.1 or newer — on every earlier one, use get_selected_rows after moving to the desired row, or get_cell_text to read one column. (1C 8.5.1+)

• get_list_settings(ref*, max_rows=500, timeout=180) Read filters and sorting through the list's standard settings form. Closes settings opened by this call. filters contains expanded tree rows, including the root and groups; orders follows sort priority. Values are displayed text. max_rows limits each settings table (1–10000). timeout bounds the operation in seconds (greater than 0, at most 3600). (1C 8.3.12+)

• get_list_settings_fields(ref*, section='filters', max_rows=500, timeout=180) List available field captions for filters or orders through the standard list settings. Returns visible fields; collapsed branches are not traversed. Closes settings opened by this call. timeout limits the operation in seconds (0 < timeout <= 3600). (1C 8.3.12+)

• get_selected_rows(ref*) Read selected rows as {column title: displayed value} maps. Row order is not guaranteed. The platform chooses the columns. Missing columns are unread, not empty; empty text can also represent an omitted value. Values may contain search highlighting. Use read_rows to read all selectable rows of the current table. (1C 8.3.6+)

• go_one_level_down(ref*, row_column=null, row_value=null, column=null) Go one level down in a table tree. Pass row_column+row_value to target a specific row by a column value; row_column accepts a column name or title. Omit both to use the current row. Optional column names a column to read before and after the move; changed compares its cell text.

• go_one_level_up(ref*, row_column=null, row_value=null, column=null) Go one level up in a table tree. Pass row_column+row_value to target a specific row by a column value; row_column accepts a column name or title. Omit both to use the current row. Optional column names a column to read before and after the move; changed compares its cell text.

• goto_first_row(ref*, toggle_selection=False, column=null) Move to the first row of a table. Set toggle_selection to also toggle that row's selection. Pass column (the column element NAME) to have that cell read before and after the move: it comes back as value_before/value_after with changed=true when they differ. changed=false only means the two texts are the same — different rows can share a value; without column nothing is read and changed is null.

• goto_last_row(ref*, toggle_selection=False, column=null) Move to the last row of a table. Set toggle_selection to also toggle that row's selection. Pass column (the column element NAME) to have that cell read before and after the move: it comes back as value_before/value_after with changed=true when they differ. changed=false only means the two texts are the same — different rows can share a value; without column nothing is read and changed is null.

• goto_next_item(ref*) Move to the next item within a table. ref: the table.

• goto_next_row(ref*, toggle_selection=False, column=null) Move to the next row of a table. Set toggle_selection to also toggle that row's selection. Pass column (the column element NAME) to have that cell read before and after the move: it comes back as value_before/value_after with changed=true when they differ. changed=false only means the two texts are the same — different rows can share a value; without column nothing is read and changed is null.

• goto_previous_item(ref*) Move to the previous item within a table. ref: the table.

• goto_previous_row(ref*, toggle_selection=False, column=null) Move to the previous row of a table. Set toggle_selection to also toggle that row's selection. Pass column (the column element NAME) to have that cell read before and after the move: it comes back as value_before/value_after with changed=true when they differ. changed=false only means the two texts are the same — different rows can share a value; without column nothing is read and changed is null.

• goto_row(ref*, column=null, value=null, direction='down', toggle_selection=False, fields=null) Seek by column (displayed TITLE, not index) and value, or fields={title:value} for multiple columns; do not combine them. Values accept int/string and * ? wildcards; matching is case-sensitive displayed text. Searches FROM AND INCLUDING current row towards down/up, without wrapping. Step away first for the next match. A miss moves to the last row going down, or the first going up. toggle_selection toggles the destination; without criteria, the current row. found=null means no criteria or undetermined, never not-found. criteria uses titles; observed.column uses the element name. Refuses inactive containing pages. (1C 8.3.2+)

• is_expanded(ref*, row_column=null, row_value=null) Whether a table row is expanded. Without row_column this reads the CURRENT row. Pass row_column (column name or title) and row_value to read another row without moving the cursor.

• read_rows(ref*, max_rows=500, columns=null, text_format='plain') Read selectable rows within current filters/collapsed groups: row_count and at most max_rows (0: count only), unordered. columns selects returned titles; plain strips known search highlighting, raw retains it. Temporarily selects rows, then clears ALL previous selection. Keeps a usable current row; older platforms may move an unavailable cursor to first (cursor_repositioned=true). Single-selection tables are read sequentially (10000-row, 180-second scan limits), restoring the current row. Refuses unfinished row edits and inactive containing pages. (1C 8.3.6+)

• search(ref*, text*, max_rows=500, timeout=180, settle_time=2, columns=null, text_format='plain') Set the list's standard search string (empty clears), preserving filters. Returns rows after input readback and two equal row reads settle_time seconds apart; stability is not a platform completion signal. max_rows=1..10000; truncated means more rows. 0<settle_time<timeout<=3600; timeout covers the action. columns selects titles; raw retains search highlighting. Reading clears selection; unfinished edits refuse. (1C 8.3.12+)

• select_all_rows(ref*) Select all rows of a table. (1C 8.3.6+)

• select_row(ref*) Add the current table row to the selection. Needs platform 8.5.1 or newer — on every earlier one the platform has no such method. Build a selection there by moving through rows with toggle_selection set — each row the cursor passes is toggled. (1C 8.5.1+)

• set_cell_text(ref*, column*, text*) Set current-row column by element NAME; manages focus, continues existing row edits, finishes without discarding other cells, then reads back. Empty text clears. Returns verified/changed and displayed value_before/value_after; empty_value confirms emptiness despite formatting; numeric_equivalent may give verified=null. row_edit_pending means validation/reference choice kept editing: continue at the returned editor or end_edit_row(cancel=true). value_verification_inconclusive means editing finished but rounded output prevents exact verification.

• set_list_settings(ref*, filters=null, orders=null, replace=False, max_rows=500, timeout=180) Apply standard list filters/sorting; field is an exact available caption, value is displayed text. filters/orders follow their schemas. Adds by default; replace=true replaces only supplied sections ([] clears one). Success applies and closes settings; failure leaves them open and earlier edits may remain. 0<timeout<=3600 seconds covers the operation. (1C 8.3.12+)

• set_order(ref*, column*) Sort a table by a column, addressed by its TITLE. There is no direction parameter and no way to read the current direction: calling it again on the same column reverses the order. To learn which way it went, go to the first row and read a cell. (1C 8.3.6+)

• set_row_values(ref*, cells*) Fill 1..100 cells of the current row: {column: element NAME, text} or {column, checked}. Matching checkboxes are not toggled. Continues editing, finishes once after all entries, then reads back. Refusal/unexpected editor stops with earlier edits preserved for completion/cancel. completed counts entries; edit_finished confirms row completion; final_verified=null may mean numeric equivalence. Results use 0-based input order. Does not add rows, alter selection or save. (1C 8.3.12+)

• switch_row_delete_mark(ref*, confirm=True) Toggle the current row's deletion mark; confirm=true answers Yes, false No. dialog_answered proves only a response; changed is always null (no readable mark flag). To verify, invoke the mark command again and read its question: mark means currently unmarked, remove mark means marked. (1C 8.3.6+)

• table_add_row(ref*) Add a row to a form table. Fill its cells with set_cell_text using column element names. ref selects the client; otherwise set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in ref; re-find expired elements.