tc_doc

Actions on document fields and spreadsheet areas. Choose action. Common operations for objects of this type live elsewhere: tc_field(action="is_visible"), tc_field(action="is_enabled"), tc_field(action="get_context_menu"), 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:

• begin_edit_current_area(ref*) Start editing the current spreadsheet-document area. Follow with input_text then end_edit_current_area to commit a new cell value. On a field that does NOT allow editing this does something else entirely: it runs the current cell's DETAILS — the platform's drill-down. It opens the object behind the cell, or a field chooser for a total, and choosing a row there gives the drill-down report. Set the current cell with set_current_area first.

• 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 a hyperlink in an HTML-document field. The platform clicks the FIRST link whatever you pass: measured with three links and an index of 0, 1 and 2, and the same encoding the platform's own test manager sends. An index beyond the number of links is refused, so the argument is read — it just does not choose. Addressing by text does nothing at all here. (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.

• 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; names must be identifiers (no dots). (1C 8.3.8+)

• read_document(ref*, start_address=null, max_cells=1000) Read nonempty spreadsheet cells as rows with cell addresses and merged-cell spans. Uses the document's data bounds. If complete=false, pass next_address as start_address to continue. max_cells limits positions scanned per call (1–10000).

• 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. 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 an HTML, formatted, spreadsheet or text document field. PDF fields do not support this action. With filename, Save As is used even for a previously saved document; this call replaces pending file-dialog answers and clears its answer afterwards. For spreadsheets choose file_format: mxl, html, pdf, xls, xlsx, ods or docx. Example: filename="C:/exports/report.xlsx", file_format="xlsx". The extension alone does not select a format. Alternatively filter_index selects a dialog's file type (0-based); do not combine it with file_format. Without either option the dialog's first file type is selected. Without filename, saves under the current name unless save_as=true. If a dialog can appear, prepare it before EACH call using tc_app(action="set_file_dialog_result"). ok confirms that the save request was accepted, not that a file has finished writing. (1C 8.3.8+) 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.