tc_field

Actions on a form field, button, group or element addition. Choose action. Common operations for objects of this type live elsewhere: tc_app(action="get_parent"). In the signatures below a trailing * marks a REQUIRED parameter — the group schema itself accepts every parameter as optional. ok: true means the client accepted the command, not that anything changed — confirm an effect by reading the state back; target_check: present is not proof of one either. Where the address can be checked the response carries target_check: present, unknown (not checkable here) or off (checking disabled). target_hidden: true appears ONLY when the target exists and was NOT visible; it does NOT prove the absence of an effect — for tc_field(action="activate") invisibility is the normal precondition — it describes the ELEMENT itself and not an invisible container around it, and its absence says nothing. A wrong address is refused with an error only where the address can be checked: a read without a target marker cannot tell one from an empty answer, and tc_table(action="get_cell_text") on a table that does not exist returns text=null exactly as for an empty cell. Actions:

• activate(ref*) Give a form element the focus — this is how you switch to a page or make a table column the current cell; a click does neither. It also commits text left uncommitted by tc_field(action="input_text"), but only when you activate a DIFFERENT focusable element: the field you typed into already has the focus. To let the form choose the next focus target, use tc_form(action="goto_next_element") on the form. Reports no changed — verify with tc_field(action="get_text"), tc_field(action="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. 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*) Click a form element (button, cell, etc.). A click PRESSES the element; it does not make it current — clicking a page does not switch to it and clicking a cell does not make it the current cell. Use tc_field(action="activate") for that.

• 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 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").

• get_choice_list(ref*) Get a field's choice list. Read it while the drop-down list is OPEN: with the list closed the answer is empty and status is 'unknown', which is normal, not an error. The answer describes the list that is currently OPEN, not the element you addressed — with one field list open, any other field ref returns that same list with status='ok'. Open the list on the field you are asking about (tc_field(action="open_drop_list")) and read it immediately. 'items' holds {presentation, text} per entry; 'presentations' is just their texts, which is exactly what tc_field(action="choose_from_drop_list") accepts. (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 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 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. Ordinary form input fields finish automatically: the owning form moves focus once to its next element, then the accepted value is checked. finish=false leaves the editing buffer active, for example before choosing a reference suggestion or cancelling. Empty text clears the value directly. Reference input can still need a matching value. committed=true confirms the accepted text; false means pending; null means unverified. edit_finished reports whether focus left the ordinary field. Numeric formatting can produce verification=numeric_equivalent with committed=null. changed compares displayed text. These flags do not mean the record was saved. Table cells use tc_table(action="set_cell_text"). Text documents finish by activating another element with tc_field(action="activate"); spreadsheet cells use tc_doc(action="end_edit_current_area").

• is_enabled(ref*) Whether an element is currently enabled. (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).

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

• 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.

• start_choosing(ref*) Open a reference field's choice form. Handles focus and table-cell editing. Returns opened and the active window; use that window to continue choosing.

• 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 up to timeout seconds for a drop-down list to be generated. Returns generated=True if a list appeared within the timeout, else False. The answer is not tied to the element you addressed — it can come back true before this field's list is open at all, the same way get_choice_list describes. Open the list on the field you care about first (tc_field(action="open_drop_list")) and read it right after. (1C 8.3.4+) connection_id selects the client. Passing ref selects the client automatically; otherwise, with several clients, connection_id is required. Use tc_session(action="list_connections"). Pass reference values returned by the tools unchanged in ref. If a reference expires, find the element again.