tc_field

Actions on a form field, button, group or element addition. Choose action. Also available: 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:

• activate(ref*) Focus an element, switch a page or make a table column current; click does not do this. Commits pending input_text only by focusing a DIFFERENT focusable element; tc_form(action="goto_next_element") lets the form choose. Reports page visibility; still hidden returns target_hidden. No changed flag: verify via get_text/get_current_page, tc_form(action="get_current_element") or tc_table(action="get_current_item").

• cancel_edit(ref*) Cancel editing an input field. (1C 8.3.6+)

• choose_from_drop_list(ref*, value*) Pick a value from a field's open drop-down list by its display text (e.g. a colour name) or by its 0-based index in the list. The value is written at once — no focus change is needed. changed may come back null here even when the value did change: with the list open the value cannot be read. A changed window is returned when readback is enabled; inspect it before continuing. window_changed=false reuses the previous window description. Read the field with tc_field(action="get_text") to confirm. (1C 8.3.6+)

• clear(ref*) Clear an input field's value.

• click(ref*, diagnostics=False, diagnostics_wait=2.0) Click a button, field, group, decoration or command-interface button. Use activate to focus inputs/cells/pages. window, when present, is the active window afterwards. window_changed=false means the previous window description still applies. diagnostics=true also reads messages, possibly from earlier actions. diagnostics_wait=0..60 seconds polls while messages are unavailable/empty; 0 reads once. Individual requests use set_max_action_time. diagnostics.status is read/unavailable/failed; null messages are not an empty list. ok or absent messages do not prove business success.

• click_view_status_item(ref*, index*) Click a view-status item by 0-based index (or by its text). Nothing here proves the item was there: the platform answers the same when the form has no view-status line at all, and reading the texts first does not settle it either — that read comes back empty even while a search or filter is active. Judge by the list itself: read the rows before and after. (1C 8.3.16+)

• close_drop_list(ref*) Close a field's drop-down list. Verify with tc_field(action="drop_list_is_open"). (1C 8.3.6+)

• create(ref*) Create a new object from a reference field: opens the new object's form, as the field's '+' does. The field must have the FOCUS first — call tc_field(action="activate") on it, otherwise the command is accepted and nothing opens. Verify by reading the active window. (1C 8.3.6+)

• current_check(ref*) Whether a form BUTTON is pressed, or shows a check mark next to it. Only buttons answer meaningfully: anything else — a checkbox field, a page, a table — always reports false, which means 'not applicable', not 'switched off'. Read a checkbox with tc_field(action="get_text") ('Да'/'Нет') and the active page with tc_field(action="get_current_page"). (1C 8.3.16+)

• current_mode_is_edit(ref*) Whether a table row or spreadsheet-document field is currently in edit mode. (1C 8.3.3+)

• current_opened(ref*) Whether a form group is currently open. (1C 8.3.16+)

• decrease_value(ref*) Decrement a numeric (spinner) field. A track bar does NOT take this — move it with tc_field(action="goto_value") in percent. When the value does not move, applicable: false in the answer means the method does not fit this kind of field.

• delete_view_status_item(ref*, index*) Delete a view-status item by 0-based index (or by its text) — this is how a filter or a search chip is dropped. Nothing here proves the item was there: the platform answers the same when the form has no view-status line, and reading the texts first does not settle it either. Judge by the list itself: read the rows before and after. (1C 8.3.16+)

• drop_list_is_open(ref*) Whether a field's drop-down list is open. (1C 8.3.6+)

• execute_choice_from_choice_list(ref*, value*) Pick from a field's choice list by its display text or by its 0-based index. Reports changed/value_before/value_after — the field's value read before and after, same as tc_field(action="choose_from_drop_list"). A changed window is returned with readback enabled. window_changed=false reuses the previous window description.

• get_choice_list(ref*) Read radio-button options, an input's open drop-down list or a form's open choice list. For an input, open its list immediately before reading: the answer describes whichever drop-down is currently open. items contains {presentation, text}; presentations contains the displayed texts to select. A closed input list may return items=[] with status=unknown. (1C 8.3.12+)

• get_command_bar(ref*) Get an element's own command panel object, if it has one. This is NOT the list of buttons: the panel is a container, and its buttons are read with a separate tc_app(action="get_child_objects") on the returned ref. An empty result means the element has no command panel of its own — a list table is the usual case, its buttons live in a form group next to it. (1C 8.3.3+)

• get_context_menu(ref*) Get an element's context menu. The platform returns the menu as a form GROUP, not as a list of commands: 'menu' holds that group, and its items are read with a separate tc_app(action="get_child_objects") on the group's ref. (1C 8.3.3+)

• get_current_page(ref*) Get the current page of a page group. To switch pages use tc_field(action="activate"): a click on a page does not switch to it. tc_field(action="current_check") is useless here — pages always report checked=false. (1C 8.3.6+)

• get_data_presentation(ref*) Get an element's data presentation. Form fields only — not form decorations, and on a table the answer is always null. An empty input or label field returns "". presentation is null when no value was available; that is not proof that the field has no presentation.

• get_edit_text(ref*) Read an input field's edit buffer — what is being typed, which is not necessarily what the form holds. get_data_presentation reads the accepted value; get_text reads displayed text. An empty input buffer returns ""; null means unavailable. (1C 8.3.3+)

• get_linked_window(ref*) Get the linked window of a command-interface button. An empty answer means the button has no linked window — but only when target_check says the button itself is there; a wrong ref answers empty too, and the check is what tells the two apart. (1C 8.3.6+)

• get_state_presentation(ref*) Read a form field's state presentation. An unavailable value is explained in the answer; null does not confirm that the field has no state presentation. (1C 8.3.16+)

