tc_form

Actions on the managed form itself, including navigation between form elements and reading the focused element. 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:

• compare_snapshot(snapshot_id*, ref=null) Compare the original form instance with its baseline; optional ref must identify the same instance. Returns changes/added/removed; observed means previously unread properties, not changes. complete/baseline_complete/errors mark read gaps. Uses baseline table settings; table_changes matches 1-based row positions and column titles, *_present distinguishes missing/empty cells. Tables are prepared before reading and stay selected; truncated tables are not compared. Added flags: '-' unread, 'unknown' failed. Stores no new snapshot; closed/reconnected forms need a new baseline. (1C 8.3.3+)

• create_snapshot(ref=null, include_tables=False, max_rows=500) Save ManagedForm state (default active) for later compare_snapshot; returns snapshot_id/summary. Reads visibility/availability/read-only and ordinary values; hidden branches skip further reads, disabled elements skip read-only. include_tables adds display-ordered rows up to max_rows each without expanding trees; requires active form/finished input (8.3.6+). Tables requiring sequential navigation report table_requires_sequential_read and complete=false; use read_rows separately. Rows stay selected; 8.3 may activate/establish current rows. Preparation precedes final reading. Excludes document contents; sequential, not atomic; may take seconds. (1C 8.3.3+)

• current_modified(ref*) Whether a form has been modified. (1C 8.3.3+)

• delete_snapshot(snapshot_id*) Delete a saved snapshot belonging to this connection.

• execute_choice_from_list(ref*, index*) Pick an item from a modal choice list by 0-based index or display text. Not a field's drop-down (use tc_field(action="choose_from_drop_list")). ref: the form (ManagedForm), not a field. (1C 8.3.8+)

• execute_choice_from_menu(ref*, index*) Choose an item from an open menu by 0-based index or display text. For a submenu, call again to choose its item. Address the form or the spreadsheet field that opened the menu. A spreadsheet field requires platform 8.3.25 or newer. (1C 8.3.8+)

• find_default_button(ref*) Find the form's default button. ref is the form's ref. (1C 8.3.3+)

• get_context(ref=null, save_as_snapshot=False, include_tables=False, max_rows=500, root_ref=null, visible_only=False, include_commands=True, result_mode='changes') Inspect ManagedForm elements (including hidden), state, values and input context; includes discovery, so no separate search is needed. Use tc_find(action="find_objects") alone for element lookup. May take seconds. result_mode=changes returns a full first read, then only new/changed elements and removed objects since the previous complete read of this form; changed=false means no changes. Other interaction fields describe the current state. full returns everything. result_mode and full_reason identify the actual response; context_id/compared_to identify automatic baselines. Filter changes or lost baselines return full. Incomplete reads return full and keep the prior baseline. save_as_snapshot creates a separate fixed snapshot for compare_snapshot without another read. include_tables adds up to max_rows per table without expanding trees; rows stay selected, 8.3 may activate rows. Excludes document contents. Flags: '-' unread, 'unknown' failed, null unavailable (not empty). form_details reports optional hints/type restrictions/choices availability. root_ref limits output to a subtree; include_commands=false omits buttons/command groups; visible_only excludes known hidden/inactive pages, retains unknown visibility. Output filters do not narrow reading or fixed snapshot scope. complete/errors mark read gaps; snapshot_error marks failed saving. Sequential reads. (1C 8.3.3+)

• get_current_element(ref*) Get the managed form's focused element as item: [{ref}]. ref: the form (ManagedForm). The platform can return no current element after navigating out of its fields.

• goto_next_element(ref*) Move focus to the next element in the managed form's tab order. ref: the form (ManagedForm). This can finish the current field's pending input; read the field's data presentation to verify acceptance. Reference fields may still require choosing a value.

• goto_previous_element(ref*) Move focus to the previous element in the managed form's tab order. ref: the form (ManagedForm). This can finish the current field's pending input; read the field's data presentation to verify acceptance.

• list_snapshots(ref=null) List saved snapshots for this connection, optionally restricted to one ManagedForm ref. Returns IDs, form titles, timestamps, element counts, sizes and global storage limits. Listing does not refresh last_used_at or verify forms are still open; a supplied ref is validated.

• wait_for_closing(window_title=null, timeout=60) Wait until a window closes, up to timeout seconds. Without window_title, watch the window active AT THE MOMENT OF THE CALL. After a close, pass window_title to check the closed window. Switching windows or opening a preview does not count as closing. If the target cannot be identified or its absence confirmed, return ok=False. (1C 8.3.3+) ref/root_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/root_ref; re-find expired elements.