tc_doc

Actions on document fields and spreadsheet areas. 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:

• begin_edit_current_area(ref*) Start editing the current spreadsheet area; follow with input_text and end_edit_current_area. In view mode this can instead open a drill-down menu, object or field chooser. A menu may leave the active window unchanged; use execute_choice_from_menu to continue.

• click_formatted_doc_hyperlink(ref*, index*) Click a hyperlink in a formatted-document field by 0-based index (or by its text). On a document without links the platform answers the same and puts up its own error window, and tc_doc(action="get_formatted_string_hyperlinks") cannot be used to check first: for a formatted DOCUMENT it answers with an empty list even when the document does have a link (it lists links only for a formatted-string label). Judge by what the click was supposed to do. (1C 8.3.25+)

• click_formatted_string_hyperlink(ref*, index*) Click a hyperlink in a formatted string by 0-based index (or by its text). ref may be a label field or a form decoration bearing the formatted string. (1C 8.3.13+)

• click_html_hyperlink(ref*, index*) Click an HTML link. The platform may open the FIRST link regardless of an in-range index; out-of-range indexes fail. text has no effect. Verify the resulting navigation. (1C 8.3.25+)

• end_edit_current_area(ref*, cancel=False) Finish editing the current spreadsheet-document area. Set cancel to discard the edit instead of committing it. Returns the cell address and its text before/after finishing; changed compares those values, including when an edit is cancelled.

• find_text(ref*, text*, match='contains', case_sensitive=False, area=null, start_address=null, max_cells=1000) Find literal spreadsheet text (match=contains/exact, case-insensitive by default); return cell addresses/text without moving the current area. area restricts a cell/rectangle (8.3.25+). max_cells=1..10000 limits scanned positions, not matches. If complete=false, resume with start_address=next_address and unchanged text/match/case_sensitive/area. Empty matches proves absence only in the successfully scanned part. (1C 8.3.13+)

• get_area_text(ref*, area=null) Get the text of ONE spreadsheet-document area; omit area to read the current one. tc_doc(action="get_current_area_text") is the older form of this same call and answers identically; prefer this one. (1C 8.3.6+)

• get_current_area_address(ref*) Get the address of the current spreadsheet-document area.

• get_current_area_field(ref*) Get the field of the current spreadsheet-document area. (1C 8.3.2+)

• get_current_area_text(ref*, area=null) Get the text of ONE spreadsheet-document area; omit area to read the current one. This is the older form of tc_doc(action="get_area_text"), which the platform deprecated in 8.3.6 in favour of that one; prefer get_area_text.

• get_doc_area_horizontal_size(ref*) Get the horizontal size (max column number holding data) of a spreadsheet-document. (1C 8.3.13+)

• get_doc_area_vertical_size(ref*) Get the vertical size (max row number holding data) of a spreadsheet-document. (1C 8.3.13+)

• get_formatted_string_hyperlinks(ref*) Get a formatted string's hyperlink presentations. (1C 8.3.25+)

• get_html(ref*) Read the HTML of a formatted/HTML-document field. After the form has put up a menu or a modal choice list, the platform stops returning this field's content until it is written again — an empty answer right after such a window does not mean the field is empty. (1C 8.3.8+)

• included_in_merged_area(ref*, address*) Return the address of the merged area containing the cell (e.g. 'R1C1'), or None if the cell is not part of a merged area. A null answer is ambiguous in one more way: it also comes back when the document has no such cell or no area by that name — the platform does not distinguish the two, and neither can this action. Only the FORM of the address is checked here (cell, range, area name, intersection); whether it exists is up to the document. (1C 8.3.25+)

• input_html(ref*, html*, attachments=null) Set HTML/text into a formatted-document field. attachments maps an image name used in the HTML (e.g. -> "p1") to that image as a base64 string; src must exactly match the attachment name. Names must be identifiers (no dots). (1C 8.3.8+)

• read_document(ref*, start_address=null, max_cells=1000, area=null) Read nonempty spreadsheet cells as rows with cell addresses and merged-cell spans. Optional area is a rectangle such as R2C3:R8C5 (platform 8.3.25+), clipped to the document's data bounds. Intersecting merged cells retain their full address/span, even if they start outside area. If complete=false, pass next_address as start_address with the same area to continue. max_cells limits positions scanned per call (1–10000). Does not move the current area.

• set_area_text(ref*, address*, text*) Set a spreadsheet cell's text by address, e.g. R2C1. Selects the cell, starts and finishes editing, then reads the result. Empty text clears it. Returns verified, changed and value_before/value_after. Numeric formatting can return verified=null with verification=numeric_equivalent. Rounded output returns value_verification_inconclusive: editing finished, but the exact value is not verified. Requires an editable document.

• set_current_area(ref*, address*) Set the current area of a spreadsheet-document field (e.g. 'R1C1').

• text_within_area_bounds(ref*, area=null) Whether the text in a spreadsheet-document area fits within its bounds (True) or is clipped to '#####' (False). Pass area (e.g. 'R1C1'); omit to check the current cell. (1C 8.3.25+)

• write_content_to_file(ref*, filename=null, file_format=null, filter_index=null, save_as=null) Save HTML/formatted/spreadsheet/text fields (not PDF fields). filename forces Save As, replacing and finally clearing pending dialog answers on 8.3.25+; older versions cannot clear unused answers, so prepare only the next dialog. Spreadsheet file_format: mxl/html/pdf/xls/xlsx/ods/docx; extension alone does not select it. Alternatively use 0-based filter_index; mutually exclusive with file_format, omitted: first type. Without filename, use current name unless save_as=true; predefine possible dialogs before EACH call with tc_app(action="set_file_dialog_result"). ok confirms accepted requests, not completed disk writing. Final cleanup failure separately returns cleanup_error and dialog_answer_cleared=false; the next filename call retries cleanup before saving. (1C 8.3.8+) 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.