• get_text(ref*) Read displayed text (checkbox text follows the client language). An empty input or label field returns "". For an edit buffer use get_edit_text. If text is unavailable, the answer explains the limitation and suggests another reading action where applicable. null does not confirm an empty field. (1C 8.3.12+)

• get_tooltip(ref*) Read an element's tooltip text (empty → None). (1C 8.3.3+)

• get_view_status_item_texts(ref*) Get the view-status item texts of a form-element addition → list of strings. Do not use it to tell whether a filter or search is active: with a list narrowed down to one row by search the platform still answers with an empty collection. Check the effect by reading the rows. (1C 8.3.16+)

• goto_value(ref*, percent*) Move a TRACK BAR to a value in PERCENT (0..100). This is a track bar method: on any other kind of field the command is accepted and nothing moves, and the answer then carries applicable: false. A spinner is stepped with increase_value/decrease_value instead. Returns changed/value_before/value_after. (1C 8.3.6+)

• increase_value(ref*) Increment a numeric (spinner) field. A track bar does NOT take this — move it with tc_field(action="goto_value") in percent. When the value does not move, applicable: false in the answer means the method does not fit this kind of field.

• input_text(ref*, text*, finish=True) Enter text; text="" clears. finish=true moves the owning form's focus once and verifies ordinary input; false keeps the edit buffer (e.g. for reference choice/cancel). Reference input may still require selection. Changed pending text causes pending_input_changed: re-enter or cancel. committed=true/false/null means accepted/pending/unverified; edit_finished means focus left; changed compares displayed text. Numeric formatting may yield verification=numeric_equivalent and committed=null. These flags do not confirm saving. For table cells use tc_table(action="set_cell_text"); finish text documents with activate on another element, spreadsheet cells with tc_doc end_edit_current_area.

• is_enabled(ref*) Read the element's availability. A command can still refuse execution in the current form state. (1C 8.3.3+)

• is_readonly(ref*) Whether an element is currently read-only — that is the element's own read-only property. Two other things look the same and are NOT this: an element switched off entirely (read that with tc_field(action="is_enabled")), and a spreadsheet-document field shown in view mode, which neither read reflects — there, tc_doc(action="begin_edit_current_area") runs the cell's details instead of editing. (1C 8.3.3+)

• is_visible(ref*) Whether an element is currently visible. Returns an error instead of visible=false when there is no object at ref: for this read the protocol does report a missing target, so a mistyped address cannot pass for a hidden element. On the pages of a page group this does NOT tell you which page is on screen — several pages report visible=true at once; use tc_field(action="get_current_page") for that. (1C 8.3.3+)

• open_drop_list(ref*) Open the drop-down list of a reference/enum field (call before choose_from_drop_list). (1C 8.3.6+)

• open_field(ref*) Open a reference field's value (F4 / follow the link).

• read_fields(targets*, properties=null) Read 1–100 fields of the active form without moving focus. properties defaults to ['text']; presentation reads data, edit_text reads the editing buffer. visible/enabled/readonly are optional. Table-column text reads the current row. Results follow input order (index is 0-based); unavailable properties remain null with a reason. Reads are sequential, not an atomic snapshot. targets is an array of {ref} objects returned by discovery. (1C 8.3.12+)

• select_option(ref*, value*) Pick a radio-button option by its display text or by its 0-based index.

• select_value(ref*, value=null, match=null, choice_table=null, choice_column=null, data_type=null, expected=null, max_rows=500, timeout=180) Select exact value text (drop-down first) or match={column title: exact text} in a choice form. Ambiguous/incomplete searches refuse selection. choice_table is an exact table name; choice_column limits value to a column title; data_type chooses a displayed type in the standard type dialog. expected checks accepted field text. Returns accepted value and verification. max_rows=1..10000; timeout is in seconds, 0<timeout<=3600, and covers the action. Failure leaves the UI and does not undo sent choices. Table cells use the current row and leave row editing open. (1C 8.3.12+)

• set_check(ref*) Toggle a checkbox field. Inside a table this acts on the column that is the CURRENT cell, so make the target column current first — tc_field(action="activate") on the column element does that; a click on the cell does not.

• set_fields(entries*) Fill 1..100 input fields or checkboxes in one active form, in order. Each entry has exactly one of text, checked (boolean), or select={value: exact text} / select={match: {column title: exact text}}; select accepts tc_field(action="select_value") options. Empty text clears; matching checkboxes are not toggled, unknown states stop (Russian/English Yes/No supported). Stops on refusal, pending choice, window change or unconfirmed value; earlier changes remain. Rechecks all values at the end; final_verified=null may mean equivalent numeric formatting. Results use 0-based input indexes. Does not save the document. entries contains {ref, text}, {ref, checked}, or {ref, select} objects; use discovered references unchanged. (1C 8.3.12+)

• start_choosing(ref*) Open a reference field's choice form. Handles focus and table-cell editing. For CalendarField, selects the current date like a double-click; use goto_date first. Returns opened and the active window. A calendar selection need not open another window.

• start_choosing_from_choice_list(ref*) Start choosing from a field's choice list.

• title_is_shown(ref*) Whether an element's title is shown. (1C 8.3.25+)

• wait_for_drop_list_generation(ref*, timeout=60) Wait timeout seconds (integer 0..65535) for a generated drop-down; returns generated. The result is not tied to ref and may be true before this field's list opens. Open this field's list first, then read it immediately. (1C 8.3.4+) ref selects the client; otherwise set connection_id when several clients are connected. targets/entries references also select it; all must belong to one connection. 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.