diff options
| author | Jean-Pierre Ledure <jp@ledure.be> | 2024-03-15 15:55:45 +0100 |
|---|---|---|
| committer | Jean-Pierre Ledure <jp@ledure.be> | 2024-03-15 17:27:00 +0100 |
| commit | c5e0c65bd26664349fb7c80a792e2fe949fee0fe (patch) | |
| tree | 653b60ad4f7f861f3b642ea8b8fb850b601d447c /wizards | |
| parent | a6bb2e837264451ed896dd6783249e335e145605 (diff) | |
ScriptForge - Python typing hints
Python typing hints may be stored either
- inside the original .py source file
- in a separate .pyi source file (aka. STUB).
Choice is made to create a new scriptforge.pyi file
- to allow hiding the private functions
- to specialize each module: technical doc
vs. user doc
- to allow potential later translation
- to minimize the impact at run-time:
stubs are active only during code edition.
The new scriptforge.pyi module
- provides the static type checking of all the public
interfaces (methods/properties) of the ScriptForge API.
- when the user uses an IDE like PyCharm or VSCode,
(s)he might benefit from the typing hints provided
by the signatures and docstrings stored
in the module.
Visually, while editing a user script:
- hovering an object instance, a method or a property
displays its detailed description
- a "." after an object instance displays a drop-down
box listing all available interfaces
- brackets after a method-name start code-completion
by displaying its arguments.
Limitations: SF supports ProperCase, lowercase and
camelCase naming for methods and properties.
Only ProperCase is described in scriptforge.pyi.
Extending to the other 2 notations would be easy
but would also overload needlessly the drop-down lists.
The effective code (scriptforge.py) is completed
with a series of importable variable types,
corresponding roughly with the available service
instance names in uppercase. Example
from scriptforge import CALC, RANGE
def userfct(c: CALC, r: RANGE) -> RANGE:
r1: RANGE = "A1:K10"
Objective: enrich the signatures in user scripts
and benefit from the same hints when the variable
types cannot be derived from the context.
The help documentation should be complemented
with the actual additional feature.
Change-Id: I6c39939a3cdbed94828e9449cd691fe15c24c923
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/164867
Reviewed-by: Jean-Pierre Ledure <jp@ledure.be>
Tested-by: Jenkins
Diffstat (limited to 'wizards')
| -rw-r--r-- | wizards/Package_scriptforge.mk | 1 | ||||
| -rw-r--r-- | wizards/source/scriptforge/python/scriptforge.py | 104 | ||||
| -rw-r--r-- | wizards/source/scriptforge/python/scriptforge.pyi | 7232 |
3 files changed, 7317 insertions, 20 deletions
diff --git a/wizards/Package_scriptforge.mk b/wizards/Package_scriptforge.mk index 4cd78e1f4982..96b5a907a321 100644 --- a/wizards/Package_scriptforge.mk +++ b/wizards/Package_scriptforge.mk @@ -57,5 +57,6 @@ $(eval $(call gb_Package_add_files,wizards_basicsrvscriptforge,$(LIBO_SHARE_FOLD $(eval $(call gb_Package_add_files,wizards_basicsrvscriptforge,$(LIBO_LIB_PYUNO_FOLDER),\ python/scriptforge.py \ + python/scriptforge.pyi \ )) # vim: set noet sw=4 ts=4: diff --git a/wizards/source/scriptforge/python/scriptforge.py b/wizards/source/scriptforge/python/scriptforge.py index de590875c961..e339ada06d63 100644 --- a/wizards/source/scriptforge/python/scriptforge.py +++ b/wizards/source/scriptforge/python/scriptforge.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- -# Copyright 2020-2024 Jean-Pierre LEDURE, Rafael LIMA, Alain ROMEDENNE +# Copyright 2020-2024 Jean-Pierre LEDURE, Rafael LIMA, @AmourSpirit, Alain ROMEDENNE # ===================================================================================================================== # === The ScriptForge library and its associated libraries are part of the LibreOffice project. === @@ -38,6 +38,11 @@ - implements a protocol between those interfaces and, when appropriate, the corresponding ScriptForge Basic libraries implementing the requested services. + The scriptforge.pyi module + - provides the static type checking of all the visible interfaces of the ScriptForge API. + - when the user uses an IDE like PyCharm or VSCode, (s)he might benefit from the typing + hints provided by them thanks to the twin scriptforhe.pyi module. + Usage: When Python and LibreOffice run in the same process (usual case): @@ -45,10 +50,13 @@ When Python and LibreOffice are started in separate processes, LibreOffice being started from console ... (example for Linux with port = 2023) - ./soffice --accept='socket,host=localhost,port=2023;urp;' + ./soffice --accept='socket,host=localhost,port=2024;urp;' then use next statements: from scriptforge import CreateScriptService, ScriptForge - ScriptForge(hostname = 'localhost', port = 2023) + ScriptForge(hostname = 'localhost', port = 2024) + + When the user uses an IDE like PyCharm or VSCode, (s)he might benefit from the typing + hints provided by them thanks to the twin scriptforhe.pyi module. Specific documentation about the use of ScriptForge from Python scripts: https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/sf_intro.html?DbPAR=BASIC @@ -59,6 +67,7 @@ import uno import datetime import time import os +from typing import TypeVar class _Singleton(type): @@ -446,10 +455,10 @@ class ScriptForge(object, metaclass = _Singleton): class SFServices(object): """ - Generic implementation of a parent Service class - Every service must subclass this class to be recognized as a valid service + Generic implementation of a parent Service class. + Every service must subclass this class to be recognized as a valid service. A service instance is created by the CreateScriptService method - It can have a mirror in the Basic world or be totally defined in Python + It can have a mirror in the Basic world or be totally defined in Python. Every subclass must initialize 3 class properties: servicename (e.g. 'ScriptForge.FileSystem', 'ScriptForge.Basic') @@ -659,7 +668,6 @@ class SFServices(object): # SFScriptForge CLASS (alias of ScriptForge Basic library) ### # ##################################################################################################################### class SFScriptForge: - pass # ######################################################################### # SF_Array CLASS @@ -1227,12 +1235,12 @@ class SFScriptForge: def MoveFile(self, source, destination): return self.ExecMethod(self.vbMethod, 'MoveFile', source, destination) - def Normalize(self, filename): - return self.ExecMethod(self.vbMethod, 'Normalize', filename) - def MoveFolder(self, source, destination): return self.ExecMethod(self.vbMethod, 'MoveFolder', source, destination) + def Normalize(self, filename): + return self.ExecMethod(self.vbMethod, 'Normalize', filename) + def OpenTextFile(self, filename, iomode = 1, create = False, encoding = 'UTF-8'): return self.ExecMethod(self.vbMethod, 'OpenTextFile', filename, iomode, create, encoding) @@ -1529,12 +1537,12 @@ class SFScriptForge: def SetPDFExportOptions(self, pdfoptions): return self.ExecMethod(self.vbMethod + self.flgDictArg, 'SetPDFExportOptions', pdfoptions) - def UnoObjectType(self, unoobject): - return self.ExecMethod(self.vbMethod, 'UnoObjectType', unoobject) - def UnoMethods(self, unoobject): return self.ExecMethod(self.vbMethod + self.flgArrayRet, 'UnoMethods', unoobject) + def UnoObjectType(self, unoobject): + return self.ExecMethod(self.vbMethod, 'UnoObjectType', unoobject) + def UnoProperties(self, unoobject): return self.ExecMethod(self.vbMethod + self.flgArrayRet, 'UnoProperties', unoobject) @@ -2391,11 +2399,11 @@ class SFDocuments: def OpenFormDocument(self, formdocument, designmode = False): return self.ExecMethod(self.vbMethod, 'OpenFormDocument', formdocument, designmode) - def OpenQuery(self, queryname): - return self.ExecMethod(self.vbMethod, 'OpenQuery', queryname) + def OpenQuery(self, queryname, designmode = False): + return self.ExecMethod(self.vbMethod, 'OpenQuery', queryname, designmode) - def OpenTable(self, tablename): - return self.ExecMethod(self.vbMethod, 'OpenTable', tablename) + def OpenTable(self, tablename, designmode = False): + return self.ExecMethod(self.vbMethod, 'OpenTable', tablename, designmode) def PrintOut(self, formdocument, pages = '', copies = 1): return self.ExecMethod(self.vbMethod, 'PrintOut', formdocument, pages, copies) @@ -2666,12 +2674,12 @@ class SFDocuments: XChartObj = False, XDiagram = False, XShape = False, XTableChart = False, XTitle = True, YTitle = True) - def Resize(self, xpos = -1, ypos = -1, width = -1, height = -1): - return self.ExecMethod(self.vbMethod, 'Resize', xpos, ypos, width, height) - def ExportToFile(self, filename, imagetype = 'png', overwrite = False): return self.ExecMethod(self.vbMethod, 'ExportToFile', filename, imagetype, overwrite) + def Resize(self, xpos = -1, ypos = -1, width = -1, height = -1): + return self.ExecMethod(self.vbMethod, 'Resize', xpos, ypos, width, height) + # ######################################################################### # SF_Form CLASS # ######################################################################### @@ -3032,6 +3040,62 @@ def CreateScriptService(service, *args, **kwargs): createScriptService, createscriptservice = CreateScriptService, CreateScriptService + +# ############################################################################### +# FOR TYPING HINTS, NEXT VARIABLE TYPES MAY BE IMPORTED IN USER SCRIPTS +# EXAMPLE: +# from scriptforge import CALC, RANGE +# def userfct(c: CALC, r: RANGE) -> RANGE: +# r1: RANGE = "A1:K10" +# ############################################################################### +# List the available service types +# SFScriptForge +ARRAY = SFScriptForge.SF_Array +BASIC = SFScriptForge.SF_Basic +DICTIONARY = SFScriptForge.SF_Dictionary +EXCEPTION = SFScriptForge.SF_Exception +FILESYSTEM = SFScriptForge.SF_FileSystem +L10N = SFScriptForge.SF_L10N +PLATFORM = SFScriptForge.SF_Platform +REGION = SFScriptForge.SF_Region +SESSION = SFScriptForge.SF_Session +STRING = SFScriptForge.SF_String +TEXTSTREAM = SFScriptForge.SF_TextStream +TIMER = SFScriptForge.SF_Timer +UI = SFScriptForge.SF_UI +# SFDatabases +DATABASE = SFDatabases.SF_Database +DATASET = SFDatabases.SF_Dataset +DATASHEET = SFDatabases.SF_Datasheet +# SFDialogs +DIALOG = SFDialogs.SF_Dialog +DIALOGCONTROL = SFDialogs.SF_DialogControl +# SFDocuments +DOCUMENT = SFDocuments.SF_Document +BASE = SFDocuments.SF_Base +CALC = SFDocuments.SF_Calc +CALCREFERENCE = SFDocuments.SF_CalcReference +CHART = SFDocuments.SF_Chart +FORM = SFDocuments.SF_Form +FORMCONTROL = SFDocuments.SF_FormControl +FORMDOCUMENT = SFDocuments.SF_FormDocument +WRITER = SFDocuments.SF_Writer +# SFWidgets +MENU = SFWidgets.SF_Menu +POPUPMENU = SFWidgets.SF_PopupMenu +TOOLBAR = SFWidgets.SF_Toolbar +TOOLBARBUTTON = SFWidgets.SF_ToolbarButton +# UNO +UNO = TypeVar('UNO') +# Other +FILE = TypeVar('FILE', str, str) +SHEETNAME = TypeVar('SHEETNAME', str, str) +RANGE = TypeVar('RANGE', str, str) +SCRIPT_URI = TypeVar('SCRIPT_URI', str, str) +SQL_SELECT = TypeVar('SQL_SELECT', str, str) +SQL_ACTION = TypeVar('SQL_ACTION', str, str) + + # ###################################################################### # Lists the scripts, that shall be visible inside the Basic/Python IDE # ###################################################################### diff --git a/wizards/source/scriptforge/python/scriptforge.pyi b/wizards/source/scriptforge/python/scriptforge.pyi new file mode 100644 index 000000000000..dc2569279786 --- /dev/null +++ b/wizards/source/scriptforge/python/scriptforge.pyi @@ -0,0 +1,7232 @@ +# -*- coding: utf-8 -*- + +# Copyright 2020-2024 Jean-Pierre LEDURE, Rafael LIMA, @AmourSpirit, Alain ROMEDENNE + +# ===================================================================================================================== +# === The ScriptForge library and its associated libraries are part of the LibreOffice project. === +# === Full documentation is available on https://help.libreoffice.org/ === +# ===================================================================================================================== + +# ScriptForge is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +# ScriptForge is free software; you can redistribute it and/or modify it under the terms of either (at your option): + +# 1) The Mozilla Public License, v. 2.0. If a copy of the MPL was not +# distributed with this file, you can obtain one at http://mozilla.org/MPL/2.0/ . + +# 2) The GNU Lesser General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. If a copy of the LGPL was not +# distributed with this file, see http://www.gnu.org/licenses/ . + +""" + ScriptForge libraries are an extensible and robust collection of macro scripting resources for LibreOffice + to be invoked from user Basic or Python macros. Users familiar with other BASIC macro variants often face hard + times to dig into the extensive LibreOffice Application Programming Interface even for the simplest operations. + By collecting most-demanded document operations in a set of easy to use, easy to read routines, users can now + program document macros with much less hassle and get quicker results. + + The use of the ScriptForge interfaces in user scripts hides the complexity of the usual UNO interfaces. + However, it does not replace them. At the opposite their coexistence is ensured. + Indeed, ScriptForge provides a number of shortcuts to key UNO objects. + + The scriptforge.py module + - describes the interfaces (classes and attributes) to be used in Python user scripts + to run the services implemented in the standard modules shipped with LibreOffice + - implements a protocol between those interfaces and, when appropriate, the corresponding ScriptForge + Basic libraries implementing the requested services. + + The scriptforge.pyi module + - provides the static type checking of all the visible interfaces of the ScriptForge API. + - when the user uses an IDE like PyCharm or VSCode, (s)he might benefit from the typing + hints provided by them thanks to the actual scriptforge.pyi module. + + Specific documentation about the use of ScriptForge from Python scripts: + https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/sf_intro.html?DbPAR=BASIC + """ +# IMPORTS +from __future__ import annotations +import datetime +import time +from typing import Any, Dict, List, Literal, NewType, Optional, overload, Sequence, Tuple, TypeVar, Union + +# List the available service types +# SFScriptForge +ARRAY = SFScriptForge.SF_Array +BASIC = SFScriptForge.SF_Basic +DICTIONARY = SFScriptForge.SF_Dictionary +EXCEPTION = SFScriptForge.SF_Exception +FILESYSTEM = SFScriptForge.SF_FileSystem +L10N = SFScriptForge.SF_L10N +PLATFORM = SFScriptForge.SF_Platform +REGION = SFScriptForge.SF_Region +SESSION = SFScriptForge.SF_Session +STRING = SFScriptForge.SF_String +TEXTSTREAM = SFScriptForge.SF_TextStream +TIMER = SFScriptForge.SF_Timer +UI = SFScriptForge.SF_UI +# SFDatabases +DATABASE = SFDatabases.SF_Database +DATASET = SFDatabases.SF_Dataset +DATASHEET = SFDatabases.SF_Datasheet +# SFDialogs +DIALOG = SFDialogs.SF_Dialog +DIALOGCONTROL = SFDialogs.SF_DialogControl +# SFDocuments +DOCUMENT = SFDocuments.SF_Document +BASE = SFDocuments.SF_Base +CALC = SFDocuments.SF_Calc +CALCREFERENCE = SFDocuments.SF_CalcReference +CHART = SFDocuments.SF_Chart +FORM = SFDocuments.SF_Form +FORMCONTROL = SFDocuments.SF_FormControl +FORMDOCUMENT = SFDocuments.SF_FormDocument +WRITER = SFDocuments.SF_Writer +# SFWidgets +MENU = SFWidgets.SF_Menu +POPUPMENU = SFWidgets.SF_PopupMenu +TOOLBAR = SFWidgets.SF_Toolbar +TOOLBARBUTTON = SFWidgets.SF_ToolbarButton +# Aggregate +SERVICE = Union[ARRAY, BASIC, DICTIONARY, EXCEPTION, FILESYSTEM, L10N, PLATFORM, REGION, SESSION, STRING, + TEXTSTREAM, TIMER, UI, + DATABASE, DATASET, DATASHEET, + DIALOG, DIALOGCONTROL, + DOCUMENT, BASE, CALC, CALCREFERENCE, CHART, FORM, FORMCONTROL, FORMDOCUMENT, WRITER, + MENU, POPUPMENU, TOOLBAR, TOOLBARBUTTON] +# UNO +UNO = TypeVar('UNO') +# Other +FILE = TypeVar('FILE', str, str) +""" File or folder name expressed in accordance with the ``FileSystem.FileNaming`` notation. """ + +SHEETNAME = TypeVar('SHEETNAME', str, str) +""" A sheet in a Calc document, as a string. It must not contain next characters: "[]*?:\\\/". The apostrophe (') +is forbidden in the first and last positions. The "~" (tilde) character designates the active sheet. """ +RANGE = TypeVar('RANGE', str, str) +""" A set of contiguous cells located in a sheet. + +The sheet name is optional. If no sheet name is provided, then the active sheet is used. +The use of single quotes to enclose the sheet name is required if the name contains blank spaces " " or periods ".". +Otherwise surrounding single quotes and $ signs are allowed but ignored. + +The shortcut "~" (tilde) represents the current selection or the first selected range if multiple ranges are selected. +The shortcut "*" represents all used cells. + +Examples + - ``$'SheetX'.D2``, ``$D$2`` - Single cells + - ``$'SheetX'.D2:F6``, ``D2:D10`` - Single ranges with multiple cells + - ``$'SheetX'.*`` - All used cells in the given sheet + - ``$'SheetX'.A:A``, ``3:5`` - All cells in contiguous columns or rows up to the last used cell + - ``myRange`` - A range named "myRange" at spreadsheet level + - ``~.someRange``, ``SheetX.someRange`` - Range names at sheet level + - ``~.~`` or ``~`` - The current selection in the active sheet +""" +SCRIPT_URI = TypeVar('SCRIPT_URI', str, str) +""" String reference to a Basic or Python macro as described in +``https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework#Scripting_Framework_URI_Specification`` +""" +SQL_SELECT = TypeVar('SQL_SELECT', str, str) +""" A SQL command containing a SELECT statement, a tablename or a queryname. +In a SELECT statement, table-, qyery- and field names may be surrounded by square brackets. """ +SQL_ACTION = TypeVar('SQL_ACTION', str, str) +""" A SQL command containing an action statement (CREATE TABLE, INSERT, DELETE, ...). +Table- and field names may be surrounded by square brackets. """ +SCALAR = Union[int, float, str, datetime.datetime] +VECTOR = Sequence[SCALAR] +MATRIX = Sequence[VECTOR] + +# Define the used UNO types +try: + # Next code can succeed only when types-unopy is installed + from com.sun.star.awt import XControl + from com.sun.star.awt import XControlModel + from com.sun.star.awt import XTabControllerModel + from com.sun.star.awt import XWindow + from com.sun.star.awt.tree import XMutableTreeDataModel + from com.sun.star.awt.tree import XMutableTreeNode + from com.sun.star.beans import PropertyValue + from com.sun.star.chart import XDiagram + from com.sun.star.document import XEmbeddedScripts + from com.sun.star.drawing import XShape + from com.sun.star.form import ListSourceType + from com.sun.star.form import XForm + from com.sun.star.frame import XDesktop + from com.sun.star.lang import XComponent + from com.sun.star.script import XLibraryContainer + from com.sun.star.script.provider import XScriptProvider + from com.sun.star.sdb import XOfficeDatabaseDocument + from com.sun.star.sdbc import XConnection as UNOXConnection + from com.sun.star.sdbc import XDatabaseMetaData + from com.sun.star.sheet import XSheetCellCursor + from com.sun.star.sheet import XSpreadsheet + from com.sun.star.table import XCellRange + from com.sun.star.table import XTableChart + from com.sun.star.uno import XComponentContext + from com.sun.star.uno import XInterface + from com.sun.star.util import Date as UNODate + from com.sun.star.util import DateTime as UNODateTime + from com.sun.star.util import Time as UNOTime +except ImportError: + # types-unopy is not installed + XControl = NewType('XControl', UNO) + XControlModel = NewType('XControlModel', UNO) + XTabControllerModel = NewType('XTabControllerModel', UNO) + XWindow = NewType('XWindow', UNO) + XMutableTreeDataModel = NewType('XMutableTreeDataModel', UNO) + XMutableTreeNode = NewType('XMutableTreeNode', UNO) + PropertyValue = NewType('PropertyValue', UNO) + XDiagram = NewType('XDiagram', UNO) + XEmbeddedScripts = NewType('XEmbeddedScripts', UNO) + XShape = NewType('XShape', UNO) + ListSourceType = NewType('ListSourceType', UNO) + XForm = NewType('XForm', UNO) + XDesktop = NewType('XDesktop', UNO) + XComponent = NewType('XComponent', UNO) + XLibraryContainer = NewType('XLibraryContainer', UNO) + XScriptProvider = NewType('XScriptProvider', UNO) + XOfficeDatabaseDocument = NewType('XOfficeDatabaseDocument', UNO) + UNOXConnection = NewType('UNOXConnection', UNO) + XDatabaseMetaData = NewType('XDatabaseMetaData', UNO) + XSheetCellCursor = NewType('XSheetCellCursor', UNO) + XSpreadsheet = NewType('XSpreadsheet', UNO) + XCellRange = NewType('XCellRange', UNO) + XTableChart = NewType('XTableChart', UNO) + XComponentContext = NewType('XComponentContext', UNO) + XInterface = NewType('XInterface', UNO) + UNODate = NewType('UNODate', UNO) + UNODateTime = NewType('UNODateTime', UNO) + UNOTime = NewType('UNOTime', UNO) + +# Docstring rules to display readable text both in PyCharm and VS Code +# Indentation and punctuation are required like in the example below. +# def ImportFromCSVFile(self, filename: FILE, delimiter: str = ',', +# dateformat: Literal['YYYY-MM-DD', 'DD-MM-YYYY', 'MM-DD-YYYY'] = ...) -> Tuple[str, ...]: +# """ +# Import the data contained in a comma-separated values (CSV) file. The comma may be replaced +# by any character. +# Difference with the Basic version: dates are returned in their iso format, +# not as any of the datetime objects. +# Args <<<<< No colon (:) +# ``filename``: The name of the text file containing the data. +# The name must be expressed according to the current FileNaming property of the FileSystem +# service. +# <<<<< When multiple arguments, a linefeed is required here +# ``dateformat``: A special mechanism handles dates when ``dateformat`` is not the empty string. +# The dash (-) may be replaced by a dot (.), a slash (/) or a space. Other date formats +# will be ignored. +# Returns <<<<< No colon (:) +# A ``list`` of ``lists``. +# """ +# ... + + +# ##################################################################################################################### +# ScriptForge CLASS ### +# ##################################################################################################################### + +class ScriptForge(object, metaclass = ...): + """ + The ScriptForge class encapsulates the core of the ScriptForge run-time + - Bridge with the LibreOffice process + - Implementation of the interlanguage protocol with the Basic libraries + - Identification of the available services interfaces + - Dispatching of services + - Coexistence with UNO + + The class may be instantiated several times. Only the first instance will be retained ("Singleton"). + """ + + def __init__(self, hostname: str = ..., port: int = ...): + """ + The ScriptForge class encapsulates the core of the ScriptForge run-time + - Bridge with the LibreOffice process + - Implementation of the interlanguage protocol with the Basic libraries + - Identification of the available services interfaces + - Dispatching of services + - Coexistence with UNO + + The class may be instantiated several times. Only the first instance will be retained ("Singleton"). + + Both arguments are mandatory when Python and LibreOffice run in separate processes. + Otherwise, do not call this routine or leave both arguments out. + To execute at most once by LibreOffice session. + Args + ``hostname``: probably 'localhost' + + ``port``: port number + """ + ... + + +# ##################################################################################################################### +# SFServices CLASS (ScriptForge services superclass) ### +# ##################################################################################################################### + +class SFServices(object): + """ + Generic implementation of a parent Service class. + + Every service must subclass this class to be recognized as a valid service. + A service instance is created by the ``CreateScriptService`` method. + + It can have a mirror in the ``Basic`` world or be totally defined in ``Python``. + """ + + def Dispose(self) -> None: + """ Free up the object's resources after usage. """ + ... + + def GetProperty(self, propertyname: str, arg: Any = ...) -> Any: + """ Get the given property from the Basic world """ + ... + + def Properties(self) -> Tuple[str, ...]: + """ Properties list. """ + ... + + +# ##################################################################################################################### +# SFScriptForge CLASS (alias of ScriptForge Basic library) ### +# ##################################################################################################################### +class SFScriptForge: + """ SF_ScriptForge all-purpose services. """ + + # ######################################################################### + # SF_Array CLASS + # ######################################################################### + class SF_Array(SFServices, metaclass = ...): + + def ImportFromCSVFile(self, + filename: FILE, + delimiter: str = ',', + dateformat: Literal['YYYY-MM-DD', 'DD-MM-YYYY', 'MM-DD-YYYY', + 'YYYY/MM/DD', 'DD/MM/YYYY', 'MM/DD/YYYY', + 'YYYY.MM.DD', 'DD.MM.YYYY', 'MM.DD.YYYY', + 'YYYY MM DD', 'DD MM YYYY', 'MM DD YYYY'] = ... + ) -> MATRIX: + """ + Import the data contained in a comma-separated values (CSV) file. The comma may be replaced + by any character. + Difference with the Basic version: dates are returned in their iso format, + not as any of the datetime objects. + Args + ``filename``: The name of the text file containing the data. + The name must be expressed according to the current FileNaming property of the FileSystem + service. + + ``dateformat``: A special mechanism handles dates when ``dateformat`` is not the empty string. + The dash (-) may be replaced by a dot (.), a slash (/) or a space. Other date formats + will be ignored. + Returns + A ``list`` of ``lists``. + """ + ... + + # ######################################################################### + # SF_Basic CLASS + # ######################################################################### + class SF_Basic(SFServices, metaclass = ...): + """ + This service proposes a collection of Basic methods to be executed in a Python context + simulating the exact syntax and behavior of the identical Basic builtin method.\n + Typical example: + ``basic = CreateScriptService('basic')`` + ``basic.MsgBox('This has to be displayed in a message box')`` + """ + + MB_ABORTRETRYIGNORE: Literal[2] + MB_DEFBUTTON1: Literal[128] + MB_DEFBUTTON2: Literal[258] + MB_DEFBUTTON3: Literal[215] + MB_ICONEXCLAMATION: Literal[48] + MB_ICONINFORMATION: Literal[64] + MB_ICONQUESTION: Literal[32] + MB_ICONSTOP: Literal[16] + MB_OK: Literal[0] + MB_OKCANCEL: Literal[1] + MB_RETRYCANCEL: Literal[5] + MB_YESNO: Literal[4] + MB_YESNOCANCEL: Literal[3] + IDABORT: Literal[3] + IDCANCEL: Literal[2] + IDIGNORE: Literal[5] + IDNO: Literal[7] + IDOK: Literal[1] + IDRETRY: Literal[4] + IDYES: Literal[6] + + @classmethod + def CDate(cls, datevalue: Union[int, float, str]) -> Optional[datetime.datetime]: + """ + Converts a numeric expression or a string to a ``datetime.datetime`` Python native object. + Args + ``datevalue``: A numeric expression or a ``string`` representing a date. + Returns + The equivalent ``datetime.datetime``. + """ + ... + + @staticmethod + def CDateFromUnoDateTime(unodate: Union[UNODateTime, UNODate, UNOTime]) -> datetime.datetime: + """ + Converts a ``UNO date/time`` representation to a ``datetime.datetime`` Python native object. + Args + ``unodate``: A ``UNO date`` object, ``com.sun.star.util.DateTime``, ``.Date`` or ``.Time``. + Returns + The equivalent ``datetime.datetime``. + """ + ... + + @staticmethod + def CDateToUnoDateTime(date: Union[float, time.struct_time, datetime.datetime, datetime.date, datetime.time] + ) -> UNODateTime: + """ + Converts a date representation into the ``com.sun.star.util.DateTime`` date format. + Args + ``date``: A ``datetime`` like object. + When ``date`` is a ``float`` it is considered a ``time.time`` value. + Returns + A ``com.sun.star.util.DateTime`` UNO object. + """ + ... + + @classmethod + def ConvertFromUrl(cls, url: str) -> str: + """ + Convert from url. + Args + ``url``: A string representing a file in URL format. + Returns + The same file name in native operating system notation._ + """ + ... + + @classmethod + def ConvertToUrl(cls, systempath: str) -> str: + """ + Convert to url. + Args + ``systempath``: A string representing a file in native operating system notation. + Returns + The same file name in URL format. + """ + ... + + @classmethod + def CreateUnoService(cls, servicename: str) -> UNO: + """ + Instantiates a UNO service + Args + ``servicename``: A string representing the service to create. + Returns + A UNO object + """ + ... + + @classmethod + def CreateUnoStruct(cls, unostructure: str) -> UNO: + """ + Returns an instance of a UNO structure of the specified type. + Args + ``unostructure``: A UNO Struct typename such as ``com.sun.star.awt.Size``. + Returns + A UNO Object + """ + ... + + @classmethod + def DateAdd(cls, + interval: Literal['yyyy', 'q', 'm','y', 'w', 'ww', 'd', 'h', 'n', 's'], + number: int, + date: Union[float, time.struct_time, datetime.datetime, datetime.date, datetime.time] + ) -> datetime.datetime: + """ + Adds a date or time interval to a given date/time a number of times and returns the resulting date. + Args + ``interval``: A string expression specifying the date or time interval. + + ``number``: A numerical expression specifying how often the interval value will be added when + positive or subtracted when negative. + + ``date``: A given ``datetime.datetime`` value, the interval value will be added ``number`` + times to this ``date`` value. + Returns + A ``datetime.datetime`` value. + """ + ... + + @classmethod + def DateDiff(cls, + interval: Literal['yyyy', 'q', 'm','y', 'w', 'ww', 'd', 'h', 'n', 's'], + date1: Union[float, time.struct_time, datetime.datetime, datetime.date, datetime.time], + date2: Union[float, time.struct_time, datetime.datetime, datetime.date, datetime.time], + firstdayofweek: Literal[0, 1, 2, 3, 4, 5, 6, 7] = ..., + firstweekofyear: Literal[0, 1, 2, 3] = ..., + ) -> int: + """ + Gets the number of date or time intervals between two given date/time values. + Args + ``interval``: A string expression specifying the date interval. + + ``date1``: The first ``datetime.datetime`` values to be compared. + + ``firstdayofweek``: An optional parameter that specifies the starting day of a week. + + ``firstweekofyear``: An optional parameter that specifies the starting week of a year. + Returns + A number. + """ + ... + + @classmethod + def DatePart(cls, + interval: Literal['yyyy', 'q', 'm','y', 'w', 'ww', 'd', 'h', 'n', 's'], + date: Union[float, time.struct_time, datetime.datetime, datetime.date, datetime.time], + firstdayofweek: Literal[0, 1, 2, 3, 4, 5, 6, 7] = ..., + firstweekofyear: Literal[0, 1, 2, 3] = ..., + ) -> int: + """ + Gets a specified part of a date. + Args + ``interval``: A string expression specifying the date interval. + + ``date``: The date from which to extract a part. + + ``firstdayofweek``: the starting day of a week. Defaults to 1. + + ``firstweekofyear``: the starting week of a year. Defaults to 1. + Returns + The specified part of the date. + """ + ... + + @classmethod + def DateValue(cls, string: str) -> datetime.datetime: + """ + Computes a date value from a date string. + Args + ``string``: A string expression that contains the date that you want to calculate. + The string passed to ``DateValue`` must be expressed in one of the date formats defined + by your locale setting or using the ISO date format "yyyy-mm-dd" (year, month and day + separated by hyphens). + Returns + The converted date. + """ + ... + + @classmethod + def Format(cls, expression: Union[datetime.datetime, float, int], format: str = ...) -> str: + """ + Converts a number to a string, and then formats it according to the format that you specify. + Args + ``expression``: Numeric expression that you want to convert to a formatted string. + + ``format``: the format to apply. Defaults to "". + Returns + The formatted value. + """ + ... + + @classmethod + def GetDefaultContext(cls) -> XComponentContext: + """ + Gets the default context of the process service factory, if existent, else returns a None reference. + """ + ... + + @classmethod + def GetGuiType(cls) -> int: + """ + Gets a numerical value that specifies the graphical user interface. + Returns + The GetGuiType value, 1 for Windows, 4 for UNIX + """ + ... + + @classmethod + def GetPathSeparator(cls) -> str: + """ + Gets the operating system-dependent directory separator used to specify file paths. + Returns + The os path separator + """ + ... + + @classmethod + def GetSystemTicks(cls) -> int: + """ + Gets the number of system ticks provided by the operating system. + You can use this function to optimize certain processes. + Use this method to estimate time in milliseconds: + Returns + The actual number of system ticks. + """ + ... + + class GlobalScope(metaclass = ...): + """ + Use cases: + - ``GlobalScope.BasicLibraries`` + - ``GlobalScope.DialogLibraries`` + """ + + @classmethod + def BasicLibraries(cls) -> XLibraryContainer: + """ + ``GlobalScope.BasicLibraries`` gets the UNO object containing all shared Basic libraries + and modules. This method is the Python equivalent to ``GlobalScope.BasicLibraries`` + in Basic scripts. + Returns + A ``XLibraryContainer`` UNO object. + """ + ... + + @classmethod + def DialogLibraries(cls) -> XLibraryContainer: + """ + ``GlobalScope.DialogLibraries`` gets the UNO object containing all shared dialog libraries. + Returns + A ``DialogLibraryContainer`` UNO object. + """ + ... + + @classmethod + def InputBox(cls, + prompt: str, + title: str = ..., + default: str = ..., + xpostwips: int = ..., + ypostwips: int = ..., + ) -> str: + """ + Displays an input box. + Args + ``prompt``: String expression displayed as the message in the dialog box. + + ``title``: String expression displayed in the title bar of the dialog box. + + ``default``: String expression displayed in the text box as default ifno other input is given. + + ``xpostwips``: Integer expression that specifies the horizontal position of the dialog. + The position is an absolute coordinate and does not refer to the window of LibreOffice. + + ``ypostwips``: Integer expression that specifies the vertical position of the dialog. + The position is an absolute coordinate and does not refer to the window of LibreOffice. + + If ``xpostwips`` and ``ypostwips`` are omitted, the dialog is centered on the screen. + Returns + The input string. + """ + ... + + @classmethod + def MsgBox(cls, prompt: str, buttons: int = ..., title: str = ...) -> int: + """ + Displays a dialogue box containing a message and returns an optional value. + + MB_xx constants help specify the dialog type, the number and type of buttons to display, + plus the icon type. By adding their respective values they form bit patterns, that define the + MsgBox dialog appearance. + Args + ``prompt``: String expression displayed as a message in the dialog box. + + ``buttons``: Integer expression that specifies the dialog type, as well as the number + and type of buttons to display, and the icon type. ``buttons`` represents a combination of bit + patterns, that is, a combination of elements can be defined by adding their respective values. + Defaults to 0. + + ``title``: String expression displayed in the title bar of the dialog. Defaults to "". + Returns + The pressed button. + """ + ... + + @classmethod + def Now(cls) -> datetime.datetime: + """ + Gets the current system date and time as a ``datetime.datetime`` Python native object. + """ + ... + + @classmethod + def RGB(cls, red: int, green: int, blue: int) -> int: + """ + Gets an integer color value consisting of red, green, and blue components. + Args + ``red``: An integer expression that represents the red component (0-255) of the composite color. + + ``green``: An integer expression that represents the green component (0-255) of the + composite color. + + ``blue``: An integer expression that represents the blue component (0-255) of the composite + color. + Returns + An integer color value consisting of red, green, and blue components. + """ + ... + + + @classmethod + def Xray(cls, unoobject: UNO) -> None: + """ + Inspect UNO objects or variables. + Args + ``unoobject``: A variable or UNO object. + """ + ... + + StarDesktop: XDesktop + """ Gets the desktop as a UNO object. """ + ThisComponent: Optional[XComponent] + """ + If the current component refers to a LibreOffice document, this method + returns the UNO object representing the document. + When the current component is the Basic IDE, the ThisComponent object returns in Basic the + component owning the currently run user script. This behaviour cannot be reproduced in Python. + Returns + The current component or None when not a document. + """ + ThisDatabaseDocument: Optional[XOfficeDatabaseDocument] + """ + If the script is being executed from a Base document or any of its subcomponents + this method returns the main component of the Base instance. + Returns + The current Base (main) component or None when not a Base document or one of its subcomponents. + """ + + # ######################################################################### + # SF_Dictionary CLASS + # ######################################################################### + class SF_Dictionary(SFServices, dict): + """ + The service adds to a Python dict instance the interfaces for conversion to and from + a list of UNO PropertyValues + Usage + ``dico = dict(A = 1, B = 2, C = 3)`` + + ``myDict = CreateScriptService('Dictionary', dico) # Initialize myDict with the content of dico`` + + ``myDict['D'] = 4`` + + ``print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}`` + + ``propval = myDict.ConvertToPropertyValues()`` + or + ``dico = dict(A = 1, B = 2, C = 3)`` + + ``myDict = CreateScriptService('Dictionary') # Initialize myDict as an empty dict object`` + + ``myDict.update(dico) # Load the values of dico into myDict`` + + ``myDict['D'] = 4`` + + ``print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}`` + + ``propval = myDict.ConvertToPropertyValues()`` + """ + + def ConvertToPropertyValues(self) -> Tuple[PropertyValue]: + """ + Store the content of the dictionary in an array of PropertyValues. + Each entry in the list is a ``com.sun.star.beans.PropertyValue``. + The key is stored in Name, the value is stored in ``Value``. + + If one of the items has a type ``datetime``, it is converted to a ``com.sun.star.util.DateTime`` + structure. If one of the items is an empty list, it is converted to ``None``. + Returns + A list of property values. The resulting list is empty when the dictionary is empty. + """ + ... + + def ImportFromPropertyValues(self, propertyvalues: Sequence[PropertyValue], overwrite: bool = ...) -> bool: + """ + Inserts the contents of an array of ``PropertyValue`` objects into the current dictionary. + ``PropertyValue`` Names are used as keys in the dictionary, whereas Values contain + the corresponding values. Date-type values are converted to ``datetime.datetime`` instances. + Args + ``propertyvalues``: tuple containing ``com.sun.star.beans.PropertyValue`` objects. + + ``overwrite``: When True, entries with same name may exist in the dictionary + and their values are overwritten. When ``False`` (default), repeated keys are not overwritten. + Defaults to ``False``. + Returns + True when successful. + """ + ... + + # ######################################################################### + # SF_Exception CLASS + # ######################################################################### + class SF_Exception(SFServices, metaclass = ...): + """ + The Exception service is a collection of methods for code debugging. + + The ``Exception`` service console stores events, variable values and information about errors. + + Use the console when the Python shell is not available, for example in ``Calc`` user defined functions (UDF) + or during events processing. + + Use the ``DebugPrint()`` and ``DebuDisplay()`` methods to log any relevant information, events and data + of any type to the console. + + Console entries can be dumped to a text file or visualized in a dialogue. + """ + + def Console(self, modal: bool = ...): + """ + Displays the console messages in a modal or non-modal dialog. In both modes, all the past messages + issued by a ``DebugPrint()`` method or resulting from an exception are displayed. In non-modal mode, + subsequent entries are added automatically. + + If the console is already open, when non-modal, it is brought to the front. + + A modal console can only be closed by the user. A non-modal console can either be closed by the user + or upon script termination. + Args + ``modal``: determine if the console window is modal (``True``) or non-modal (``False``). + Default value is ``True``. + """ + ... + + def ConsoleClear(self, keep: int = ...): + """ + Clears the console keeping an optional number of recent messages. If the console is activated in non-modal mode, + it is refreshed. + Args + ``keep``: the number of recent messages to be kept. Default value is 0. + """ + ... + + def ConsoleToFile(self, filename: FILE) -> bool: + """ + Exports the contents of the console to a text file. If the file already exists and the console + is not empty, it will be overwritten without warning. Returns True if successful. + Args + ``filename``: the name of the text file the console should be dumped into. + The name is expressed according to the current ``FileNaming`` property of the ``SF_FileSystem`` + service. + Returns + ``True`` when successful. + """ + ... + + def DebugDisplay(self, *args)-> int: + """ + Concatenates all the arguments into a single human-readable string and displays it in a MsgBox + with an Information icon and an OK button. The displayed string is also added to the Console. + Args + ``*args``: any number of arguments of any type. + Returns + The result of the execution of the ``MsgBox()`` method. + """ + ... + + def DebugPrint(self, *args): + """ + Assembles all the given arguments into a single human-readable string and adds it as a new entry + in the console. + Args + ``*args``: any number of arguments of any type. + """ + ... + + @classmethod + def PythonShell(cls, variables: dict = ...) -> None: + """ + Opens an APSO Python shell as a non-modal window. + The Python script keeps running after the shell is opened. + The output from ``print`` statements inside the script are shown in the shell. + Args + ``variables``: a Python dictionary with variable names and values that will be + passed on to the APSO Python shell. By default, all local variables are passed using + Python's builtin ``locals()`` function. + + Typical use: ``{**globals(), **locals()}`` + """ + ... + + # ######################################################################### + # SF_FileSystem CLASS + # ######################################################################### + class SF_FileSystem(SFServices, metaclass = ...): + """ + The "FileSystem" service includes common file and folder handling routines. + """ + + FileNaming: str + """ + Sets or returns the current files and folders notation, either ``'ANY', 'URL'`` or ``'SYS'``: + + ``ANY``: (default) the methods of the ``FileSystem`` service accept both URL and current operating + system's notation for input arguments but always return URL strings. + + ``URL``: the methods of the ``FileSystem`` service expect URL notation for input arguments and + return URL strings. + + ``SYS``: the methods of the ``FileSystem`` service expect current operating system's notation + for both input arguments and return strings. + + Once set, the ``FileNaming`` property remains unchanged either until the end of the ``LibreOffice`` + session or until it is set again. + """ + ConfigFolder: FILE + """ Returns the configuration folder of ``LibreOffice``. """ + ExtensionsFolder: FILE + """ Returns the folder where extensions are installed. """ + HomeFolder: FILE + """ Returns the user home folder. """ + InstallFolder: FILE + """ Returns the installation folder of ``LibreOffice``. """ + TemplatesFolder: FILE + """ Returns the folder containing the system templates files. """ + TemporaryFolder: FILE + """ Returns the temporary files folder defined in the ``LibreOffice`` path settings. """ + UserTemplatesFolder: FILE + """ Returns the folder containing the user-defined template files. """ + + ForReading: Literal[1] + ForWriting: Literal[2] + ForAppending: Literal[8] + + def BuildPath(self, foldername: FILE, name: str) -> str: + """ + Joins a folder path and the name of a file and returns the full file name with a + valid path separator. The path separator is added only if necessary. + + Args + ``foldername``: the path with which name will be combined. + The specified path does not need to be an existing folder. + + ``name``: the name of the file to be appended to foldername. This parameter uses + the notation of the current operating system. + + Returns + The path concatenated with the file name after insertion of a path separator, if necessary. + """ + ... + + def CompareFiles(self, filename1: FILE, filename2: FILE, comparecontents: bool = ...) -> bool: + """ + Compare 2 files and return ``True`` if they seem identical. + Depending on the value of the ``comparecontents`` argument, + the comparison between both files can be either based only on + file attributes (such as the last modified date), or based on the file contents. + Args + ``filename1``: the 1st file to compare. + + ``filename2``: the 2nd file to compare. + + ``comparecontents``: when ``True``, the contents of the files are compared. + Defaults to ``False``. + Returns + ``True`` when the files seem identical + """ + ... + + def CopyFile(self, source: FILE, destination: FILE, overwrite: bool = ...) -> bool: + """ + Copies one or more files from one location to another. + Args + ``source``: ``FileName`` or ``NamePattern`` which can include wildcard characters, + for one or more files to be copied. + + ``destination``: ``FileName`` where the single ``source`` file is to be copied + or ``FolderName`` where the multiple files from ``source`` are to be copied. + + ``overwrite``: if ``True`` (default), files may be overwritten. + ``CopyFile`` will fail if Destination has the read-only attribute set, + regardless of the value of Overwrite. + Returns + ``True`` if at least one file has been copied. ``False`` if an error occurred. + An error also occurs if a source using wildcard characters doesn't match any files. + The method stops on the first error it encounters. + No attempt is made to roll back or undo any changes made before an error occurs. + Notes + - If ``destination`` does not exist, it is created. + - Wildcard characters are not allowed in ``destination``. + """ + ... + + def CopyFolder(self, source: FILE, destination: FILE, overwrite: bool = ...) -> bool: + """ + Copies one or more folders from one location to another. + Args + ``source``: ``FolderName`` or ``NamePattern`` which can include wildcard characters, + for one or more folders to be copied. + + ``destination``: ``FolderName`` where the single ``source`` folder is to be copied + or ``FolderName`` where the multiple folders from ``source`` are to be copied. + If ``FolderName`` does not exist, it is created. + + ``overwrite``: if ``True`` (default), folders and their content may be overwritten. + Defaults to ``True``. ``CopyFile`` will fail if ``destination`` has the read-only + attribute set, regardless of the value of ``overwrite``. + Returns + ``True`` if at least one folder has been copied. ``False`` if an error occurred. + An error also occurs if a ``source`` using wildcard characters doesn't match any folders. + The method stops on the first error it encounters. + No attempt is made to roll back or undo any changes made before an error occurs. + Notes + - If ``destination`` does not exist, it is created. + - Wildcard characters are not allowed in ``destination``. + """ + ... + + def CreateFolder(self, foldername: FILE) -> bool: + """ + Creates the specified ``olderame``. + If the specified folder has a parent folder that does not exist, it is created. + Args + foldername: a string representing the folder to create. It must not exist. + Returns + ``True`` if ``foldername`` is a valid folder name, does not exist and creation was successful. + ``False`` otherwise, including when ``foldername`` is a file. + """ + ... + + def CreateTextFile( + self, filename: FILE, overwrite: bool = ..., encoding: str = ... + ) -> TEXTSTREAM: + """ + Creates a specified file and returns a ``TextStream`` service instance that can be used + to write to the file. + The method returns ``None`` if an error occurred. + Args + ``filename``: the name of the file to be created. + + ``overwrite``: determines if ``filename`` can be overwritten (default = ``True``). + + ``encoding``: the character set to be used. The default encoding is "UTF-8". + """ + ... + + def DeleteFile(self, filename: FILE) -> bool: + """ + Deletes one or more files. + The files to be deleted must not be readonly. + Args + ``filename``: ``FileName`` or ``NamePattern`` which can include wildcard characters, + for one or more files to be deleted. + Returns + ``True`` if at least one file has been deleted. ``False`` if an error occurred. + An error also occurs if ``fileName`` using wildcard characters doesn't match any files. + The method stops on the first error it encounters. + No attempt is made to roll back or undo any changes made before an error occurs. + """ + ... + + def DeleteFolder(self, foldername: FILE) -> bool: + """ + Deletes one or more folders. + The folders to be deleted must not be readonly. + Args + ``foldername``: ``FolderName`` or ``NamePattern`` which can include wildcard characters, + for one or more Folders to be deleted. + Returns + ``True`` if at least one folder has been deleted. ``False`` if an error occurred. + An error will also occur if the ``foldername`` parameter uses wildcard characters and + does not match any folders. + The method stops immediately after it encounters an error. + The method does not roll back nor does it undo changes made before the error occurred. + """ + ... + + def ExtensionFolder(self, extension: str) -> str: + """ + Returns a string containing the folder where the specified extension package is installed. + Args + ``extension``: a string value with the ID of the extension. + If the extension is not installed, an exception is raised. + """ + ... + + def FileExists(self, filename: FILE) -> bool: + """ + Return ``True`` if the given file exists. + Args + ``filename``: a string representing the file to be tested. + Returns + ``True`` if ``filename`` is a valid File name and it exists. + ``False`` otherwise, including when ``filename`` is a folder. + """ + ... + + def Files(self, foldername: FILE, filter: str = ..., includesubfolders: bool = ...) -> Tuple[str, ...]: + """ + Gets a tuple of the ``FileNames`` stored in the given folder. + If the argument ``foldername`` specifies a folder that does not exist, an exception is raised. + The resulting tuple may be filtered with wildcards. + Args + ``foldername``: the folder to explore. + + ``filter``: contains wildcards ("?" and "*") to limit the list to the relevant files + (default = ""). + + ``includesubfolders``: set this argument to ``True`` to include the contents of + subfolders (Default = ``False``). + Returns + A tuple of strings, each entry is the ``FileName`` of an existing file. + """ + ... + + def FolderExists(self, foldername: FILE) -> bool: + """ + Returns ``True`` if the given folder name exists. + Args + ``foldername``: a string representing a folder. + Returns + ``True`` if ``folderName`` is a valid folder name and it exists. + ``False`` otherwise, including when ``foldername`` is a file. + """ + ... + + def GetBaseName(self, filename: FILE) -> str: + """ + Returns the ``BaseName`` (equal to the last component) of a file or folder name, without its extension. + The method does not check for the existence of the specified file or folder. + Args + ``filename``: path and file name + Returns + The ``BaseName`` of the given file name. It may be the empty string. + """ + ... + + def GetExtension(self, filename: FILE) -> str: + """ + Returns the extension part of a ``File-`` or ``FolderName``, without the dot (.). + The method does not check for the existence of the specified file or folder. + Args + ``filename``: path and file name + Returns + The extension without a leading dot. May be empty. + """ + ... + + def GetFileLen(self, filename: FILE) -> int: + """ + Returns the length of a file in bytes. + Args + ``filename``: a string representing an existing file. + Returns + File size if ``filename`` exists. + """ + ... + + def GetFileModified(self, filename: FILE) -> datetime.datetime: + """ + Returns the last modified date for the given file. + Args + ``filename``: a string representing an existing file. + Returns + The modification date and time. + """ + ... + + def GetName(self, filename: FILE) -> str: + """ + Returns the last component of a ``File-`` or ``FolderName``. + The method does not check for the existence of the specified file or folder. + Args + ``filename``: path and file name + Returns + The last component of the full file name in native operating system format. + """ + ... + + def GetParentFolderName(self, filename: FILE) -> FILE: + """ + Returns a string containing the name of the parent folder of the last component in a specified + ``File-`` or ``FolderName``. + The method does not check for the existence of the specified file or folder. + Args + ``filename``: path and file name. + Returns + A folder name including its final path separator. + """ + ... + + def GetTempName(self, extension: str = ...) -> FILE: + """ + Returns a randomly generated temporary file name that is useful for performing + operations that require a temporary file : the method does not create any file. + Args + ``extension``: the extension of the temporary file name (Default = ""). + Returns + A ``FileName`` as a string. + By default, the returned file name does not have an extension (suffix). + Use the extension parameter to specify the extension of the file name to be generated. + The folder part of the returned string is the system's temporary folder. + """ + ... + + def HashFile(self, + filename: FILE, + algorithm: Literal['MD5', 'SHA1', 'SHA224', 'SHA256', 'SHA384', 'SHA512'], + ) -> str: + """ + Gets a hexadecimal string representing a checksum of the given file. + Args + ``filename``: a string representing a file. + + ``algorithm``: the hashing algorithm to use. + Returns + The requested checksum as a string. Hexadecimal digits are lower-cased. + A zero-length string when an error occurred. + Note + The supported hashing algorithms are: + - MD5 + - SHA1 + - SHA224 + - SHA256 + - SHA384 + - SHA512 + """ + ... + + def MoveFile(self, source: FILE, destination: FILE) -> bool: + """ + Moves one or more files from one location to another. + Returns ``True`` if at least one file has been moved or ``False`` if an error occurred. + An error will also occur if the source parameter uses wildcard characters anddoes not match any files. + + The method stops immediately after it encounters an error. The method does not + roll back nor does it undo changes made before the error occurred. + Args + ``source``: ``FileName`` or ``NamePattern`` which can include wildcard characters, + for one or more files to be moved. + + ``destination``: if ``source`` is an existing file name then ``destination`` indicates + the new path and file name of the moved file. If the move operation involves multiple files, + then ``destination`` must be a folder name. If it does not exist, it is created. + If ``source`` and ``destination`` have the same parent folder, the method will rename + the ``source``. + Wildcard characters are not allowed in ``destination``. + Returns + ``True`` if at least one file has been moved. ``False`` if an error occurred. + """ + ... + + def MoveFolder(self, source: FILE, destination: FILE) -> bool: + """ + Moves one or more folders from one location to another. + Returns ``True`` if at least one folder has been moved or ``False`` if an error occurred. + An error will also occur if the source parameter uses wildcard characters and does + not match any folders. + + The method stops immediately after it encounters an error. The method does not roll + back nor does it undo changes made before the error occurred. + Args + ``source``: ``FolderName`` or ``NamePattern`` which can include wildcard characters, + for one or more folders to be moved. + + ``destination``: if the move operation involves a single folder, then ``destination`` + is the name and path of the moved folder. It must not exist. + If multiple folders are being moved, then ``destination`` designates where the folders + in ``source`` will be moved into. If ``destination`` does not exist, it is created. + Wildcard characters are not allowed in ``destination``. + Returns + ``True`` if at least one folder has been moved. ``False`` if an error occurred. + """ + ... + + def Normalize(self, filename: FILE) -> FILE: + """ + Returns a string containing the normalized path name by collapsing redundant separators and up-level + references. For instance, the path names ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` are all + normalized to ``A/B``. + + On Windows, forward slashes ``/`` are converted to backward slashes \\\. + Args + ``filename``: a string representing a valid path name. + The file or directory represented by this argument may not exist. + Returns + The normalized file name. + """ + ... + + def OpenTextFile(self, + filename: FILE, + iomode: Literal[1, 2, 8] = ..., + create: bool = ..., + encoding: str = ..., + ) -> TEXTSTREAM: + """ + Opens a specified file and returns a ``TextStream`` object that can be used to read from, + write to, or append to the file. + Args + ``filename``: identifies the file to open. + + ``iomode``: indicates input/output mode. It can be one of three constants: + ``filesystem.ForReading`` (default), ``filesystem.ForWriting``, or ``filesystem.ForAppending``. + + ``create``: boolean value that indicates whether a new file can be created if the specified + filename doesn't exist. The value is ``True`` if a new file and its parent folders + may be created. ``False`` if they aren't created. Defaults to ``False``. + + ``encoding``: the character set that should be used. Defaults to "UTF-8". + Returns + A ``TEXTSTREAM`` instance representing the opened file or ``None`` if an error occurred. + The method does not check if the file is really a text file. It doesn't check either + if the given encoding is implemented in LibreOffice nor if it is the right one. + """ + ... + + def PickFile(self, + defaultfile: FILE = ..., + mode: Literal['OPEN', 'SAVE'] = ..., + filter: str = ..., + ) -> FILE: + """ + Opens a dialog box to open or save a file. + + If the ``SAVE`` mode is set and the picked file exists, a warning message will be displayed. + Args + ``defaultfile``: this argument is a string composed of a folder and file name. + The folder part indicates the folder that will be shown when the dialog opens + (default = the last selected folder). The file part designates the default file to open or save. + + ``mode``: a string value that can be either "OPEN" (for input files) or + "SAVE" (for output files). The default value is "OPEN". + + ``filter``: the extension of the files displayed when the dialog is opened + (default = no filter). + Returns + The selected FileName in ``filesystem.FileNaming`` format or "" if the dialog was cancelled. + """ + ... + + def PickFolder(self, defaultfolder: FILE = ..., freetext: str = ...) -> FILE: + """ + Display a dialog box to select a folder. + Args + ``defaultfolder``: the folder from which to start. Default = the last selected folder. + + ``freetext``: text to display in the dialog. Defaults to "". + Returns + The selected folder in ``filesystem.FileNaming`` notation. + A zero-length string if the dialog was cancelled. + """ + ... + def SubFolders(self, + foldername: FILE, + filter: str = ..., + includesubfolders: bool = ... + ) -> Tuple[str, ...]: + """ + Returns a tuple of strings corresponding to the folders stored + in the given ``foldername``. + The list may be filtered with wildcards. + Args + ``foldername``: a string representing a folder. The folder must exist. ``foldername`` must not + designate a file. + + ``filter``: a string containing wildcards ("?" and "*") that will be applied to the resulting + list of folders (default = ""). + + ``includesubfolders``: set this argument to ``True`` to include the contents of + subfolders (Default = ``False``). + """ + ... + + # ######################################################################### + # SF_L10N CLASS + # ######################################################################### + class SF_L10N(SFServices): + """ + This service provides a number of methods related to the translation of strings + with minimal impact on the program's source code. + + The methods provided by the L10N service can be used mainly to: + - Create POT files that can be used as templates for translation of all strings in the program. + - Get translated strings at runtime for the language defined in the Locale property. + """ + + Folder: FILE + """ The folder containing the ``PO`` files """ + Languages: Tuple[str, ...] + """ A list of all the base names (without the ``.po`` extensions found in the specified ``folder``. """ + Locale: str + """ The currently active ``language-COUNTRY`` combination. """ + + def AddText(self, context: str = ..., msgid: str = ..., comment: str = ...) -> bool: + """ + Adds a new entry in the list of localizable strings. It must not exist yet. + Args + ``context``: the key to retrieve the translated string with the GetText method. + This parameter has a default value of "". + + ``msgid``: the untranslated string, which is the text appearing in the program code. ``msgid`` + must not be empty. + + The ``msgid`` becomes the key to retrieve the translated string via + the ``GetText()`` method when ``context`` is empty. + The ``msgid`` string may contain any number of placeholders (%1 %2 %3 ...) for dynamically + modifying the string at runtime. + + ``comment``: optional comment to be added alongside the string to help translators. + Returns + ``True`` if successful. + """ + ... + + def AddTextsFromDialog(self, dialog: DIALOG) -> bool: + """ + Add all fixed text strings of a dialog to the list of localizable text strings. + + Added texts are: + - The title of the dialog. + - The caption associated with next control types: Button, CheckBox, FixedLine, FixedText, GroupBox and RadioButton. + - The content of list- and combo boxes. + - The tip- or help text displayed when the mouse is hovering the control. + + The current method has method ``SFDialogs.SF_Dialog.GetTextsFromL10N()`` as counterpart. + The targeted dialog must not be open when the current method is run. + Args + ``dialog``: a SFDialogs.Dialog service instance + Returns + ``True`` when successful. + """ + ... + + def ExportToPOTFile(self, filename: FILE, header: str = ..., encoding: str = ...) -> bool: + """ + Export a set of untranslated strings as a POT file. + The set of strings has been built either by a succession of AddText() methods + or by a successful invocation of the L10N service with the ``FolderName`` argument. + The generated file should pass successfully the ``"msgfmt --check 'the pofile'"`` GNU command. + Args + ``filename``: the complete file name (in ``filesstem.FileNaming`` notation) + to export to. If it exists, it is overwritten without warning. + + ``header``: comments that will appear on top of the generated file. Do not include + any leading "#". If the string spans multiple lines, insert escape sequences (``\\n``) where + relevant. A standard header will be added anyway. Defaults to "". + + ``encoding``: the character set that should be used. Defaults to "UTF-8". + Returns + ``True`` if successful. + """ + ... + + def GetText(self, msgid: str, *args: Any) -> str: + """ + Gets the translated string corresponding to the given ``msgid`` argument. + A list of arguments may be specified to replace the placeholders (%1, %2, ...) in the string. + Args + ``msgid``: the untranslated string, which is the text appearing in the program code. + It must not be empty. It may contain any number of placeholders (%1 %2 %3 ...) that can be used + to dynamically insert text at runtime. + + Besides using a single ``msgid`` string, this method also accepts the following formats: + - the untranslated text (``msgid``) + - the reference to the untranslated text (``context``) + - both (``context|msgId``), use the pipe character as delimiter. + + ``args``: values to be inserted into the placeholders. + Any variable type is allowed, however only strings, numbers and dates will be considered. + Returns + The translated string. If no translated string is found, the method returns the untranslated + string after replacing the placeholders with the specified arguments. + """ + ... + + # ######################################################################### + # SF_Platform CLASS + # ######################################################################### + class SF_Platform(SFServices, metaclass = ...): + """ + The ``Platform`` service implements a collection of properties about the actual execution environment + and context, such as : + - the hardware platform + - the operating system + - the LibreOffice version + - the current user + All its properties are read-only. + """ + + Architecture: str + """ The hardware bit architecture. Example: '32bit' or '64bit'. """ + ComputerName: str + """ The computer's network name. """ + CPUCount: int + """ The number of central processing units. """ + CurrentUser: str + """ The name of the currently logged user. """ + Extensions: Tuple[str, ...] + """ An array of strings containing the internal IDs of all installed extensions. """ + FilterNames: Tuple[str, ...] + """ An array of strings containing the available document import and export filter names. """ + Fonts: Tuple[str, ...] + """ An array of strings containing the names of all available fonts. """ + FormatLocale: str + """ The locale used for numbers and dates as a string in the format "la-CO" (language-COUNTRY). """ + Locale: str + """ The locale of the operating system as a string in the format "la-CO" (language-COUNTRY). + This is equivalent to the ``SystemLocale`` property. """ + Machine: str + """ The machine type. Examples are: 'i386' or 'x86_64'. """ + OfficeLocale: str + """ The locale of the user interface as a string in the format "la-CO" (language-COUNTRY). """ + OfficeVersion: str + """ The actual LibreOffice version expressed as ``LibreOffice w.x.y.z (The Document Foundation)``. """ + OSName: str + """ The operating system type. Example: 'Darwin, Linux' or 'Windows'. """ + OSPlatform: str + """ A single string identifying the underlying platform with as much useful and human-readable information + as possible. Example: ``Linux-5.8.0-44-generic-x86_64-with-glibc2.32``. """ + OSRelease: str + """ The operating system's release. Example: ``5.8.0-44-generic``. """ + OSVersion: str + """ The operating system's build or version. Example: ``#50-Ubuntu SMP Tue Feb 9 06:29:41 UTC 2021 `` """ + Printers: Tuple[str, ...] + """ The list of available printers. The default printer is put in the first position of the list + (index = [0]). """ + Processor: str + """ The real processor name. Example: ``amdk6``. This property may return the same value as the ``Machine`` + property. """ + PythonVersion: str + """ The version of the Python interpreter being used as a string in the format ``Python major.minor.patchlevel`` + (ex: ``Python 3.9.7``). """ + SystemLocale: str + """ The locale of the operating system as a string in the format "la-CO" (language-COUNTRY). + This is equivalent to the ``Locale`` property. """ + UserData: DICTIONARY + """ Returns a ``Dictionary`` instance containing key-value pairs in relation with the + ``Tools - Options - User Data`` dialog. """ + + # ######################################################################### + # SF_Region CLASS + # ######################################################################### + class SF_Region(SFServices, metaclass = ...): + """ + The "Region" service gathers a collection of functions about languages, countries and timezones + - Locales + - Currencies + - Numbers and dates formatting + - Calendars + - Timezones conversions + - Numbers transformed to text in any supported language + """ + + def Country(self, region: str = ...) -> str: + """ + Gets the country name in English corresponding to a given region. + Args + ``region``: formatted as "la-CO" or "CO". + """ + ... + + def Currency(self, region: str = ...) -> str: + """ + Gets the ISO 4217 currency code of the specified region. + Args: + ``region``: formatted as "la-CO" or "CO". + """ + ... + + def DatePatterns(self, region=...) -> Tuple[str, ...]: + """ + Gets an array of strings containing the date acceptance patterns for the specified region. + Args + ``region``: formatted as "la-CO". + """ + ... + + def DateSeparator(self, region: str = ...) -> str: + """ + Returns the date separator used in the given region. + Args + ``region``: formatted as "la-CO". + """ + ... + + def DayAbbrevNames(self, region: str = ...) -> Tuple[str, ...]: + """ + Gets an array of strings containing the list of abbreviated weekday names in the specified language. + Args + ``region``: formatted as "la-CO" or "la". + """ + ... + + def DayNames(self, region: str = ...) -> Tuple[str, ...]: + """ + Gets an array of strings containing the list of weekday names in the specified language. + Args + ``region``: formatted as "la-CO" or "la". + """ + ... + + def DayNarrowNames(self, region: str = ...) -> Tuple[str, ...]: + """ + Gets a zero-based array of strings containing the list of the initials of weekday names + in the specified language. + Args + ``region``: formatted as "la-CO" or "la". + """ + ... + + def DecimalPoint(self, region: str = ...) -> str: + """ + Gets the decimal separator used in numbers in the specified region. + Args + ``region``: formatted as "la-CO". + """ + ... + + def Language(self, region: str = ...) -> str: + """ + Gets tthe name of the language, in English, of the specified region. + Args + ``region``: formatted as "la-CO" or "la". + """ + ... + + def ListSeparator(self, region: str = ...) -> str: + """ + Gets the list separator used in the specified region. + Args + ``region``: formatted as "la-CO". + """ + ... + + def MonthAbbrevNames(self, region: str = ...) -> Tuple[str, ...]: + """ + Gets a zero-based array of strings containing the list of abbreviated month names + in the specified language. + Args + ``region``: formatted as "la-CO". + """ + ... + + def MonthNames(self, region: str = ...) -> Tuple[str, ...]: + """ + Gets an array of strings containing the list of month names in the specified language. + Args + ``region``: formatted as "la-CO" or "la". + """ + ... + + def MonthNarrowNames(self, region: str = ...) -> Tuple[str, ...]: + """ + Gets an array of strings containing the list of the initials of month names in the specified language. + Args + ``region``: formatted as "la-CO" or "la". + """ + ... + + def ThousandSeparator(self, region: str = ...) -> str: + """ + Gets the thousands separator used in numbers in the specified region. + Args + ``region``: formatted as "la-CO". + """ + ... + + def TimeSeparator(self, region: str = ...) -> str: + """ + Gets the separator used to format times in the specified region. + Args + ``region``: formatted as "la-CO". + """ + ... + + def DSTOffset(self, localdatetime: datetime.datetime, timezone: str, locale: str = ...) -> int: + """ + Computes the additional Daylight Saving Time (DST) offset, in minutes, that is applicable + to a given region and timezone. + Args + ``localdatetime``: the local date and time to consider. + + ``timezone``: the timezone for which the offset will be calculated. + + ``locale``: the locale specifying the country for which the offset will be calculated, + given either in "la-CO" or "CO" formats. The default value is the locale defined + in the ``OfficeLocale`` property of the ``Platform`` service. + """ + ... + + def LocalDateTime(self, utcdatetime: datetime.datetime, timezone: str, locale: str = ...) -> datetime.datetime: + """ + Computes the local date and time from a UTC date and time. + Args + ``utcdatetime``: the UTC date and time, expressed using a date object. + + ``timezone``: the timezone for which the local time will be calculated. + + ``locale``: the locale specifying the country for which the offset will be calculated, + given either in "la-CO" or "CO" formats. The default value is the locale defined + in the ``OfficeLocale`` property of the ``Platform`` service. + """ + ... + + def Number2Text(self, number: Union[int, float, str], locale: str = ...) -> str: + """ + Converts numbers and monetary values into written text for any of the currently supported languages. + Args + ``number``: the number to be converted into written text. + It can be provided either as a numeric type or as a string. When a string is provided, + it can be preceded by a prefix informing how the numbers should be written. + It is also possible to include ISO 4217 currency codes. + + ``locale``: the locale defining the language into which the number will be converted to, + given either in "la-CO" or "la" formats. + The default value is the locale defined in the ``OfficeLocale`` property of the ``Platform`` + service. + Returns + The converted number or monetary value in letters. + """ + ... + + def TimeZoneOffset(self, timezone: str, locale: str = ...) -> int: + """ + Gets the offset between GMT and the given timezone and locale, in minutes. + Args + ``imezone``: the timezone for which the offset to the GMT will be calculated. + + ``locale``: the locale specifying the country for which the offset will be calculated, + given either in "la-CO" or "CO" formats. + The default value is the locale defined in the ``OfficeLocale`` property + of the ``Platform`` service. + """ + ... + + def UTCDateTime(self, localdatetime: datetime.datetime, timezone: str, locale: str = ...) -> datetime.datetime: + """ + Gets the UTC date and time considering a given local date and time in a timezone. + Args + ``localdatetime``: the local date and time in a specific timezone, expressed as a date. + + ``timezone``: the timezone for which the ``localdatetime`` argument is given. + + ``locale``: the locale specifying the country for which the ``localdatetime`` argument is given, + expressed either in "la-CO" or "CO" formats. The default value is the locale defined + in the ``OfficeLocale`` property of the ``Platform`` service. + """ + ... + + def UTCNow(self, timezone: str, locale: str = ...) -> datetime.datetime: + """ + Gets the current UTC date and time, given a timezone and a locale. + Args + ``timezone``: the timezone for which the current UTC time will be calculated. + + ``locale``: the locale specifying the country for which the current UTC time will be calculated, + expressed either in "la-CO" or "CO" formats. The default value is the locale defined + in the ``OfficeLocale`` property of the ``Platform`` service. + """ + ... + + # ######################################################################### + # SF_Session CLASS + # ######################################################################### + class SF_Session(SFServices, metaclass = ...): + """ + The Session service gathers various general-purpose methods about: + - UNO introspection + - the invocation of external scripts or programs + - send mails + - ... + """ + + # Class constants Where to find an invoked library ? + SCRIPTISEMBEDDED: Literal["document"] + """ The invoked library is in the document (Basic + Python). """ + SCRIPTISAPPLICATION: Literal["application"] + """ The invoked library is in any shared library (Basic). """ + SCRIPTISPERSONAL: Literal["user"] + """ The invoked library is in My Macros (Python). """ + SCRIPTISPERSOXT: Literal["user:uno_packages"] + """ The invoked library is in an extension installed for the current user (Python). """ + SCRIPTISSHARED: Literal["share"] + """ The invoked library is in LibreOffice macros (Python). """ + SCRIPTISSHAROXT: Literal["share:uno_packages"] + """ The invoked library is in an extension installed for all users (Python). """ + SCRIPTISOXT: Literal["uno_packages"] + """ The invoked library is in an extension but the installation parameters are unknown (Python). """ + + @classmethod + def ExecuteBasicScript( + cls, scope: str = ..., script: str = ..., *args: Optional[Any] + ) -> Any: + """ + Execute the Basic script given its name and location and fetch its result if any. + + If the script returns nothing, which is the case of procedures defined with Sub, + the returned value is ``None``. + Args + ``scope``: string specifying where the script is stored. + + ``script``: string specifying the script to be called in the format + "library.module.method" as a case-sensitive string. + + ``args``: the arguments to be passed to the called script. + Notes + Argument ``scope`` can be either: + - "document" (= ``session.SCRIPTISEMBEDDED``) + - "application" (= ``session.SCRIPTISAPPLICATION``). + + About argument ``script``: + - The library is loaded in memory if necessary. + - The module must not be a class module. + - The method may be a ``Sub`` or a ``Function``. + Returns + The value returned by the called script. + """ + ... + + @classmethod + def ExecuteCalcFunction(cls, calcfunction: str, *args: Any) -> Any: + """ + Execute a Calc function using its English name and based on the given arguments. + If the arguments are arrays, the function is executed as an array formula. + Args + ``calcfunction``: the name of the Calc function to be called, in English. + + ``args``: the arguments to be passed to the called Calc function. + Each argument must be either a string, a numeric value or an array of arrays combining + those types. + Returns + The value returned by the function. + """ + ... + + @classmethod + def ExecutePythonScript(cls, scope: str = ..., script: str = ..., *args: Any) -> Any: + """ + Execute the Python script given its location and name, fetch its result if any. + Result can be a single value or an array of values. + + If the script is not found, or if it returns nothing, the returned value is ``None``. + Args + ``scope``: one of the applicable constants listed. See Notes. + + ``script``: either "library/module.py$method" or "module.py$method" + or "myExtension.oxt|myScript|module.py$method" as a case-sensitive string. + Notes + Arg ``scope`` can be either + - "document" (= ``session.SCRIPTISEMBEDDED``) + - "application" (= ``session.SCRIPTISAPPLICATION``) + - "user" (= ``session.SCRIPTISPERSONAL``) + - "user:uno_packages" (= ``session.SCRIPTISPERSOXT``) + - "share" (= ``session.SCRIPTISSHARED``). Default value. + - "share:uno_packages" (= ``session.SCRIPTISSHAROXT``) + - "uno_packages" (= ``session.SCRIPTISOXT``) + + About argument ``script``: + - ``library``: The folder path to the Python module. + - ``myScript``: The folder containing the Python module. + - ``module.py``: The Python module. + - ``method``: The Python function. + Returns + The value(s) returned by the call to the script. If > 1 values, enclosed in a tuple. + """ + ... + + def GetPDFExportOptions(self) -> DICTIONARY: + """ + Returns the current PDF export settings defined in the ``PDF Options`` dialog, which can be accessed + by choosing ``File - Export as - Export as PDF``. + Returns + A ``Dictionary`` object wherein each key represents an export option and the corresponding + value is the current PDF export setting. + """ + ... + + def HasUnoMethod(self, unoobject: UNO, methodname: str) -> bool: + """ + Returns ``True`` if a UNO object contains the given method. + Args + ``unoobject``: the object to inspect. + + ``methodname``: the name of the method as a string. The search is case-sensitive. + Returns + ``False`` when the method is not found or when an argument is invalid. + """ + ... + + def HasUnoProperty(self, unoobject: UNO, propertyname: str) -> bool: + """ + Returns ``True`` if a UNO object contains the given property. + Args + ``unoobject``: the object to inspect. + + ``propertyname``: the name of the property as a string. The search is case-sensitive. + Returns + ``False`` when the property is not found or when an argument is invalid. + """ + ... + + @classmethod + def OpenURLInBrowser(cls, url: str) -> None: + """ + Opens a given URL in the default browser. + Args + ``url``: The URL to open in the browser. + """ + ... + + def RunApplication(self, command: str, parameters: str) -> bool: + """ + Executes an arbitrary system command. + Args + ``command``: the command to execute. + This may be an executable file or a file which is registered with an application + so that the system knows what application to launch for that file. A file must be + expressed in the current ``filesystem.FileNaming`` notation. + + ``parameters``: a list of space separated parameters as a single string. + The method does not validate the given parameters, but only passes them to the specified + command. + Returns + ``True`` if the command was launched successfully. + """ + ... + def SendMail(self, + recipient: str, + cc: str = ..., + bcc: str = ..., + subject: str = ..., + body: str = ..., + filenames: str = ..., + editmessage: bool = ..., + ) -> None: + """ + Send a message (with or without attachments) to recipients from the user's mail client. + The message may be edited by the user before sending or, alternatively, be sent immediately. + Args + ``recipient``: an email addresses (To recipient). + + ``cc``: a comma-delimited list of email addresses (carbon copy). Defaults to ''. + + ``bcc``: a comma-delimited list of email addresses (blind carbon copy). Defaults to ''. + + ``subject``: the header of the message. Defaults to ''. + + ``body``: the unformatted text of the message. Defaults to ''. + + ``filenames``: a comma-separated list of filenames to attach to the mail. + ``filesystem.FileNaming`` naming conventions apply. Defaults to ''. + + ``editmessage``: when ``True`` (default) the message is editable before being sent. + """ + ... + + def SetPDFExportOptions(self, pdfoptions: DICTIONARY) -> bool: + """ + Modifies the PDF export settings defined in the ``PDF Options`` dialog, which can be accessed + by choosing ``File - Export as - Export as PDF``. + + The new settings can be used by the ``ExportAsPDF()`` method from the ``Document`` service. + Args + ``pdfoptions``: a ``Dictionary`` object that defines the PDF export settings to be changed. + Each key-value pair represents an export option and its new value. + Returns + ``True`` when successful. + """ + ... + + def UnoMethods(self, unoobject: UNO) -> Tuple[str, ...]: + """ + Returns a tuple of the methods callable from an UNO object. The tuple may be empty. + Args + ``unoobject``: the object to inspect. + """ + ... + + def UnoObjectType(self, unoobject: UNO) -> str: + """ + Identify the UNO class of an UNO object. + Args + ``unoobject``: the object to inspect. + Returns + ``com.sun.star. ...`` as a string or a zero-length string if the identification was not + successful. + """ + ... + + def UnoProperties(self, unoobject: UNO) -> Tuple[str, ...]: + """ + Returns a tuple of the properties callable from an UNO object. The tuple may be empty. + Args + ``unoobject``: the object to inspect. + """ + ... + + def WebService(self, uri: str) -> str: + """ + Get some web content from a URI. + Args + ``uri ``: text of the web service. + Returns + The web page content of the URI. + """ + ... + # ######################################################################### + # SF_String CLASS + # ######################################################################### + class SF_String(SFServices, metaclass = ...): + """ + Focus on string manipulation, regular expressions, encodings and hashing algorithms. + The methods implemented in Basic that are redundant with Python builtin functions + are not duplicated. + """ + + sfCR: str + """ Carriage return (ASCII 13). """ + sfCRLF: str + """ Carriage return + linefeed (ASCII 13 + 10). """ + sfLF: str + """ Linefeed (ASCII 10). """ + sfNEWLINE: str + """ Depending on the operating system, either Carriage return + Linefeed (ASCII 13 + 10) + or Linefeed (ASCII 10). """ + sfTAB: str + """ Horizontal tabulation (ASCII 09). """ + + @classmethod + def HashStr(cls, + inputstr: str, + algorithm: Literal['MD5', 'SHA1', 'SHA224', 'SHA256', 'SHA384', 'SHA512'], + ) -> str: + """ + Return a hexadecimal string representing a checksum of the given input string. + Args + ``inputstr``: the string to be hashed. + + ``algorithm``: the hashing algorithm to use. + Returns + The requested checksum as a string. Hexadecimal digits are lower-cased. + A zero-length string when an error occurred. + Note + The supported hashing algorithms are: + - MD5 + - SHA1 + - SHA224 + - SHA256 + - SHA384 + - SHA512 + """ + ... + + def IsADate(self, + inputstr: str, + dateformat: Literal['YYYY-MM-DD', 'DD-MM-YYYY', 'MM-DD-YYYY', + 'YYYY/MM/DD', 'DD/MM/YYYY', 'MM/DD/YYYY', + 'YYYY.MM.DD', 'DD.MM.YYYY', 'MM.DD.YYYY', + 'YYYY MM DD', 'DD MM YYYY', 'MM DD YYYY'] = ..., + ) -> bool: + """ + Return ``True`` if the string is a valid date respecting the given format. + Args + ``inputstr``: the input string. + + ``dateformat``: either ``YYYY-MM-DD`` (default), ``DD-MM-YYYY`` or ``MM-DD-YYYY``. + The dash (-) may be replaced by a dot (.), a slash (/) or a space. + Returns + ``True`` if the string contains a valid date and there is at least one character. + ``False`` otherwise or if the date format is invalid. + """ + ... + + def IsEmail(self, inputstr: str) -> bool: + """ + Return ``True`` if the string is a valid email address. + Args + ``inputstr``: the input string. + Returns + ``True`` if the string contains an email address and there is at least one character, + ``False`` otherwise. + """ + ... + + def IsFileName(self, inputstr: str, osname: Literal['WINDOWS', 'LINUX', 'MACOS', 'SOLARIS'] = ...) -> bool: + """ + Return ``True`` if the string is a valid filename in a given operating system. + Args + ``inputstr``: the input string. + + ``osname``: the default is the current operating system on which the script is run. + Returns + ``True`` if the string contains a valid filename and there is at least one character, + + """ + ... + + def IsIBAN(self, inputstr: str) -> bool: + """ + Returns ``True`` if the input string is a valid International Bank Account Number. + Args + ``inputstr``: the input string. + Returns + ``True`` if the string contains a valid IBAN number. The comparison is not case-sensitive. + """ + ... + + def IsIPv4(self, inputstr: str) -> bool: + """ + Return ``True`` if the string is a valid IPv4 address. + Args + ``inputstr``: the input string. + Returns + ``True`` if the string contains a valid IPv4 address and there is at least one character, + ``False`` otherwise. + """ + ... + + def IsLike(self, inputstr: str, pattern: str, casesensitive: bool = ...) -> bool: + """ + Returns True if the whole input string matches a given pattern containing wildcards. + Args + ``inputstr``: the input string. + + ``pattern``: the pattern as a string. The ``?`` represents any single character. + The ``*`` represents zero, one, or multiple characters. + + ``casesensitive``: defaults to ``False``. + Returns + ``True`` if a match is found. Zero-length input or pattern strings always return ``False``. + """ + ... + + def IsSheetName(self, inputstr: str) -> bool: + """ + Return ``True`` if the input string can serve as a valid Calc sheet name. + + The sheet name must not contain the characters ``[ ] * ? : / \\`` + or the character ``'`` (apostrophe) as first or last character. + Args + ``inputstr``: the input string. + Returns + ``True`` if the string is validated as a potential Calc sheet name, ``False`` otherwise. + """ + ... + + def IsUrl(self, inputstr: str) -> bool: + """ + Return ``True`` if the string is a valid absolute URL (Uniform Resource Locator). + Args + ``inputstr``: the input string. + Returns + ``True`` if the string contains a URL and there is at least one character, ``False`` otherwise. + """ + ... + + def SplitNotQuoted(self, + inputstr: str, + delimiter: str = ..., + occurrences: int = ..., + quotechar: Literal["'", '"'] = ..., + ) -> Tuple[str, ...]: + """ + Split a string on ``delimiter`` into an array. If ``delimiter`` is part of a quoted (sub)string, + it is ignored. Use case: parsing of csv-like records containing quoted strings. + Args + ``inputstr``: the input string. + + ``delimiter``: a string of one or more characters that is used to delimit the input string. + Defaults to ' ' (space). + + ``occurrences``: the maximum number of substrings to return (Default = 0, meaning no limit). + + ``quotechar``: the quoting character, either ``"`` (default) or ``'``. + Returns + A tuple whose items are chunks of the input string, The ``delimiter`` is not included. + """ + ... + + def Wrap(self, inputstr: str, width: int = ..., tabsize: int = ...) -> Tuple[str, ...]: + """ + Wraps every single paragraph in text (a string) so every line is at most ``width`` characters long. + Args + ``inputstr``: the input string. + + ``width``: the maximum number of characters in each line. Defaults to 70. + + ``tabsize``: before wrapping the text, the existing TAB (ASCII 09) characters are replaced with + spaces. ``TabSize`` defines the TAB positions at + ``TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1``. Defaults to 8. + Returns + A tuple of output lines, without final newlines except the pre-existing line-breaks. + Tabs are expanded. Symbolic line breaks are replaced by their hard equivalents. + If the wrapped output has no content, the returned tuple is empty. + """ + ... + + # ######################################################################### + # SF_TextStream CLASS + # ######################################################################### + class SF_TextStream(SFServices): + """ + The ``TextStream`` service is used to sequentially read from and write to files opened or created + using the ScriptForge.FileSystem service. + """ + + AtEndOfStream: bool + """ Used in read mode. A ``True`` value indicates that the end of the file has been reached. + A test using this property should precede calls to the ``ReadLine()`` method. """ + Encoding: str + """ The character set to be used. The default encoding is "UTF-8". """ + FileName: FILE + """ Returns the name of the current file either in URL format or in the native operating system's format, + depending on the current value of the ``FileNaming`` property of the ``filesystem`` service. """ + IOMode: Literal['READ', 'WRITE', 'APPEND'] + """ The input/output mode. """ + Line: int + """ The number of lines read or written so far. """ + NewLine: str + """ Sets or returns the current delimiter to be inserted between two successive written lines. + The default value is the native line delimiter in the current operating system. """ + + def CloseFile(self) -> bool: + """ + Empties the output buffer if relevant. Closes the actual input or output stream. + Returns + ``True`` if the closure was successful. + """ + ... + + def ReadAll(self) -> str: + """ + Returns all the remaining lines in the text stream as one string. Line breaks are NOT removed. + The resulting string can be split in lines either by using the usual ``split()`` builtin function. + Returns + The read lines. The string may be empty. + Note + The ``Line`` property is incremented only by 1. + """ + ... + + def ReadLine(self) -> str: + """ + Returns the next line in the text stream as a string. Line breaks are removed. + Returns + The read line. The string may be empty. + """ + ... + + def SkipLine(self) -> None: + """ + Skips the next line when reading a ``TextStream`` file. This method can result in ``AtEndOfStream`` + being set to ``True``. + """ + ... + + def WriteBlankLines(self, lines: int) -> None: + """ + Writes a number of empty lines in the output stream. + Args + ``lines``: the number of lines to write. + """ + ... + + def WriteLine(self, line: str) -> None: + """ + Writes the given line to the output stream. A newline is inserted if relevant. + Args + ``line``: the line to write, may be the empty string. + """ + ... + + # ######################################################################### + # SF_Timer CLASS + # ######################################################################### + class SF_Timer(SFServices): + """ + The ``Timer`` service measures the amount of time it takes to run user scripts. + + A ``Timer`` measures durations. It can be: + - Started, to indicate when to start measuring time. + - Suspended, to pause measuring running time. + - Resumed, to continue tracking running time after the Timer has been suspended. + - Restarted, which will cancel previous measurements and start the Timer at zero. + """ + + Duration: float + """ The actual running time elapsed since start or between start and stop (not considering suspended time). """ + IsStarted: bool + """ ``True`` when timer is started or suspended. """ + IsSuspended: bool + """ ``True`` when timer is started and suspended. """ + SuspendDuration: float + """ The actual time elapsed while suspended since start or between start and stop. """ + TotalDuration: float + """ The actual time elapsed since start or between start and stop (including suspensions and running time). + ``TotalDuration = Duration + SuspendDuration``. """ + + def Continue(self) -> bool: + """ + Continue/Resume a suspended timer. + Returns + ``True`` except if the timer is not in suspended state. + """ + ... + + def Restart(self) -> bool: + """ + Terminate the timer and restart a new clean timer. + Returns + ``True`` except if the timer is inactive. + """ + ... + + def Start(self) -> bool: + """ + Start a new clean timer. + Returns + ``True`` except if the timer is already started. + """ + ... + + def Suspend(self) -> bool: + """ + Suspend a running timer. + Returns + ``True`` except if the timer is not started or already suspended. + """ + ... + + def Terminate(self) -> bool: + """ + Terminate a running timer. + Returns + ``True`` except if the timer is neither started nor suspended. + """ + ... + + # ######################################################################### + # SF_UI CLASS + # ######################################################################### + class SF_UI(SFServices, metaclass = ...): + """ + Class for the identification and the manipulation of the different windows composing the whole + ``LibreOffice`` application: + - Windows selection + - Windows moving and resizing + - Statusbar settings + - Creation of new windows + - Access to the underlying "documents" + + Windows can be designated using different ``WindowNames``: + - a full path and file name + - the last component of the full file name or even only the last component without its suffix + - the title of the window + - for new documents, something like "Untitled 1" + - one of the special windows ``BASICIDE`` and ``WELCOMESCREEN`` + A ``WindowName`` is case-sensitive. + """ + + MACROEXECALWAYS: Literal[2] + """ Macros are always executed. """ + MACROEXECNEVER: Literal[1] + """ Macros are never executed. """ + MACROEXECNORMAL: Literal[0] + """ Macro execution depends on user settings. """ + + ActiveWindow: str + """ A valid and unique WindowName for the currently active window. When the window cannot be identified, + a zero-length string is returned. """ + + Height: int + """ The height of the active window in pixels. """ + Width: int + """ The width of the active window in pixels. """ + + X: int + """ The X coordinate of the active window, which is the distance to the left edge of the screen in pixels. """ + + Y: int + """ The Y coordinate of the active window, which is the distance to the top edge of the screen in pixels. + This value does not consider window decorations added by your operating system, so even when the window + is maximized this value may not be zero. """ + + def Activate(self, windowname: str = ...) -> bool: + """ + Make the specified window active. + Args + ``windowname``: see definitions at ``SF_UI`` class level. + Returns + ``True`` if the given window is found and can be activated. + There is no change in the actual user interface if no window matches the selection. + """ + ... + + def CreateBaseDocument(self, + filename: str, + embeddeddatabase: Literal['HSQLDB', 'FIREBIRD', 'CALC'] = ..., + registrationname: str = ..., + calcfilename: str = ..., + ) -> BASE: + """ + Create a new LibreOffice Base document embedding an empty database of the given type. + Args + ``filename``: identifies the file to create. It must follow the ``FileSystem.FileNaming`` + notation. If the file already exists, it is overwritten without warning. + + ``embeddeddatabase``: either ``HSQLDB`` or ``FIREBIRD`` or ``CALC``. Defaults to ``HSQLDB``. + + ``registrationname``: the name used to store the new database in the databases register. + If "" (default), no registration takes place. If the name already exists it is overwritten + without warning. + + ``calcfilename``: only when ``embeddeddatabase`` = ``CALC``, the name of the file containing + the tables as Calc sheets. The name of the file must be given in ``FileSystem.FileNaming`` + notation. The file must exist. + Returns + A ``Base`` service instance. + """ + ... + + def CreateDocument(self, + documenttype: Literal['', 'calc', 'draw', 'impress', 'math', 'writer', + 'Calc', 'Draw', 'Impress', 'Math', 'Writer', + 'CALC', 'DRAW', 'IMPRESS', 'MATH', 'WRITER'] = ..., + templatefile: FILE = ..., + hidden: bool = ... + ) -> Union[DOCUMENT, CALC, WRITER]: + """ + Create a new ``LibreOffice`` document of a given type or based on a given template. + Args + ``documenttype``: Calc, Writer, etc. If absent, a ``templatefile`` must be given. + + ``templatefile``: the full ``FileName`` of the template to build the new document on. + If the file does not exist, the argument is ignored. + The ``FileSystem`` service provides the ``TemplatesFolder`` and ``UserTemplatesFolder`` + properties to help to build the argument. Defaults to ''. + + ``hidden``: if ``True``, open in the background. Defaults to ``False``. + To use with caution: activation or closure can only happen programmatically. + Returns + A ``Document`` object or one of its subclasses. + Note + Use the ``CreateBaseDocument()`` method to create a new ``Base`` document. + """ + ... + + def Documents(self) -> Tuple[str, ...]: + """ + Returns the list of the currently open documents. Special windows are ignored. + Returns + An array either of file names (in ``FileSystem.FileNaming`` notation) or of window titles + for unsaved documents. + """ + ... + + def GetDocument( + self, + windowname: Union[str, XComponent, XOfficeDatabaseDocument] = ... + ) -> Union[BASE, CALC, DOCUMENT, FORMDOCUMENT, WRITER]: + """ + Returns a ``Document`` object referring to the active window or the given window. + Args + ``windowname``: when a string, see definitions in ``SF_UI``. If absent the active window is + considered. When an object, must be a UNO object of types ``XComponent`` + or ``XOfficeDatabaseDocument``. + Returns + A ``Document`` object or one of its subclasses. + + """ + ... + + def Maximize(self, windowname: str = ...) -> None: + """ + Maximizes the active window or the given window. + Args + ``windowname``: see definitions in ``SF_UI``. If absent the active window is considered. + """ + ... + + def Minimize(self, windowname: str = ...) -> None: + """ + Minimizes the active window or the given window. + Args + ``windowname``: see definitions in ``SF_UI``. If absent the active window is considered. + """ + ... + + def OpenBaseDocument(self, + filename: FILE = ..., + registrationname: str = ..., + macroexecution: Literal[0, 1, 2] = ..., + ) -> BASE: + """ + Open an existing LibreOffice Base document and return a SFDocuments.Base object. + Args + ``filename``: identifies the file to open. + It must follow the ``FileSystem.FileNaming`` notation. Defaults to ''. + + ``registrationname``: the name of a registered database. + It is ignored if FileName <> "". Defaults to ''. + + ``macroexecution``: one of the MACROEXECxxx constants. Defaults to ``MACROEXECNORMAL``. + Returns + A ``Base`` object. + """ + ... + + def OpenDocument(self, + filename: FILE, + password: str = ..., + readonly: bool = ..., + hidden: bool = ..., + macroexecution: Literal[0, 1, 2] = ..., + filtername: str = ..., + filteroptions: str = ..., + ) -> Union[DOCUMENT, CALC, WRITER]: + """ + Open an existing LibreOffice document with the given options. + Args + ``filename``: identifies the file to open. It must follow the ``FileSystem.FileNaming`` + notation. + + ``password``: to use when the document is protected. If wrong or absent while the document + is protected, the user will be prompted to enter a password. + + ``readonly``: defaults to ``False``. + + ``hidden``: if ``True``, open in the background. Defaults to ``False``. + ``True`` to use with caution: activation or closure can only happen programmatically. + + ``macroexecution``: one of the MACROEXECxxx constants. Defaults to ``MACROEXECNORMAL``. + + ``filtername``: the name of a filter that should be used for loading the document. + If present, the filter must exist. Defaults to ''. + + ``filteroptions``: an optional string of options associated with the filter. + Returns + A ``Document`` object or one of its subclasses, or + None if the opening failed, including when due to a user decision. + """ + ... + + def Resize(self, left: int = ..., top: int = ..., width: int = ..., height: int = ...) -> None: + """ + Resizes and/or moves the active window. Negative or absent arguments are ignored. + If the window was minimized or without arguments, it is restored. + Args + ``left``: distance from left edge of screen. + + ``top``: distance from top of screen. + + ``width``: width of the window. + + ``height``: height of the window. + """ + ... + + def RunCommand(self, command: str, *args: Any, **kwargs: Any) -> None: + """ + Runs a UNO command on the current window. Commands can be run with or without arguments. + Arguments are not validated before running the command. If the command or its arguments are invalid, + then nothing will happen. + Args + ``command``: case-sensitive string containing the UNO command name. + The inclusion of the prefix ".uno:" in the command is optional. + The command itself is not checked for correctness. + + ``args, kwargs``: use either pairs of ("name", value) positional arguments + or pairs of name = value keyword arguments. + """ + ... + + def SetStatusbar(self, text: str = ..., percentage: Union[int, float] = ...) -> None: + """ + Display a text and a progressbar in the status bar of the active window. + Any subsequent calls in the same macro run refer to the same status bar of the same window, + even if the window is not active anymore. + A call without arguments resets the status bar to its normal state. + Args + ``text``: the optional text to be displayed before the progress bar. Defaults to ''. + + ``percentage``: the optional degree of progress between 0 and 100. + """ + ... + def ShowProgressBar(self, title: str = ..., text: str = ..., percentage: Union[int, float] = ...) -> None: + """ + Display a non-modal dialog box. Specify its title, an explicatory text and the progress + on a progressbar. A call without arguments erases the progress bar dialog. + The box will anyway vanish at the end of the macro run. + Args + ``title``: the title appearing on top of the dialog box (Default = ``ScriptForge``). + + ``text``: the optional text to be displayed above the progress bar. Defaults to ''. + + ``percentage``: the degree of progress between 0 and 100. + """ + ... + + def WindowExists(self, windowname: str) -> bool: + """ + Returns ``True`` if the specified window exists. + Args + ``windowname``: see the definitions in ``SF_UI``. + Returns + ``True`` if the given window is found. + """ + ... + + +# ##################################################################################################################### +# SFDatabases CLASS (alias of SFDatabases Basic library) ### +# ##################################################################################################################### +class SFDatabases: + """ + The SFDatabases class manages databases embedded in or connected to Base documents. + The associated services include the ``Database``, ``Dataset`` and ``Datasheet`` services. + """ + + # ######################################################################### + # SF_Database CLASS + # ######################################################################### + class SF_Database(SFServices): + """ + Each instance of the current class represents a single database, stored in or connected + to a ``Base`` document, with essentially its tables, queries and data. + + The exchanges with the database are done in SQL only. + To make them more readable, use optionally square brackets to surround table/query/field names + instead of the (RDBMS-dependent) normal surrounding character. + + ``SQL`` statements may be run in direct or indirect modes. In direct mode the statement is transferred + literally without syntax checking nor review to the database engine. + """ + + Queries: Tuple[str, ...] + """ The list of stored queries. """ + Tables: Tuple[str, ...] + """ The list of stored tables. """ + XConnection: UNO + """ The ``UNO`` object representing the current connection (``com.sun.star.sdbc.XConnection``). """ + XMetaData: UNO + """ The ``UNO`` object representing the metadata describing the database system attributes + (``com.sun.star.sdbc.XDatabaseMetaData``). """ + + def CloseDatabase(self) -> None: + """ + Close the current database connection. + """ + ... + + def Commit(self) -> None: + """ + Commits all updates done since the previous ``Commit`` or ``Rollback`` call. + This method is ignored if commits are done automatically after each SQL statement, + i.e. the database is set to the default auto-commit mode. + """ + ... + + def CreateDataset(self, sqlcommand: SQL_SELECT, directsql: bool = ..., filter: str = ..., orderby: str = ... + ) -> Optional[DATASET]: + """ + Creates a Dataset service instance based on a table, query or ``SQL SELECT`` statement. + Args + ``sqlcommand``: a table name, a query name or a valid ``SQL SELECT`` statement. + Identifiers may be enclosed with square brackets. This argument is case-sensitive. + + ``directsql``: set this argument to ``True`` to send the statement directly to the database + engine without preprocessing by LibreOffice (Default = ``False``). + + ``filter``: specifies the condition that records must match to be included in the returned + dataset. This argument is expressed as a ``SQL WHERE`` statement without the ``WHERE`` keyword. + + ``orderby``: specifies the ordering of the dataset as a ``SQL ORDER BY`` statement + without the ``ORDER BY`` keyword. + Returns + A ``Dataset`` service instance. + """ + ... + + def DAvg(self, expression: str, tablename: str, criteria: str = ...) -> Optional[float, int]: + """ + Compute the aggregate function ``AVG()`` on a field or expression belonging to a table + filtered by a ``WHERE``-clause. + Args + ``expression``: an ``SQL`` expression. + + ``tablename``: the name of a table. + + ``criteria``: an optional ``WHERE`` clause without the word ``WHERE``. + Returns + int | float | None + """ + ... + + def DCount(self, expression: str, tablename: str, criteria: str = ...) -> Optional[int]: + """ + Compute the aggregate function ``COUNT()`` on a field or expression belonging to a table + filtered by a ``WHERE``-clause. + Args + ``expression``: an ``SQL`` expression. + + ``tablename``: the name of a table. + + ``criteria``: an optional ``WHERE`` clause without the word ``WHERE``. + Returns + int | float | None + """ + ... + + def DLookup(self, expression: str, tablename: str, criteria: str = ..., orderclause: str = ...) -> Any: + """ + Compute a ``SQL`` expression on a single record returned by a ``WHERE`` clause defined by the + ``criteria`` parameter. + + If the query returns multiple records, only the first one is considered. + Use the ``orderclause`` parameter to determine how query results are sorted. + Args + ``expression``: an ``SQL`` expression in which the field names are surrounded with + square brackets. + + ``tablename``: the name of a table (without square brackets). + + ``criteria``: an optional ``WHERE`` clause without the word ``WHERE``, in which field names + are surrounded with square brackets. + + ``orderclause``: an optional ``ORDER BY`` clause without the ``ORDER BY`` keywords. + Field names should be surrounded with square brackets. + Returns + The found value or None. + """ + ... + + def DMax(self, expression: str, tablename: str, criteria: str = ...) -> Optional[float, int]: + """ + Compute the aggregate function ``MAX()`` on a field or expression belonging to a table + filtered by a ``WHERE``-clause. + Args + ``expression``: an ``SQL`` expression. + + ``tablename``: the name of a table. + + ``criteria``: an optional ``WHERE`` clause without the word ``WHERE``. + Returns + int | float | None + """ + ... + + def DMin(self, expression: str, tablename: str, criteria: str = ...) -> Optional[float, int]: + """ + Compute the aggregate function ``MIN()`` on a field or expression belonging to a table + filtered by a ``WHERE``-clause. + Args + ``expression``: an ``SQL`` expression. + + ``tablename``: the name of a table. + + ``criteria``: an optional ``WHERE`` clause without the word ``WHERE``. + Returns + int | float | None + """ + ... + + def DSum(self, expression: str, tablename: str, criteria: str = ...) -> Optional[float, int]: + """ + Compute the aggregate function ``SUM()`` on a field or expression belonging to a table + filtered by a ``WHERE``-clause. + Args + ``expression``: an ``SQL`` expression. + + ``tablename``: the name of a table. + + ``criteria``: an optional ``WHERE`` clause without the word ``WHERE``. + Returns + int | float | None + """ + ... + + def GetRows(self, + sqlcommand: SQL_SELECT, + directsql: bool = ..., + header: bool = ..., + maxrows: int = ..., + ) -> MATRIX: + """ + Return the content of a table, a query or a ``SELECT SQL`` statement as a list of lists. + The first index corresponds to the individual records and the second index refers to the record fields. + Args + ``sqlcommand``: a table name, a query name or a ``SELECT SQL`` statement. + + ``directsql``: when ``True``, no syntax conversion is done by LibreOffice. + Ignored when ``sqlommand`` is a table or a query name. Defaults to ``False``. + + ``header``: when ``True``, a header row is inserted on the top of the list with the + column names. Defaults to ``False``. + + ``maxrows``: the maximum number of returned rows. If absent, all records are returned. + Returns + The returned list will be empty if no rows are returned and the column headers are not required. + """ + ... + + def OpenFormDocument(self, formdocument: str) -> Optional[FORMDOCUMENT]: + """ + Open the ``FormDocument`` given by its hierarchical name in normal mode. + If the form document is already open, the form document is made active. + Args + ``formdocument``: a valid form document name as a case-sensitive string. + When hierarchical, the hierarchy must be rendered with forward slashes ("/"). + Returns + A ``FormDocument`` instance or ``None``. + """ + ... + + def OpenQuery(self, queryname: str) -> Optional[DATASHEET]: + """ + Opens the Data View window of the specified query. + Args + ``queryname``: the name of an existing query as a case-sensitive string. + Returns + An instance of the ``Datasheet`` service. + If the query could not be opened, then ``None`` is returned. + """ + ... + + def OpenSql(self, sql: SQL_SELECT, directsql: bool = ...) -> Optional[DATASHEET]: + """ + Runs a ``SQL SELECT`` command, opens a Data View window with the results. + Args + sql: a string containing a valid ``SQL SELECT`` statement. + Identifiers may be enclosed by square brackets. + + directsql: when ``True``, the ``SQL`` command is sent to the database engine + without pre-analysis. Defaults to ``False``. + Returns + An instance of the ``Datasheet`` service. + If the query could not be opened, then ``None`` is returned. + """ + ... + + def OpenTable(self, tablename: str) -> Optional[DATASHEET]: + """ + Opens the Data View window of the specified table. + Args + ``tablename``: the name of an existing table as a case-sensitive string. + Returns + An instance of the ``Datasheet`` service. + If the table could not be opened, then ``None`` is returned. + """ + ... + + def Rollback(self) -> None: + """ + Cancels all updates made to the database since the previous ``Commit`` or ``Rollback`` call. + This method is ignored if commits are done automatically after each SQL statement, + i.e. if the database is set to the default auto-commit mode. + """ + ... + + def RunSql(self, sqlcommand: SQL_ACTION, directsql: bool = ...) -> bool: + """ + Execute an action query (table creation, record insertion, ...) or ``SQL`` statement on + the current database. + Args + ``sqlcommand``: a query name (without square brackets) or an ``SQL`` statement. + + ``directsql``: when ``True``, no syntax conversion is done by LibreOffice. + Ignored when ``sqlcommand`` is a query name. Defaults to ``False``. + Returns + ``True`` when the command ran successfully. + """ + ... + + def SetTransactionMode(self, transactionmode: Literal[0, 1, 2, 4, 8] = ...) -> bool: + """ + Defines the level of isolation in database transactions. + + By default, databases manage transactions in auto-commit mode, which means that a ``Commit()`` + is automatically performed after every SQL statement. + + Use this method to manually determine the isolation level of transactions. + When a transaction mode other than ``NONE (0)`` is set, the script has to explicitly + call the ``Commit()`` method to apply the changes to the database. + + Args + ``tranactionmode``: specifies the transaction mode. + This argument must be one of the constants defined in ``com.sun.star.sdbc.TransactionIsolation`` + (Default = ``NONE``) + Returns + ``True`` when successful. + """ + ... + + # ######################################################################### + # SF_Dataset CLASS + # ######################################################################### + class SF_Dataset(SFServices): + """ + A dataset represents a set of tabular data produced by a database. + + In the user interface of LibreOffice a dataset corresponds with the data + displayed in a form or a data sheet (table, query). + + To use datasets, the database instance must exist but the Base document may not be open. + + With this service it is possible to: + - Navigate through and access the data in a dataset. + - Update, insert and remove records in a dataset. + """ + + BOF: bool + """ Returns ``True`` if the current record position is before the first record in the dataset, + otherwise returns ``False``. Set this property to ``True`` to move the cursor to the beginning of the dataset. + Setting this property to ``False`` is ignored. """ + DefaultValues: Dict + """ Returns a ``dict`` with the default values used for each field in the dataset. + The fields or columns in the dataset are the keys in the dictionary. The database field types are converted + to their corresponding Python data types. When the field type is undefined, the default value is None. """ + EOF: bool + """ Returns ``True`` if the current record position is after the last record in the dataset, + otherwise returns ``False``. Set this property to ``True`` to move the cursor to the end of the dataset. + Setting this property to ``False`` is ignored. """ + Fields: Tuple[str, ...] + """ Returns a list containing the names of all fields in the dataset. """ + Filter: str + """ Returns the filter applied in addition to the eventual ``WHERE`` clause(s) in the initial ``SQL`` statement. + This property is expressed as a ``WHERE`` clause without the ``WHERE`` keyword. """ + OrderBy: str + """ Returns the ordering clause that replaces the eventual ``ORDER BY`` clause present in the initial + ``SQL`` statement. This property is expressed as a ``ORDER BY`` clause without the ``ORDER BY`` keywords. """ + ParentDatabase: DATABASE + """ Returns the ``Database`` instance corresponding to the parent database of the current dataset. """ + RowCount: int + """ Returns the exact number of records in the dataset. Note that the evaluation of this property + implies browsing the whole dataset, which may be costly depending on the dataset size. """ + RowNumber: int + """ Returns the number of the current record starting at 1. Returns 0 if this property is unknown. """ + Source: str + """ Returns the source of the dataset. It can be either a table name, a query name or a ``SQL`` statement. """ + SourceType: str + """ Returns the source of the dataset. It can be one of the following string values: + ``TABLE``, ``QUERY`` or ``SQL``. """ + UpdatableFields: List + """ Returns a ``list`` containing the names of all fields in the dataset that are updatable. """ + Values: Dict + """ Returns a ``dict`` containing the pairs (field name: value) of the current record in the dataset. """ + XRowSet: UNO + """ Returns the ``com.sun.star.sdb.RowSet`` ``UNO`` object representing the dataset. """ + + def CloseDataset(self) -> bool: + """ + Closes the current Dataset. + Returns + ``True`` when successful. + """ + ... + + def CreateDataset(self, filter:str = ..., orderby: str = ...) -> DATASET: + """ + Returns a ``Dataset`` service instance derived from the actual dataset by applying + the specified ``filter`` and ``orderby`` arguments. + Args + ``filter``: specifies the condition that records must match to be included in the + returned dataset. This argument is expressed as a ``SQL WHERE`` clause + without the ``WHERE`` keyword. If this argument is not specified, then the filter + used in the current dataset is applied, otherwise the current filter is replaced + by this argument. + + ``orderby``: specifies the ordering of the dataset as a ``SQL ORDER BY`` clause + without the ``ORDER BY`` keywords. If this argument is not specified, then + the sorting order used in the current dataset is applied, otherwise + the current sorting order is replaced by this argument. + Returns + A new ``Dataset`` service instance. + """ + ... + + def Delete(self) -> bool: + """ + Deletes the current record from the dataset. + + After this operation the cursor is positioned at the record immediately after the deleted record. + When the deleted record is the last in the dataset, then the cursor is positioned after it + and the property ``EOF`` returns ``True``. + Returns + ``True`` when successful. + """ + ... + + def ExportValueToFile(self, fieldname: str, filename: FILE, overwrite: bool = ...) -> bool: + """ + Exports the value of a binary field of the current record to the specified file. + If the specified field is not binary or if it contains no data, then the output file is not created. + Args + ``fieldname``: the name of the binary field to be exported, as a case-sensitive string. + + ``filename``: the complete path to the file to be created using the notation defined + in the ``FileSystem.FileNaming`` property. + + ``overwrite``: set this argument to ``True`` to allow the destination file + to be overwritten (Default = ``False``). + Returns + ``True`` when successful. + """ + ... + + def GetRows(self, header: bool = ..., maxrows: int = ...) -> Optional[MATRIX]: + """ + Return the content of the dataset as a list of lists. + The first index corresponds to the individual records and the second index refers to the record fields. + Args + ``header``: when ``True``, a header row is inserted on the top of the list with the + column names. Defaults to ``False``. + + ``maxrows``: the maximum number of returned rows. If absent, all records are returned. + Returns + The returned list will be empty if no rows are returned and the column headers are not required. + """ + ... + + def GetValue(self, fieldname: str) -> Any: + """ + Returns the value of the specified field from the current record of the dataset. + Args + ``fieldname``: the name of the field to be returned, as a case-sensitive string. + Returns + If the specified field is binary, then its length is returned. + """ + ... + + def Insert(self, *args, **kwargs: Dict) -> int: + """ + Inserts a new record at the end of the dataset and initialize its fields with the specified values. + Updatable fields with unspecified values are initialized with their default values. + Args + Next variants are allowed: + - ``newid = dataset.Insert({"Name": "John", "Age": 50, "City": "Chicago"})`` + - ``newid = dataset.Insert("Name", "John", "Age", 50, "City", "Chicago")`` + - ``newid = dataset.Insert(Name = "John", Age = 50, City = "Chicago")`` + Returns + If the primary key of the dataset is an ``auto value``, then this method returns + the primary key value of the new record. Otherwise, the method will return 0 (when successful) + or -1 (when not successful). + """ + ... + + def MoveFirst(self) -> bool: + """ + Moves the dataset cursor to the first record. Deleted records are ignored by this method. + Returns + ``True`` when successful. + """ + ... + + def MoveLast(self) -> bool: + """ + Moves the dataset cursor to the last record. Deleted records are ignored by this method. + Returns + ``True`` when successful. + """ + ... + + def MoveNext(self, offset: int = ...) -> bool: + """ + Moves the dataset cursor forward by a given number of records. + Deleted records are ignored by this method. + Args + ``offset``: the number of records by which the cursor shall be moved forward. + This argument may be a negative value (Default = +1). + Returns + ``True`` when successful. + """ + ... + + def MovePrevious(self, offset: int = 1) -> bool: + """ + Moves the dataset cursor backward by a given number of records. + Deleted records are ignored by this method. + Args + ``offset``: the number of records by which the cursor shall be moved backward. + This argument may be a negative value (Default = +1). + Returns + ``True`` when successful. + """ + ... + + def Reload(self, filter: str = ..., orderby: str = ...) -> bool: + """ + Reloads the dataset from the database. The properties ``Filter`` and ``OrderBy`` may be defined + when calling this method. + + Reloading the dataset is useful when records have been inserted to or deleted from the database. + Note that the methods ``CreateDataset`` and ``Reload`` perform similar functions, + however ``Reload`` reuses the same Dataset class instance. + Args + ``filter``: specifies the condition that records must match to be included in the + returned dataset. This argument is expressed as a ``SQL WHERE`` clause + without the ``WHERE`` keyword. If this argument is not specified, then the filter + used in the current dataset is applied, otherwise the current filter is replaced + by this argument. + + ``orderby``: specifies the ordering of the dataset as a ``SQL ORDER BY`` clause + without the ``ORDER BY`` keywords. If this argument is not specified, then + the sorting order used in the current dataset is applied, otherwise + the current sorting order is replaced by this argument. + Returns + ``True`` when successful. + """ + ... + + def Update(self, *args, **kwargs) -> bool: + """ + Updates the values of the specified fields in the current record. + Args + Next variants are allowed: + - ``newid = dataset.Update({"Age": 51, "City": "New York"})`` + - ``newid = dataset.Update("Age", 51, "City", "New York")`` + - ``newid = dataset.Update(Age = 51, City = "New York")`` + Returns + ``True`` when successful. + """ + ... + + # ######################################################################### + # SF_Datasheet CLASS + # ######################################################################### + class SF_Datasheet(SFServices): + """ + The Datasheet service allows to visualize the contents of database tables as well as the results + of queries and ``SQL`` statements using ``Base's Data View``. + + Additionally, this service allows to: + - add custom menus to the data view + - access values in specific positions of the data view + - position the cursor in a specific cell of the data view + + The ``Base`` document owning the data may or may not be opened. + """ + + ColumnHeaders: Tuple[str, ...] + """ Returns a list with the names of the column headers in the datasheet. """ + CurrentColumn: str + """ Returns the currently selected column name. """ + CurrentRow: int + """ Returns the number of the currently selected row, starting at 1. """ + DatabaseFileName: FILE + """ Returns the file name of the ``Base`` file in ``SF_FileSystem.FileNaming`` format. """ + Filter: str + """ Specifies a filter to be applied to the datasheet expressed as the ``WHERE`` clause of a ``SQL`` query + without the ``WHERE`` keyword. If an empty string is specified then the active Filter is removed. """ + LastRow: int + """ Returns the number of rows in the datasheet. """ + OrderBy: str + """ Specifies the order in which records are shown expressed as the ``ORDER BY`` clause of a ``SQL`` query + without the ``ORDER BY`` keyword. If an empty string is specified then the active ``OrderBy`` is removed. """ + ParentDatabase: DATABASE + """ Returns the ``Database`` instance corresponding to the parent database of the current datasheet. """ + Source: SQL_SELECT + """ Returns the source of the datasheet. It can be either a table name, a query name + or a ``SQL`` statement. """ + SourceType: str + """ Returns the type of the data source of the datasheet. It can be one of the following string values: + ``TABLE``, ``QUERY`` or ``SQL``. """ + + XComponent: UNO + """ Returns the ``com.sun.star.lang.XComponent`` ``UNO`` object representing the datasheet. """ + + XControlModel: UNO + """ Returns the ``com.sun.star.awt.XControl`` ``UNO`` object representing the datasheet. """ + + XTabControllerModel: UNO + """ Returns the ``com.sun.star.awt.XTabControllerModel `` ``UNO`` object representing the datasheet. """ + + def Activate(self) -> None: + """ + Brings to front the data view window referred to by the ``Datasheet`` instance. + """ + ... + + def CloseDatasheet(self) -> None: + """ + Closes the data view window referred to by the ``Datasheet`` instance. + """ + ... + + def CreateMenu(self, menuheader: str, before: Union[str, int] = ..., submenuchar: str = ...) -> object: + """ + Creates a new menu entry in the data view window and returns a ``SFWidgets.Menu`` service instance, + with which menu items can be programmatically added. + Args + ``menuheader``: the name of the new menu. + ``before``: this argument can be either the name of an existing menu entry before + which the new menu will be placed or a number expressing the position of the new menu. + If this argument is left blank the new menu is placed as the last entry. + + ``submenuchar``: the delimiter used in menu trees . Defaults to ``">"``. + Returns + A ``Menu`` service instance. + Note + Menus added using the ``CreateMenu`` method are lost as soon as the data view window is closed. + """ + ... + + def GetText(self, column: Union[str, int] = ...) -> str: + """ + Returns the text in a given column of the current row. + Args + ``column``: the name of the column as a string or the column position (starting at ``1``). + If a position greater than the number of columns is given, the last column is returned. + Note + This method does not change the position of the cursor in the data view window. + Returns + The column text. + """ + ... + + def GetValue(self, column: Union[str, int]) -> Optional[Union[str, int, float, datetime.datetime]]: + """ + Returns the value in a given column of the current row as a valid Python type. + Args + ``column``: the name of the column as a string or the column position (starting at ``1``). + If a position greater than the number of columns is given, the last column is returned. + Returns + The targeted column value. + Binary types are returned as a ``int`` value indicating the length of the binary field. + """ + ... + + def GoToCell(self, row: int = ..., column: Union[int, str] = ...) -> None: + """ + Moves the cursor to the specified row and column. + Args + ``row``: the row number as a numeric value starting at ``1``. + If the requested row exceeds the number of existing rows, the cursor is moved to the last row. + If this argument is not specified, then the row is not changed. + + ``column``: the name of the column as a string or the column position (starting at ``1``). + If the requested column exceeds the number of existing columns, the cursor is moved + to the last column. If this argument is not specified, then the column is not changed. + """ + ... + + def RemoveMenu(self, menuheader: str) -> bool: + """ + Removes a menu entry from the data view menubar by its name. + Args + ``menuheader``: the case-sensitive name of the menu to be removed. + The name must not include the tilde (``~``) character. + Returns + ``True`` when successful. + Note + This method can remove menus that belong to the standard user interface + as well as menus that were programmatically added with the CreateMenu method. + The removal of standard menus is not permanent, and they will reappear + after the window is closed and reopened. + """ + ... + + def Toolbars(self, toolbarname: str = ...) -> Union[TOOLBAR, Tuple[str, ...]]: + """ + Returns either a list of the available toolbar names in the actual datasheet or a ``Toolbar`` + service instance. + Args + ``toolbarname``: the usual name of one of the available toolbars. + Returns + A zero-based array of toolbar names when the argument is absent, + or a new ``Toolbar`` object instance from the ``SF_Widgets`` class. + """ + ... + +# ##################################################################################################################### +# SFDialogs CLASS (alias of SFDialogs Basic library) ### +# ##################################################################################################################### +class SFDialogs: + """ + Management of dialogs. They may be defined with the Basic IDE or built from scratch. + """ + + # ######################################################################### + # SF_Dialog CLASS + # ######################################################################### + class SF_Dialog(SFServices): + """ + The ``Dialog`` service contributes to the management of dialogs created with the Basic Dialog Editor + or dialogs created on-the-fly. Each instance of the ``Dialog`` class represents a single dialog box + displayed to the user. + + A dialog box can be displayed in modal or in non-modal modes. + + In modal mode, + the box is displayed and the execution of the macro process is suspended + until one of the ``OK`` or ``Cancel`` buttons is pressed. In the meantime, user actions executed + on the box can trigger specific actions. + + In non-modal mode, + the dialog box is "floating" on the user desktop and the execution + of the macro process continues normally. A non-modal dialog closes when it is terminated + with the Terminate() method or when the LibreOffice session ends. + The window close button is inactive in non-modal dialogs. + + A dialog box disappears from memory after its explicit termination. + """ + + OKBUTTON: Literal[1] + """ ``OK`` button has been pressed. """ + CANCELBUTTON: Literal[0] + """ ``Cancel`` button has been pressed. """ + + Caption: str + """ Specify the title of the dialog. """ + Height: int + """ Specify the height of the dialog. """ + Modal: bool + """ Specifies if the dialog box is currently in execution in modal mode. """ + Name: str + """ The name of the dialog. """ + Page: int + """ A dialog may have several pages that can be traversed by the user step by step. + The Page property of the Dialog object defines which page of the dialog is active. """ + Visible: bool + """ Specify if the dialog box is visible on the desktop. + By default it is not visible until the ``Execute()`` method is run and visible afterwards. """ + XDialogModel: UNO + """ The UNO representation (``com.sun.star.awt.XControlModel``) of the dialog model. """ + XDialogView: UNO + """ The UNO representation (``com.sun.star.awt.XControl``) of the dialog view. """ + Width: int + """ Specify the width of the dialog. """ + + OnFocusGained: SCRIPT_URI + """ Get/set the macro triggered by the ``When receiving focus`` event.""" + OnFocusLost: SCRIPT_URI + """ Get/set the macro triggered by the ``When losing focus`` event.""" + OnKeyPressed: SCRIPT_URI + """ Get/set the macro triggered by the ``Key pressed`` event.""" + OnKeyReleased: SCRIPT_URI + """ Get/set the macro triggered by the ``Key released`` event.""" + OnMouseDragged: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse moved while button pressed`` event.""" + OnMouseEntered: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse inside`` event.""" + OnMouseExited: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse outside`` event.""" + OnMouseMoved: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse moved`` event.""" + OnMousePressed: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse button pressed`` event.""" + OnMouseReleased: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse button released`` event.""" + + def Activate(self) -> bool: + """ + Set the focus on the current dialog instance. + Probably called from after an event occurrence or to focus on a non-modal dialog. + Returns + ``True`` if focusing is successful. + """ + ... + + def Center(self, parent: Union[DIALOG, BASE, DOCUMENT, CALC, WRITER, FORMDOCUMENT, DATASHEET] = ...) -> bool: + """ + Centres the current dialogue box instance in the middle of a parent window. + Without arguments, the method centres the dialogue box in the middle of the current window. + Args + ``parent``: an optional object that can be either, + - a ScriptForge dialog object, + - a ScriptForge document (Calc, Base, ...) object. + Returns + ``True`` when successful. + """ + ... + def CloneControl( + self, sourcename: str, controlname: str, left: int = ..., top: int = ...) -> Optional[DIALOGCONTROL]: + """ + Duplicate an existing control of any type in the actual dialog. + The duplicated control is left unchanged. The new control can be relocated. + Args + ``sourcename``: the name of the control to duplicate. + + ``controlname``: the name of the new control. It must not exist yet. + + ``left``: the left coordinate of the new control expressed in "``Map AppFont``" units. + + ``top``: the top coordinate of the new control expressed in "``Map AppFont``" units. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def Controls(self, controlname: str = ...) -> Union[DIALOGCONTROL, Tuple[str, ...]]: + """ + Returns the list of the controls contained in the dialog or a dialog control object based on its name. + Args + ``controlname``: a valid control name as a case-sensitive string. + If absent the list is returned. + Returns + The list of available control names as strings when ``controlname`` is absent. + Otherwise, if ``controlname`` exists, an instance of the ``SFDialogs.SF_DialogControl`` class. + """ + ... + + def CreateButton(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + toggle: bool = ..., + push: Literal["", "OK", "CANCEL"] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``Button`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``toggle``: when ``True`` a toggle button is created. Default = ``False``. + + ``push``: button type "OK", "CANCEL" or empty string (default). + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateCheckBox(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + multiline: bool = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``ComboBox`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``multiline``: when ``True`` the caption may be displayed on more than one line. + Default = ``False``. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateComboBox(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + dropdown: bool = ..., + linecount: int = ... + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``ComboBox`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``dropdown``: when ``True`` (default), a drop-down button is displayed. + + ``linecount``: the maximum line count displayed in the drop-down (default = 5). + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateCurrencyField(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + spinbutton: bool = ..., + minvalue: Union[int, float] = ..., + maxvalue: Union[int, float] = ..., + increment: int = ..., + accuracy: int = ... + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``CurrenyField`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``spinbutton``: when ``True`` a spin button is present. Default = ``False``. + + ``minvalue``: the smallest value that can be entered in the control. Default = -1000000. + + ``maxvalue``: the largest value that can be entered in the control. Default = +1000000. + + ``increment``: the step when the spin button is pressed. Default = 1. + + ``accuracy``: the decimal accuracy. Default = 2 decimal digits. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateDateField(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + dropdown: bool = ..., + mindate: datetime.datetime = ..., + maxdate: datetime.datetime = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``DateField`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``dropdown``: when ``True`` a dropdwn button is shown. Default = ``False``. + + ``mindate``: the smallest date that can be entered in the control. Default = 1900-01-01. + + ``maxdate``: the largest date that can be entered in the control. Default = 2200-12-31. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateFileControl(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``FileControl`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateFixedLine(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + orientation: Literal["H", "Horizontal", "V", "Vertical"], + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``FixedLine`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``orientation``: for horizontal orientation use "H" or "Horizontal", + for vertical orientation use "V" or "Vertical". + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateFixedText(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + multiline: bool = ..., + align: Literal["LEFT", "CENTER", "RIGHT"] = ..., + verticalalign: Literal["TOP", "MIDDLE", "BOTTOM"] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``FixedText`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: border kind, "3D" or "FLAT" or "NONE". Default is ``NONE``. + + ``multiline``: when ``True`` the caption may be displayed on more than one line. + Default ``False``. + + ``align``: horizontal alignment, "LEFT" (default) or "CENTER" or "RIGHT". + + ``verticalalign``: vertical alignment, "TOP" (default) or "MIDDLE" or "BOTTOM". + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateFormattedField(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + spinbutton: bool = ..., + minvalue: Union[int, float] = ..., + maxvalue: Union[int, float] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``FormattedField`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``spinbutton``: when ``True`` a spin button is present. Default = ``False``. + + ``minvalue``: the smallest value that can be entered in the control. Default = -1000000. + + ``maxvalue``: the largest value that can be entered in the control. Default = +1000000. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateGroupBox(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``GroupBox`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateHyperlink(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + multiline: bool = ..., + align: Literal["LEFT", "CENTER", "RIGHT"] = ..., + verticalalign: Literal["TOP", "MIDDLE", "BOTTOM"] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``Hyperlink`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: border kind, "3D" or "FLAT" or "NONE". Default is ``NONE``. + + ``multiline``: when ``True`` the caption may be displayed on more than one line. + Default ``False``. + + ``align``: horizontal alignment, "LEFT" (default) or "CENTER" or "RIGHT". + + ``verticalalign``: vertical alignment, "TOP" (default) or "MIDDLE" or "BOTTOM". + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateImageControl(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + scale: Literal["FITTOSIZE", "KEEPRATIO", "NO"] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``ImageControl`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: border kind, "3D" or "FLAT" or "NONE". Default is ``NONE``. + + ``scale``: one of next values, "FITTOSIZE" (default) or "KEEPRATIO" or "NO". + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateListBox(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + dropdown: bool = ..., + linecount: int = ..., + multiselect: bool = ... + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``ListBox`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``dropdown``: When ``True`` (default), a drop-down button is displayed. + + ``linecount``: the maximum line count displayed in the drop-down (default = 5). + + ``multiselect``: when ``True``, more than 1 entry may be selected. Default = ``False``. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateNumericField(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + spinbutton: bool = ..., + minvalue: Union[int, float] = ..., + maxvalue: Union[int, float] = ..., + increment: int = ..., + accuracy: int = ... + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``NumericField`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``spinbutton``: when ``True`` a spin button is present. Default = ``False``. + + ``minvalue``: the smallest value that can be entered in the control. Default = -1000000. + + ``maxvalue``: the largest value that can be entered in the control. Default = +1000000. + + ``increment``: the step when the spin button is pressed. Default = 1. + + ``accuracy``: the decimal accuracy. Default = 2 decimal digits. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreatePatternField(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + editmask: str = ..., + literalmask: str = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``PatternField`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``editmask``: a character code that determines what the user may enter. More info on + https://wiki.documentfoundation.org/Documentation/DevGuide/Graphical_User_Interfaces#Pattern_Field. + + ``literalmask``: contains the initial values that are displayed in the pattern field. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateProgressBar(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + minvalue: Union[int, float] = ..., + maxvalue: Union[int, float] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``ProgressBar`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``minvalue``: the smallest value that can be entered in the control. Default = 0. + + ``maxvalue``: the largest value that can be entered in the control. Default = 100. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateRadioButton(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + multiline: bool = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``RadioButton`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``multiline``: when ``True`` the caption may be displayed on more than one line. + Default is ``False``. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateScrollBar(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + orientation: Literal["H", "Horizontal", "V", "Vertical"], + border: Literal["3D", "FLAT", "NONE"] = ..., + minvalue: Union[int, float] = ..., + maxvalue: Union[int, float] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``ScrollBar`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``orientation``: for horizontal orientation use "H" or "Horizontal", + for vertical orientation use "V" or "Vertical". + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``minvalue``: the smallest value that can be entered in the control. Default = 0. + + ``maxvalue``: the largest value that can be entered in the control. Default = 100. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateTableControl(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + rowheaders: bool = ..., + columnheaders: bool = ..., + scrollbars: Literal["H", "Horizontal", "V", "Vertical", "B", "Both", "N", "None"] = ..., + gridlines: bool = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``TableControl`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``rowheaders``: when ``True`` (default), the row headers are shown. + + ``columnheaders``: when ``True`` (default), the column headers are shown. + + ``scrollbars``: H[orizontal] or V[ertical] or B[oth] or N[one] (default). + + ``gridlines``: when ``True`` horizontal and vertical lines are painted between the grid cells. + Default is ``False``. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateTextField(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + multiline: bool = ..., + maximumlength: int = ..., + passwordcharacter: str = ... + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``TextField`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: border kind, "3D" or "FLAT" or "NONE". Default is ``NONE``. + + ``multiline``: when ``True`` the caption may be displayed on more than one line. + Default ``False``. + + ``maximumlength``: the maximum character count (default = 0 meaning unlimited). + + ``passwordcharacter``: a single character specifying the echo for a password text field + (default = ""). + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateTimeField(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + mintime: datetime.datetime = ..., + maxtime: datetime.datetime = ... + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``TimeField`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + + ``mintome``: the smallest time that can be entered in the control. Default = 0h. + + ``maxtime``: the largest time that can be entered in the control. Default = 24h. + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def CreateTreeControl(self, + controlname: str, + place: Union[UNO, Tuple[int, int, int, int]], + border: Literal["3D", "FLAT", "NONE"] = ..., + ) -> Optional[DIALOGCONTROL]: + """ + Create a new control of type ``TreeControl`` in the actual dialog. + Args + ``controlname``: the name of the new control. It must not exist yet. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + + ``border``: "3D" (default), "FLAT" or "NONE". + Returns + A ``SFDialogs.SF_DialogControl`` instance or ``None``. + """ + ... + + def EndExecute(self, returnvalue: int) -> None: + """ + Ends the display of a modal dialog and gives back the argument + as return value for the current Execute() action. + + ``EndExecute()`` is usually contained in the processing of a macro + triggered by a dialog or control event. + Args + ``returnvalue``: The value passed to the running ``Execute()`` method. + """ + ... + + def Execute(self, modal: bool = ...) -> int: + """ + Display the dialog. In modal mode, the process is suspended until its closure by the user. + Args + ``modal``: ``False`` when non-modal dialog. Defaults to ``True``. + Returns + 0 = Cancel button pressed. 1 = OK button pressed. Otherwise: the dialog stopped + with an ``EndExecute()`` statement executed from a dialog or control event. + """ + ... + + def GetTextsFromL10N(self, l10n: L10N) -> bool: + """ + Replace all fixed text strings of a dialog by their localized version. + Replaced texts are: + - the title of the dialog + - the caption associated with next control types: ``Button, CheckBox, FixedLine, FixedText, GroupBox`` and ``RadioButton`` + - the content of list- and comboboxes + - the tip- or helptext displayed when the mouse is hovering a control. + The current method has a twin method ``ScriptForge.SF_L10N.AddTextsFromDialog``. + The current method is probably run before the ``Execute()`` method. + Args + ``l10n``: A "L10N" service instance created with CreateScriptService("L10N"). + Returns + ``True`` when successful. + """ + ... + + def OrderTabs(self, tabslist: Sequence[str], start: int = ..., increment: int = ...) -> bool: + """ + Set the tabulation index of a series of controls. + + The sequence of controls is given as a list or tuple of control names from the first to the last. + + Next controls will not be accessible (anymore ?) via the TAB key if >=1 of next conditions is met: + - if they are not in the given list + - if their type is ``FixedLine``, ``GroupBox`` or ``ProgressBar`` + - if the control is disabled + Args + ``tabslist``: a list or tuple of valid control names in the order of tabulation. + + ``start``: the tab index to be assigned to the 1st control in the list. Default is ``1``. + + ``increment``: the difference between ``2`` successive tab indexes. Default is ``1``. + Returns + ``True`` when successful. + """ + ... + + def Resize(self, left: int = ..., top: int = ..., width: int = ..., height: int = ...) -> bool: + """ + Moves the topleft corner of a dialog to new coordinates and/or modify its dimensions. + All distances are expressed in ``Map AppFont`` units. + Without arguments, the method resets the initial position and dimensions. + Args + ``left``: the horizontal distance from the top-left corner. + + ``top``: the vertical distance from the top-left corner. + + ``width``: the width of the rectangle containing the dialog. + + ``height``: the height of the rectangle containing the dialogue box. + Returns + ``True`` if the resize was successful. + """ + ... + + def SetPageManager(self, + pilotcontrols: str = ..., + tabcontrols: str = ..., + wizardcontrols: str = ..., + lastpage: int = ..., + ) -> bool: + """ + Defines which controls in a dialog are responsible for switching pages, making it easier + to orchestrate the ``Page`` property of a dialog and its controls. + + Dialogs may have multiple pages and the currently visible page is defined by the ``Page``dialog property. + If the ``Page`` property is left unchanged, the default visible page is equal to ``0`` (zero), meaning + that no particular page is defined and all visible controls are displayed regardless of the value set in + their own ``Page`` property. + + When the ``Page`` property of a dialog is changed to some other value such as ``1``, ``2``, ``3`` + and so forth, then only the controls whose ``Page`` property match the current dialog page will + be displayed. + + By using the SetPageManager method it is possible to define four types of page managers: + - List box or combo box: in this case, each entry in the list box or combo box corresponds to a page. The first item refers to Page 1, the second items refers to Page 2 and so on. + - Group of radio buttons: defines a group of radio buttons that will control which page is visible. + - Sequence of buttons: defines a set of buttons, each of which corresponding to a dialog page. This can be used to emulate a tabbed interface by placing buttons side by side in the dialog. + - Previous/Next buttons: defines which buttons in the dialog that will be used to navigate to the Previous/Next page in the dialog. + + This method is supposed to be called just once before calling the ``Execute()`` method. + Subsequent calls are ignored. + Args + ``pilotcontrols``: a comma-separated list of ``ListBox``, ``ComboBox`` or ``RadioButton`` + control names used as page managers. + For ``RadioButton`` controls, specify the name of the first control in the group to be used. + + ``tabcontrols``: a comma-separated list of button names that will be used as page managers. + The order in which they are specified in this argument corresponds to the page number + they are associated with. + + ``wizardcontrols``: a comma-separated list with the names of two buttons that will be used + s the ``Previous/Next`` buttons. + + ``lastpage``: the number of the last available page. + It is recommended to specify this value when using the ``Previous/Next`` page manager. + Returns + ``True`` on success. + Tip + It is possible to use more than one page management mechanism at the same time. + """ + ... + + def Terminate(self) -> bool: + """ + Terminate the dialog service for the current dialog instance. + After termination any action on the current instance will be ignored. + Returns + ``True`` if termination is successful. + """ + ... + + # ######################################################################### + # SF_DialogControl CLASS + # ######################################################################### + class SF_DialogControl(SFServices): + """ + Each instance of the current class represents a single control within a dialog box. + The focus is clearly set on getting and setting the values displayed by the controls of the dialog box, + not on their formatting. + A special attention is given to controls with type ``TreeControl``. + """ + + Border: Literal["3D", "FLAT", "NONE"] + """ Get the surrounding of the control. """ + Cancel: bool + """ Get/set whether a command button has or not the behaviour of a Cancel button. + Applicable to ``Button`` controls. """ + Caption: str + """ Get/set the text associated with the control. Applicable to ``Button, CheckBox, FixedLine, + FixedText, GroupBox, Hyperlink, RadioButton`` controls. """ + ControlType: str + """ get the type of control as a string. """ + CurrentNode: UNO + """ Get/set the currently upmost node selected in the tree control, as a + ``com.sun.star.awt.tree.XMutableTreeNode`` object. Applicable to ``TreeControl`` controls. """ + Default: bool + """ Get/set whether a command button is the default (OK) button. + Applicable to ``Button`` controls. """ + Enabled: bool + """ Specifies if the control is accessible with the cursor. """ + Format: Literal["Standard (short)", "Standard (short YY)", "Standard (short YYYY)", "Standard (long)", + "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY", "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD", + "24h short", "24h long", "12h short", "12h long"] + """ Get/set the format used to display dates and times. Applicable to ``DateField, TimeFiels, FormattedField`` + controls. """ + Height: int + """ Get/set the height of the control. """ + ListCount: int + """ Get the number of rows in the control. Applicable to ``ComboBox, ListBox, TableControl`` controls. """ + ListIndex: int + """ Get/set which item is selected in the control. Applicable to ``ComboBox, ListBox, TableControl`` + controls. """ + Locked: bool + """ Get/set if the control is read-only.. Applicable to ``ComboBox, CurrencyField, DateField, FileControl, + FormattedField, ListBox, NumericField, PatternField, TextField, TimeField`` controls. """ + MultiSelect: bool + """ Get/set whether a user can make multiple selections in a ``listbox``. """ + Name: str + """ The name of the control. """ + + OnActionPerformed: SCRIPT_URI + """ Get/set the macro triggered by the ``Execute action`` event. """ + OnAdjustmentValueChanged: SCRIPT_URI + """ Get/set the macro triggered by the ``While adjusting`` event. """ + OnFocusGained: SCRIPT_URI + """ Get/set the macro triggered by the ``When receiving focus`` event.""" + OnFocusLost: SCRIPT_URI + """ Get/set the macro triggered by the ``When losing focus`` event.""" + OnItemStatusChanged: SCRIPT_URI + """ Get/set the macro triggered by the ``Item status changed`` event. """ + OnKeyPressed: SCRIPT_URI + """ Get/set the macro triggered by the ``Key pressed`` event.""" + OnKeyReleased: SCRIPT_URI + """ Get/set the macro triggered by the ``Key released`` event.""" + OnMouseDragged: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse moved while button pressed`` event.""" + OnMouseEntered: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse inside`` event.""" + OnMouseExited: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse outside`` event.""" + OnMouseMoved: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse moved`` event.""" + OnMousePressed: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse button pressed`` event.""" + OnMouseReleased: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse button released`` event.""" + OnNodeExpanded: SCRIPT_URI + """ Get/set the macro triggered by the ``Expansion button is pressed on a node in a tree control`` event. """ + OnNodeSelected: SCRIPT_URI + """ Get/set the macro triggered by the ``Node in a tree control is selected`` event.""" + + Page: int + """ A dialog may have several pages that can be traversed by the user step by step. + The Page property of the Dialog object defines which page of the dialog is active. + The`` ``Page property of a control defines the page of the dialog on which the control is visible. """ + Parent: DIALOG + """ The parent ``DIALOG`` class object instance. """ + Picture: FILE + """ Get/se the file name (in ``FileSystem.FileNaming`` notation) containing a bitmap or other type of graphic + to be displayed on the specified control. """ + RootNode: UNO + """ Get the lowest root node (usually there is only one such root node), as a + ``com.sun.star.awt.tree.XMutableTreeNode`` object. Applicable to ``TreeControl`` controls. """ + RowSource: Sequence[str] + """ Get/set the data contained in a ``combobox`` or a ``listbox``. """ + TabIndex: int + """ Specifies a control's place in the tab order in the dialog. """ + Text: str + """ Get the text being displayed by the control. Applicable to ``ComboBox, FileControl, FormattedField, + PatternField, TextField`` controls. """ + TripleState: bool + """ Get/set whether the ``checkbox`` control may appear dimmed (grayed). """ + URL: str + """ Get/set the URL to open when clcking the ``hyperlink`` control. """ + Value: Any + """ + Get/set the content of the control: + + - ``Button``: bool - For toggle buttons only. + - ``CheckBox``: bool, int - 0, ``False``: not checked, 1, ``True``: checked, 2: grayed, don't know. + - ``ComboBox``: str - The selected value. The ``ListIndex`` property is an alternate option. + - ``CurrencyField``: int, float. + - ``DateField``: datetime.datetime. + - ``FileControl``: FILE. + - ``FormattedField``: str, int, float. + - ``ListBox``: List(str), str - The selected row(s) as a scalar or as an array depending on the ``MultiSelect`` attribute. + - ``NumericField``: int, float. + - ``PatternField``: str. + - ``ProgressBar``: int - Must be within the predefined bounds. + - ``RadioButton``: bool - Each button has its own name. They are linked together if their TAB positions are contiguous. If a radiobutton is set to ``True``, the other related buttons are automatically set to ``False``. + - ``ScrollBar``: int - Must be within the predefined bounds. + - ``TableControl``: List[Any] - The data of the currently selected row. + - ``TextField``: str - The text appearing in the control. + - ``TimeField``: datetime.datetime. + Not applicable to ``FixedLine, FixedText, GroupBox, Hyperlink, ImageControl`` and ``TreeControl`` dialog controls. + """ + Visible: bool + """ Get/set if the dialog control is hidden or visible. """ + Width: int + """ Get/set the width of the control. """ + X: int + """ X coordinate of the top-left corner of the control. """ + Y: int + """ Y coordinate of the top-left corner of the control. """ + + XControlModel: UNO + """ The UNO representation (``com.sun.star.awt.XControlModel``) of the control model. """ + XControlView: UNO + """ The UNO representation (``com.sun.star.awt.XControl``) of the control view. """ + XGridColumnModel: UNO + """ The UNO representation (``com.sun.star.awt.grid.XGridColumnModel``) of a ``tablecontrol`` column model. """ + XGridDataModel: UNO + """ The UNO representation (``com.sun.star.awt.grid.XGridDataModel``) of a ``tablecontrol`` data model. """ + XTreeDataModel: UNO + """ The UNO representation (``com.sun.star.awt.tree.MutableTreeDataModel``) of a ``treecontrol`` data model. """ + + def AddSubNode(self, + parentnode: XMutableTreeNode, + displayvalue: str, + datavalue: Any = ..., + ) -> XMutableTreeNode: + """ + Return a new node of the tree control subordinate to a parent node. + Args + ``parentnode``: a node UNO object, of type ``com.sun.star.awt.tree.XMutableTreeNode``. + + ``displayvalue``: the text appearing in the control box. + + ``datavalue``: any value associated with the new node. + Returns + The new node UNO object: ``com.sun.star.awt.tree.XMutableTreeNode``. + """ + ... + + def AddSubTree(self, + parentnode: XMutableTreeNode, + flattree: MATRIX, + withdatavalue: bool = ..., + ): + """ + Return ``True`` when a subtree, subordinate to a parent node, could be inserted successfully + in a tree control. If the parent node had already child nodes before calling this method, + the child nodes are erased. + Args + ``parentnode``: a node UNO object, of type ``com.sun.star.awt.tree.XMutableTreeNode``. + + ``flattree``: a list of lists sorted on the columns containing the ``DisplayValues``. + + ``withdatavalue``: when ``False`` (default), every column of ``FlatTree`` contains the + text to be displayed in the tree control. When ``True``, the texts to be displayed + (``DisplayValue``) are in columns 0, 2, 4, ... while the ``DataValues`` are in columns + 1, 3, 5, ... + Notes + Typically, such an array can be issued by the GetRows() method applied on + the ``SFDatabases.Database`` service. + """ + ... + + def CreateRoot(self, displayvalue: str, datavalue: Any = ...) -> XMutableTreeNode: + """ + Return a new root node of the tree control. + The new tree root is inserted below pre-existing root nodes. + Args + ``displayvalue``: the text appearing in the control box. + + ``datavalue``: any value associated with the root node. + Returns + The new root node as a UNO object of type ``com.sun.star.awt.tree.XMutableTreeNode``. + """ + ... + + def FindNode(self, + displayvalue: str = ..., + datavalue: Any = ..., + casesensitive: bool = ..., + ) -> Optional[XMutableTreeNode]: + """ + Traverses the tree and find recursively, starting from the root, a node meeting some criteria. + Either (1 match is enough) having its ``DisplayValue`` like ``displayValue`` or + having its ``DataValue`` = ``datavalue``. + + Comparisons may be or not case-sensitive. + + The first matching occurrence is returned. + Args + ``displayvalue``: the pattern to be matched. It may contain wildcards(? and *). + + ``datavalue``: a string, a numeric value or a date. + + ``casesensitive``: Defaults to ``False``. + Returns + The found node of type ``com.sun.star.awt.tree.XMutableTreeNode`` or ``None`` if not found. + """ + ... + + def Resize(self, left: int = ..., top: int = ..., width: int = ..., height: int = ...) -> bool: + """ + Move the top-left corner of the control to new coordinates and/or modify its dimensions. + Without arguments, the method resets the initial dimensions and position. + All distances are expressed in ``Map AppFont`` units and are measured from the top-left corner + of the parent dialog. + Args + ``left``: the horizontal distance from the top-left corner. It may be negative. + + ``top``: the vertical distance from the top-left corner. It may be negative. + + ``width``: the horizontal width of the rectangle containing the control. It must be positive. + + ``height``: the vertical height of the rectangle containing the control. It must be positive. + Returns + ``True`` when successful. + """ + ... + + def SetFocus(self) -> bool: + """ + Set the focus on the current Control instance. + Probably called from after an event occurrence. + Returns + ``True`` if focusing is successful. + """ + ... + + def SetTableData(self, + dataarray: MATRIX, + widths: Sequence[Union[int, float]] = ..., + alignments: str = ..., + rowheaderwidth: int = ..., + ) -> bool: + """ + Fill a table control with the given data. Preexisting data is erased. + + The Basic IDE allows to define if the control has a row and/or a column header. + When it is the case, the array in argument should contain those headers resp. in the first + column and/or in the first row. + + A column in the control shall be sortable when the data (headers excluded) in that column + is homogeneously filled either with numbers or with strings. + + Columns containing strings will by default be left-aligned, those with numbers will be right-aligned. + Args + ``dataarray``: the set of data to display in the table control, including optional + column/row headers. + + ``widths``: tuple or list containing the relative widths of each column. + In other words, widths = (1, 2) means that the second column is twice as wide as + the first one. If the number of values in the tuple is smaller than the number of + columns in the table, then the last value in the tuple is used to define the width + of the remaining columns. + + ``alignments``: the column's horizontal alignment as a string with length = number of columns. + Possible characters are: L(eft), C(enter), R(ight) or space (default behavior). + + ``rowheaderwidth``: width of the row header column expressed in ``Map AppFont`` units. + Defaults to ``10``. The argument is ignored when the table control has no row header. + Returns + ``True`` when successful. + """ + ... + + def WriteLine(self, line: str = ...) -> bool: + """ + Add a new line to a multiline ``TextField`` control. + Args + ``line``: the line to insert at the end of the text box. + A newline character will be inserted before the line, if relevant. Defaults to an empty line. + Returns + ``True`` if insertion is successful. + """ + ... + + +# ##################################################################################################################### +# SFDocuments CLASS (alias of SFDocuments Basic library) ### +# ##################################################################################################################### +class SFDocuments: + """ + The SFDocuments class gathers a number of classes, methods and properties making easy + managing and manipulating LibreOffice documents. + """ + + # ######################################################################### + # SF_Document CLASS + # ######################################################################### + class SF_Document(SFServices): + """ + The methods and properties are generic for all types of documents: they are combined in the + current SF_Document class + - saving, exporting, closing documents + - accessing their standard or custom properties + - styles and menubar management + + Specific properties and methods are implemented in the concerned subclass(es) SF_Calc, SF_Base, ... + """ + + CustomProperties: DICTIONARY + """ Returns a ``ScriptForge.Dictionary`` object instance. After update, can be passed again to the property + for updating the document. Individual items of the dictionary may be either strings, numbers, + ``datetime.datetime`` or ``com.sun.star.util.Duration`` items. + This property is not applicable to ``Base`` documents. """ + Description: str + """ Get/set the ``Description`` property of the document (also known as "``Comments``"). + This property is not applicable to ``Base`` documents. """ + DocumentProperties: DICTIONARY + """ Returns a ``ScriptForge.Dictionary`` object instance containing all the entries. Document statistics + are included. Note that they are specific to the type of document. As an example, a ``Calc`` document + includes a "``CellCount``" entry. Other documents do not. + This property is not applicable to ``Base`` documents. """ + DocumentType: str + """ String value with the document type (``Base``, ``Calc``, ``Writer``, etc) """ + ExportFilters: Tuple[str, ...] + """ Returns a tuple of strings with the export filter names applicable to the current document. + Filters used for both import/export are also returned. + This property is not applicable to ``Base`` documents. """ + FileSystem: FILE + """ Returns a string with the URL path to the root of the virtual file system of the document. + Use the ``FileSystem`` service to view its contents, as well as to create, open and read files stored in it. """ + ImportFilters: Tuple[str, ...] + """ Returns a tuple of strings with the import filter names applicable to the current document. + Filters used for both import/export are also returned. + This property is not applicable to ``Base`` documents. """ + IsBase: bool + """ ``True`` when type of document = ``Base``. """ + IsCalc: bool + """ ``True`` when type of document = ``Calc``. """ + IsDraw: bool + """ ``True`` when type of document = ``Draw``. """ + IsFormDocument: bool + """ ``True`` when type of document = ``FormDocument``. """ + IsImpress: bool + """ ``True`` when type of document = ``Impress``. """ + IsMath: bool + """ ``True`` when type of document = ``Math``. """ + IsWriter: bool + """ ``True`` when type of document = ``Writer``. """ + Keywords: str + """ Get/set the ``Keywords`` property of the document as a comma-seprated list of keywords. + This property is not applicable to ``Base`` documents. """ + Readonly: bool + """ ``True`` if the document is actually in read-only mode. + This property is not applicable to ``Base`` documents. """ + StyleFamilies: Tuple[str, ...] + """ Get the list of available style families. + This property is not applicable to ``Base`` documents. """ + Subject: str + """ Get/set the ``Subject`` property of the document. + This property is not applicable to ``Base`` documents. """ + Title: str + """ Get/set the ``Title`` property of the document. + This property is not applicable to ``Base`` documents. """ + + XComponent: UNO + """ A ``com.sun.star.lang.XComponent`` or ``com.sun.star.comp.dba.ODatabaseDocument`` UNO object representing + the document. """ + XDocumentSettings: UNO + """ A ``com.sun.star.XXX.DocumentSettings`` UNO object, where XXX is either ``sheet, text, drawing`` or + ``presentation``. This object gives access to the internal UNO properties that are specific + to the document's type. + This property is not applicable to ``Base`` documents. """ + + def Activate(self) -> bool: + """ + Make the current document active. + Returns + ``True`` if the document could be activated. + Otherwise, there is no change in the actual user interface. + """ + ... + + def CloseDocument(self, saveask: bool = ...) -> bool: + """ + Close the document. Does nothing if the document is already closed + regardless of how the document was closed, manually or by program. + Args + ``saveask``: if ``True`` (default), the user is invited to confirm or not the writing + of the changes on disk. No effect if the document was not modified. + Returns + ``False`` if the user declined to close. + """ + ... + + def CreateMenu(self, menuheader: str, before: Union[str, int] = ..., submenuchar: str = ... + ) -> MENU: + """ + Creates a new menu entry in the menubar of a given document window. + + The menu created is only available during the current LibreOffice session and is not saved neither + in the document nor in the global application settings. + Hence, closing the document window will make the menu disappear. + It will only reappear when the macro that creates the menu is executed again. + Args + ``menuheader``: the toplevel name of the new menu. + + ``before``: the name (as a string) or position (as an integer starting at 1) of + an existing menu before which the new menu will be placed. + If no value is defined for this argument, the menu will be created at the last position + in the menubar. + + ``submenuchar``: the delimiter used to create menu trees when calling + methods as ``AddItem()`` from the Menu service. The default value is ">". + Returns + A ``SFWidgets.SF_Menu`` class instance or ``None``. + """ + ... + + def DeleteStyles(self, family: str, styleslist: Union[str, Sequence[str]]) -> None: + """ + Suppresses a single style or a list of styles given by their names within a specific styles family. + Only user-defined styles may be deleted, built-in styles are ignored. + It applies to all document types except ``Base`` and ``FormDocument``. + Args + ``family``: one of the style families present in the actual document, as a case-sensitive + string. Valid family names can be retrieved using the ``StyleFamilies`` property. + + ``styleslist``: a single style name as a string or a list/tuple of style names. + The style names may be localized or not. The styles list is typically the output of the + execution of a ``Styles()`` method. + + """ + ... + + def Echo(self, echoon: bool = ..., hourglass: bool = ...) -> None: + """ + While a script is executed any display update resulting from that execution + is done immediately. + + For performance reasons it might be an advantage to differ the display updates + up to the end of the script. This is where pairs of Echo() methods to set and reset the removal of the + immediate updates may be beneficial. + + Optionally the actual mouse pointer can be modified to the image of an hourglass. + + Args + ``echoon``: when ``False``, the display updates are suspended. Default is ``True``. + + ``hourglass``: when ``True``, the mouse pointer is changed to an hourglass. Default is ``False``. + """ + ... + + def ExportAsPDF(self, + filename: FILE, + overwrite: bool = ..., + pages: str = ..., + password: str = ..., + watermark: str = ..., + ) -> bool: + """ + Store the document to the given file location in PDF format. + This method is not applicable to ``Base`` documents. + Args + ``filename``: identifies the file where to save. + It must follow the ``SF_FileSystem.FileNaming`` notation. + + ``overwrite``: ``True`` if the destination file may be overwritten. Defaults to ``False``. + + ``pages``: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". + + ``password``: password to open the document. + + ``watermark``: the text for a watermark to be drawn on every page of the exported PDF file. + Returns + ``False`` if the document could not be saved. + """ + ... + + def PrintOut(self, pages: str = ..., copies: int = ...) -> bool: + """ + Send the content of the document to the printer. + The printer might be defined previously by default, by the user or by the ``SetPrinter()`` method. + This method is not applicable to ``Base`` documents. + Args + ``pages``: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". + Default is all pages. + + ``copies``: the number of copies. Defaults to 1. + Returns + ``True`` when successful. + """ + ... + + def RemoveMenu(self, menuheader: str) -> bool: + """ + Removes a toplevel menu from the menubar of a given document window. + Args + ``menuheader``: the toplevel name of the menu to be removed. + Returns + ``True`` if the specified menu existed and could be removed. + Notes + This method can be used to remove any menu entry from the document window, including + default menus. However, none of these changes in the menubar are saved to the document + or to the application settings. To restore the menubar to the default settings, + simply close and reopen the document. + """ + ... + + def RunCommand(self, command: str, *args, **kwargs) -> None: + """ + Runs a UNO command on the document window associated with the service instance. + + The document itself does not need to be active to be able to run commands. + + Commands can be run with or without arguments. Arguments are not validated before running the command. + If the command or its arguments are invalid, then nothing will happen. + Args + ``command``: case-sensitive string containing the UNO command name. + The inclusion of the prefix ``.uno:`` in the command is optional. + The command itself is not checked for correctness. + + ``kwargs``: the command arguments as keyword arguments. + """ + ... + + def Save(self) -> bool: + """ + Store the document to the file location from which it was loaded. + The method is ignored if the document was not modified. + Returns + ``False`` if the document could not be saved. + """ + ... + + def SaveAs(self, + filename: FILE, + overwrite: bool = ..., + password: str = ..., + filtername: str = ..., + filteroptions: str = ..., + ) -> bool: + """ + Store the document to the given file location. + The new location becomes the new file name on which simple ``Save()`` method calls will be applied. + Args + ``filename``: identifies the file where to save. It must follow the ``SF_FileSystem.FileNaming`` + notation. + + ``overwrite``: ``True`` if the destination file may be overwritten. Defaults to ``False``. + + ``password``: a non-space string to protect the document. + + ``filtername``: the name of a filter that should be used for saving the document. + If present, the filter must exist. + + ``filteroptions``: a string of options associated with the filter. + Returns + ``False`` if the document could not be saved. + """ + ... + + def SaveCopyAs(self, + filename: FILE, + overwrite: bool = ..., + password: str = ..., + filtername: str = ..., + filteroptions: str = ..., + ) -> bool: + """ + Store the document to the given file location. + The actual location is unchanged + Args + ``filename``: identifies the file where to save. It must follow the ``SF_FileSystem.FileNaming`` + notation. + + ``overwrite``: ``True`` if the destination file may be overwritten. Defaults to ``False``. + + ``password``: a non-space string to protect the document. + + ``filtername``: the name of a filter that should be used for saving the document. + If present, the filter must exist. + + ``filteroptions``: a string of options associated with the filter. + Returns + ``False`` if the document could not be saved. + """ + ... + + def SetPrinter(self, + printer: str = ..., + orientation: Literal['PORTRAIT', 'LANDSCAPE'] = ..., + paperformat: Literal['A3', 'A4', 'A5', 'LETTER', 'LEGAL', 'TABLOID'] = ... + ) -> bool: + """ + Define the printer options for the document. + This method is not applicable to ``Base`` documents. + Args + ``printer``: the name of the printer queue where to print to. + When absent or space, the default printer is set. + + ``orientation``: either ``PORTRAIT`` or ``LANDSCAPE``. Left unchanged when absent. + + ``paperformat``: paper format. Left unchanged when absent. + Returns + ``True`` when successful. + """ + ... + + def Styles(self, + family: str, + namepattern: str = ..., + parentstyle: str = ..., + used: bool = ..., + userdefined: bool = ..., + category: Literal['TEXT', 'CHAPTER', 'LIST', 'INDEX', 'EXTRA', 'HTML'] = ..., + ) -> Tuple[str, ...]: + """ + Retrieves a list of styles matching an optional compound criteria, the returned list may be empty. + This method is not applicable to ``Base`` documents. + Args + ``family``: one of the style families present in the actual document, as a case-sensitive + string. Valid family names can be retrieved using the ``StyleFamilies`` property. + + ``namepattern``: a filter on the style names, as a case-sensitive string pattern. + The names include the internal and localized names. Admitted wildcards are "?" and "*". + + ``parentstyle``: when present, only the children of the given, localized or not, parent style + name are retained. + + ``used``: when ``True``, the style must be used in the document, when absent the argument + is ignored. + + ``userdefined``: when ``True``, the style must have been added by the user, either in the + document or its template, when absent, the argument is ignored. + + ``category``: a sub-category of the ``ParagraphStyles`` family. + Returns + A list of style names. + """ + ... + + def Toolbars(self, toolbarname: str = ...) -> Union[TOOLBAR, Tuple[str, ...]]: + """ + Returns either a list of the available toolbar names in the actual document + or a ``SFWidgets.SF_Toolbar`` object instance. + Args + ``toolbarname``: the optional usual name of one of the available toolbars. + Returns + A list of toolbar names when the argument is absent, or a new ``Toolbar`` object instance + from the ``SF_Widgets`` library. + """ + ... + + def XStyle(self, family: str, stylename: str) -> UNO: + """ + This method returns the UNO representation of a given style. + It is applicable to all document types except ``Base`` documents. + Args + ``family``: one of the style families present in the actual document, as a case-sensitive + string. Valid family names can be retrieved using ``StyleFamilies`` property. + + ``stylename``: one of the styles present in the given family, as a case-sensitive string. + The ``stylename`` argument may be localized or not. + Returns + A ``com.sun.star.style.XStyle`` UNO object or one of its descendants, + like ``com.sun.star.style.CellStyle`` or ``com.sun.star.style.ParagraphStyle``, etc. + ``None`` is returned when the ``stylename`` does not exist in the given ``family``. + """ + ... + + # ######################################################################### + # SF_Base CLASS + # ######################################################################### + class SF_Base(SF_Document, SFServices): + """ + The ``Base`` service provides a number of methods and properties to facilitate the management + and handling of ``LibreOffice Base`` documents. + + The ``Base`` service extends the ``Document`` service and provides additional methods that are + specific for ``Base`` documents, enabling users to: + - get access to the database contained in a ``Base`` document + - open form documents, tables and queries stored in a ``Base`` document + - check if a form document from a Base document is currently loaded + + """ + + def CloseFormDocument(self, formdocument: str) -> bool: + """ + Close the given form document. + Nothing happens if the form document is not open. + + The method is deprecated. Use the ``SF_FormDocument.CloseDocument()`` method instead. + + Args + ``formdocument``: a valid hierarchical form name as a case-sensitive string. + Returns + ``True`` if closure is successful. + """ + ... + + def FormDocuments(self) -> Tuple[str, ...]: + """ + Return the list of the form documents contained in the ``Base`` document. + Returns + A tuple of strings. Each entry is the full path name of a form document. + The path separator is the slash ("/"). + """ + ... + + def Forms(self, formdocument: str, form: Union[str, int] = ...) -> Union[FORM, Tuple[str, ...]]: + """ + Depending on the parameters provided this method will return: + - a tuple with the names of all the forms contained in a form document (if the ``form`` argument is absent) + - a ``SFDocuments.Form`` object representing the form specified in the ``form`` argument. + + The method is deprecated. Use the ``SF_FormDocument.Forms()`` method instead. + Args + ``formdocument``: the hierarchical name of an open form document. + + ``form``: the name or index number of the form stored in the form document. + If this argument is absent, the method will return a list with the names of all forms + available in the form document. + Returns + Either a tuple of strings. Each entry is a form name stored in the form document, + or a ``SFDocuments.Form`` class instance. + """ + ... + + def GetDatabase(self, user: str = ..., password: str = ...) -> Optional[DATABASE]: + """ + Returns a ``SFDatabases.Database`` class instance giving access + to the execution of SQL commands on the database defined and/or stored in + the actual ``Base`` document. + Args + ``user``, ``password``: the Login parameters as strings. + The default value for both parameters is the empty string. + Returns + A ``SFDatabases.SF_Database`` class instance or ``None`` + """ + ... + + def IsLoaded(self, formdocument: str) -> bool: + """ + Return ``True`` if the given form Ddcument is currently open. + Args + ``formdocument``: A valid hierarchical form document name as a case-sensitive string. + """ + ... + + def OpenFormDocument(self, formdocument: str, designmode: bool = ...) -> FORMDOCUMENT: + """ + Open the form document given by its hierarchical name either in normal or in design mode. + If the form document is already open, the form document is made active without changing its mode. + Args + ``formdocument``: a valid hierarchical form document name as a case-sensitive string. + + ``designmode``: when ``True`` the form document is opened in design mode. Defaults to ``False``. + Returns + The ``SFDocuments.SF_FormDocument`` class instance corresponding with the opened form document. + """ + ... + + def OpenQuery(self, queryname: str, designmode: bool = ...) -> DATASHEET: + """ + Opens the Data View window of the specified query and returns an instance of the + ``SFDatabases.SF_Datasheet`` service. + + The query can be opened in normal or design mode. + + If the query is already open, its Data View window will be made active. + Args + ``queryname``: the name of an existing SELECT query as a case-sensitive String. + + ``designmode``: when ``True``, the query is opened in design mode. + Otherwise, it is opened in normal mode (default). + Returns + the ``SFDatabases.SF_Datasheet`` service instance corresponding with the query. + Note + Closing the Base document will cause the Data View window to be closed as well. + """ + ... + + def OpenTable(self, tablename: str, designmode: bool = ...) -> DATASHEET: + """ + Opens the Data View window of the specified table and returns an instance of the + ``SFDatabases.SF_Datasheet`` service. + + The table can be opened in normal or design mode. + + If the table is already open, its Data View window will be made active. + Args + ``tablename``: the name of an existing table or view as a case-sensitive String. + + ``designmode``: when ``True``, the table is opened in design mode. + Otherwise, it is opened in normal mode (default). + Returns + the ``SFDatabases.SF_Datasheet`` service instance corresponding with the table. + Note + Closing the Base document will cause the Data View window to be closed as well. + """ + ... + + # pylint: disable=arguments-renamed + def PrintOut(self, formdocument: str, pages: str = ..., copies: int = ...) -> bool: + """ + Send the content of the form document to the printer. + The printer might be defined previously by default, by the user or by the ``SetPrinter()`` method. + + The method is deprecated. Use the ``SF_FormDocument.PrintOut()`` method instead. + + Args + ``formdocument``: a valid form document name as a case-sensitive string. + The form document must be open. It is activated by the method. + + ``pages``: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". + Default is all pages. + + ``copies``: the number of copies. Defaults to 1. + Returns + ``True`` when successful. + """ + ... + + def SetPrinter(self, + formdocument: str = ..., + printer: str = ..., + orientation: Literal['PORTRAIT', 'LANDSCAPE'] = ..., + paperformat: Literal['A3', 'A4', 'A5', 'LETTER', 'LEGAL', 'TABLOID'] = ... + ) -> bool: + """ + Define the printer options for the form document. + + The method is deprecated. Use the ``SF_FormDocument.SetPrinter()`` method instead. + + Args + ``formdocument``: a valid form document name as a case-sensitive string. + + ``printer``: the name of the printer queue where to print to. + When absent or space, the default printer is set. + + ``orientation``: either ``PORTRAIT`` or ``LANDSCAPE``. Left unchanged when absent. + + ``paperformat``: paper format. Left unchanged when absent. + Returns + ``True`` when successful. + """ + ... + + # ######################################################################### + # SF_Calc CLASS + # ######################################################################### + class SF_Calc(SF_Document, SFServices): + """ + The ``SF_Calc`` class is focused on : + - management (copy, insert, move, ...) of sheets within a ``Calc`` document + - exchange of data between Python data structures and ``Calc`` ranges of values + - copying and importing massive amounts of data + + All methods and properties defined for the ``Document`` service can also be accessed using a ``Calc`` + service instance. + """ + + CurrentSelection: Union[RANGE, Tuple[RANGE, ...]] + """ Get/set the single selected range as a string or the list of selected ranges as a tuple of strings. """ + + def FirstCell(self, rangename: RANGE) -> RANGE: + """ + Returns the First used cell in a given range or sheet. When the argument is a sheet it will always + return the "sheet.$A$1" cell. """ + ... + def FirstColumn(self, rangename: RANGE) -> int: + """ Returns the leftmost column number in a given range. """ + ... + def FirstRow(self, rangename: RANGE) -> int: + """ Returns the First used column in a given range. """ + ... + def Height(self, rangename: RANGE) -> int: + """ Returns the height in # of rows of the given range. """ + ... + def LastCell(self, rangename: RANGE) -> RANGE: + """ Returns the last used cell in a given sheet or range. """ + ... + def LastColumn(self, rangename: RANGE) -> int: + """ Returns the last used column in a given range or sheet. """ + ... + def LastRow(self, rangename: RANGE) -> int: + """ The last used row in a given range or sheet. """ + ... + def Range(self, rangename: RANGE) -> CALCREFERENCE: + """ Returns a (internal) range object """ + ... + def Region(self, rangename: RANGE) -> RANGE: + """ + Returns the address of the smallest area that contains the specified range + so that the area is surrounded by empty cells or sheet edges. + This is equivalent to applying the ``Ctrl + *`` shortcut to the given range. + """ + ... + def Sheet(self, sheetname: SHEETNAME) -> CALCREFERENCE: + """ + Returns a sheet reference that can be used as argument of methods like ``CopySheet()``. """ + ... + def SheetName(self, rangename: RANGE) -> str: + """ Returns the sheet name part of a range address. """ + ... + def Width(self, rangename: RANGE) -> int: + """ The number of columns (>= 1) in the given range. """ + ... + def XCellRange(self, rangename: RANGE) -> XCellRange: + """ A ``com.sun.star.Table.XCellRange`` UNO object. """ + ... + def XSheetCellCursor(self, rangename: str) -> XSheetCellCursor: + """ A ``com.sun.star.sheet.XSheetCellCursor`` UNO object. """ + ... + def XSpreadsheet(self, sheetname: SHEETNAME) -> XSpreadsheet: + """ A ``com.sun.star.sheet.XSpreadsheet`` UNO object. """ + ... + + def A1Style(self, row1: int, column1: int, row2: int = ..., column2: int = ..., sheetname: SHEETNAME = ..., + ) -> RANGE: + """ + Returns a range address as a string based on sheet coordinates, i.e. row and column numbers. + + If only a pair of coordinates is given, then an address to a single cell is returned. + Additional arguments can specify the bottom-right cell of a rectangular range. + + Row and column numbers start at 1. + + Args + ``row1``: specify the row number of the top cell in the range to be considered. + + ``column1``: specify the column number of the left cell in the range to be considered. + + ``row2``: specify the row number of the bottom cell in the range to be considered. + If this argument is not provided, or if ``row2 < row1``, + then the address of the single cell range represented by ``row1`` and ``column1`` is returned. + + ``column2``: specify the column number of the right cell in the range to be considered. + If these arguments are not provided, or if ``column2 < rcolumn1``, + then the address of the single cell range represented by ``row1`` and ``column1`` is returned. + + ``sheetname``: the name of the sheet to be prepended to the returned range address. + The sheet must exist. The default value is ``"~"`` corresponding to the currently active sheet. + Returns + A range address as a string. + """ + ... + + def Activate(self, sheetname: SHEETNAME = ...) -> bool: + """ + If the argument ``sheetname`` is provided, the given sheet is activated and becomes the currently + selected sheet. If the argument is absent, then the document window is activated. + Args + ``sheetname``: the name of the sheet to be activated in the document. + Returns + ``True`` if the document or the sheet could be made active. Otherwise, there is no change + in the actual user interface. + """ + ... + + def Charts(self, sheetname: SHEETNAME, chartname: str = ...) -> Union[Tuple[str, ...], CHART]: + """ + Returns either the list with the names of all chart objects in a given sheet + or a single Chart service instance. + - If only ``sheetname`` is specified, a tuple containing the names of all charts is returned. + - If a ``chartname`` is provided, then a single object corresponding to the desired chart is returned. The specified chart must exist. + + Args + ``sheetname``: the name of the sheet from which the list of charts + is to be retrieved or where the specified chart is located. + + ``chartname``: the user-defined name of the chart object to be returned. + If the chart does not have a user-defined name, then the internal object name can be used. + If this argument is absent, then the list of chart names in the specified sheet is returned. + Returns + Either the list with the names of all chart objects in a given sheet or a + single ``Chart`` service instance. + """ + ... + + def ClearAll(self, + range: RANGE, + filterformula: str = ..., + filterscope: Literal['CELL', 'ROW', 'COLUMN'] = ..., + ) -> None: + """ + Clears all the contents and formats of the given range. + A filter formula can be specified to determine which cells shall be affected. + Args + ``range``: the range to be cleared, as a string. + + ``filterformula``: a ``Calc`` formula that shall be applied to the given range + to determine which cells will be affected. The specified formula must return ``True`` + or ``False``. If this argument is not specified, then all cells in the range are affected. + Express the formula in terms of (examples assume a range = ``"A1:J10"``): + - the top-left cell of the range when ``filterscope`` = "CELL" e.g. ``"=(A1>100)"`` + - the topmost row of the range when ``filterscope`` = "ROW" e.g. ``"=(SUM($A1:$J1)<1000)"`` + - the leftmost column of the range when ``filterscope`` = "COLUMN" e.g. ``"=(A$10=SUM(A$1:A$9))"`` + + ``filterscope``: determines how ``filterformula`` is expanded to the given range. + The argument is mandatory if a ``filterformula`` is specified. + """ + ... + + def ClearFormats(self, + range: RANGE, + filterformula: str = ..., + filterscope: Literal['CELL', 'ROW', 'COLUMN'] = ..., + ) -> None: + """ + Clears the formats of the given range. + A filter formula can be specified to determine which cells shall be affected. + Args + ``range``: the range to be cleared, as a string. + + ``filterformula``: a ``Calc`` formula that shall be applied to the given range + to determine which cells will be affected. The specified formula must return ``True`` + or ``False``. If this argument is not specified, then all cells in the range are affected. + Express the formula in terms of (examples assume a range = ``"A1:J10"``): + - the top-left cell of the range when ``filterscope`` = "CELL" e.g. ``"=(A1>100)"`` + - the topmost row of the range when ``filterscope`` = "ROW" e.g. ``"=(SUM($A1:$J1)<1000)"`` + - the leftmost column of the range when ``filterscope`` = "COLUMN" e.g. ``"=(A$10=SUM(A$1:A$9))"`` + + ``filterscope``: determines how ``filterformula`` is expanded to the given range. + The argument is mandatory if a ``filterformula`` is specified. + """ + ... + + def ClearValues(self, + range: RANGE, + filterformula: str = ..., + filterscope: Literal['CELL', 'ROW', 'COLUMN'] = ..., + ) -> None: + """ + Clears the values and formulas in the given range. + A filter formula can be specified to determine which cells shall be affected. + Args + ``range``: the range to be cleared, as a string. + + ``filterformula``: a ``Calc`` formula that shall be applied to the given range + to determine which cells will be affected. The specified formula must return ``True`` + or ``False``. If this argument is not specified, then all cells in the range are affected. + Express the formula in terms of (examples assume a range = ``"A1:J10"``): + - the top-left cell of the range when ``filterscope`` = "CELL" e.g. ``"=(A1>100)"`` + - the topmost row of the range when ``filterscope`` = "ROW" e.g. ``"=(SUM($A1:$J1)<1000)"`` + - the leftmost column of the range when ``filterscope`` = "COLUMN" e.g. ``"=(A$10=SUM(A$1:A$9))"`` + + ``filterscope``: determines how ``filterformula`` is expanded to the given range. + The argument is mandatory if a ``filterformula`` is specified. + """ + ... + def CompactLeft(self, range: RANGE, wholecolumn: bool = ..., filterformula: str = ...) -> RANGE: + """ + Deletes the columns of a specified range that match a filter expressed as a ``Calc`` formula. + The filter is applied to each column to decide whether it will be deleted or not. + + The deleted column can be limited to the height of the specified range or span to the + height of the entire sheet, thus deleting whole columns. + Args + ``range``: the range from which columns will be deleted, as a string. + + ``wholecolumn``: if this option is set to ``True`` the entire column will be deleted + from the sheet. The default value is ``False``, which means that the deleted column + will be limited to the height of the specified range. + + ``filterformula``: the filter to be applied to each column to determine whether it will + be deleted. The filter is expressed as a ``Calc`` formula that should be applied + to the first column. When the formula returns ``True`` for a column, that column will be + deleted. The default filter deletes all empty columns. + For example, suppose range ``"A1:J200"`` is selected (height = 200), so the default formula + is ``"=(COUNTBLANK(A1:A200)=200)"``. This means that if all 200 cells are empty in the first + column (Column A), then the column is deleted. + Returns + String with the range address of the compacted range. + If all columns are deleted, then an empty string is returned. + """ + ... + + def CompactUp(self, + range: RANGE, + wholerow: bool = ..., + filterformula: str = ... + ) -> RANGE: + """ + Deletes the rows of a specified range that match a filter expressed as a ``Calc`` formula. + The filter is applied to each row to decide whether it will be deleted or not. + + The deleted row can be limited to the width of the specified range or span to the + width of the entire sheet, thus deleting whole rows. + Args + ``range``: the range from which rows will be deleted, as a string. + + ``wholerow``: if this option is set to ``True`` the entire row will be deleted + from the sheet. The default value is ``False``, which means that the deleted row + will be limited to the width of the specified range. + + ``filterformula``: the filter to be applied to each row to determine whether it will + be deleted. The filter is expressed as a ``Calc`` formula that should be applied + to the first row. When the formula returns ``True`` for a row, that row will be + deleted. The default filter deletes all empty rows. + For example, suppose range ``"A1:J200"`` is selected (width = 10), so the default formula + is ``"=(COUNTBLANK(A1:J1)=10)"``. This means that if all 10 cells are empty in the first + row (Row 1), then the row is deleted. + Returns + String with the range address of the compacted range. + If all rows are deleted, then an empty string is returned. + """ + ... + + def CopySheet(self, + sheetname: Union[SHEETNAME, CALCREFERENCE], + newname: SHEETNAME, + beforesheet: Union[int, SHEETNAME]) -> bool: + """ + Copies a specified sheet before an existing sheet or at the end of the list of sheets. + The sheet to be copied may be contained inside any open ``Calc`` document. + Args + ``sheetname``: the name of the sheet to be copied as a string, + or a reference to a sheet as a ``CALCREFERENCE`` class instance. + A ``CALCREFERENCE`` is produced by the ``Sheet`` property of the ``Calc`` class. + + ``newname``: the name of the sheet to insert. The name must not be in use in the document. + + ``beforesheet``: the name (string) or index (numeric, starting from 1) of the sheet + before which to insert the copied sheet. The default behavior is to add the copied sheet + at the last position. + Returns + ``True`` if the sheet could be copied successfully. + """ + ... + + def CopySheetFromFile(self, + filename: FILE, + sheetname: SHEETNAME, + newname: SHEETNAME, + beforesheet: Union[int, SHEETNAME] = ..., + ) -> bool: + """ + Copies a specified sheet from a closed Calc document and pastes it before an existing + sheet or at the end of the list of sheets. + + If the file does not exist, an error is raised. If the file is not a valid ``Calc`` file, + a blank sheet is inserted. If the source sheet does not exist in the input file, + an error message is inserted at the top of the newly pasted sheet. + Args + ``filename``: identifies the source file. It must follow the ``SF_FileSystem.FileNaming`` + notation. The file must not be protected with a password. + + ``sheetname``: the name of the sheet to be copied as a string. + + ``newname``: the name of the copied sheet to be inserted in the document. + The name must not be in use in the document. + + ``beforesheet``: the name (string) or index (numeric, starting from 1) + of the sheet before which to insert the copied sheet. + The default behavior is to add the copied sheet at the last position. + Returns + ``True`` if the sheet could be created. + """ + ... + + def CopyToCell(self, + sourcerange: Union[RANGE, CALCREFERENCE], + destinationcell: RANGE + ) -> RANGE: + """ + Copies a specified source range (values, formulas and formats) to a destination range or cell. + The method reproduces the behavior of a Copy/Paste operation from a range to a single cell. + + The source range may belong to another open ``Calc`` document. + + Args + ``sourcerange``: the source range as a string when it belongs to the same document + or as a reference when it belongs to another open ``Calc`` document. + + ``destinationcell``: the destination cell where the copied range of cells will be pasted, + as a string. If a range is given, only its top-left cell is considered. + Returns + A string representing the modified range of cells. + The modified area depends on the size of the source area. + """ + ... + + def CopyToRange(self, + sourcerange: Union[RANGE, CALCREFERENCE], + destinationrange: RANGE + ) -> RANGE: + """ + Copies downwards and/or rightwards a specified source range (values, formulas and formats) + to a destination range. The method imitates the behavior of a Copy/Paste operation from + a source range to a larger destination range. + + - If the height (or width) of the destination area is > 1 row (or column) then the height (or width) of the source must be <= the height (or width) of the destination. Otherwise, nothing happens. + - If the height (or width) of the destination is = 1 then the destination is expanded downwards (or rightwards) up to the height (or width) of the source range. + + The source range may belong to another open ``Calc`` document. + + Args + ``sourcerange``: the source range as a string when it belongs to the same document + or as a reference when it belongs to another open ``Calc`` document. + + ``destinationrange``: the destination of the copied range of cells, as a string. + Returns + A string representing the modified range of cells. + """ + ... + + def CreateChart(self, + chartname: str, + sheetname: SHEETNAME, + range: RANGE, + columnheader: bool = ..., + rowheader: bool = ..., + ) -> CHART: + """ + Creates a new chart object showing the data in the specified range. + The returned chart object can be further manipulated using the ``Chart service``. + Args + ``chartname``: the user-defined name of the chart to be created. + The name must be unique in the same sheet. + + ``sheetname``: the name of the sheet where the chart will be placed. + + ``range``: the range to be used as the data source for the chart. The range may refer to + any sheet of the ``Calc`` document. + + ``columnheader``: when ``True``, the topmost row of the range is used as labels + for the category axis or the legend. Defaults to ``False``. + + ``rowheader``: when ``True``, the leftmost column of the range is used as labels + for the category axis or the legend. Defaults to ``False``. + Returns + A new chart service instance. + """ + ... + + def CreatePivotTable(self, + pivottablename: str, + sourcerange: RANGE, + targetcell: RANGE, + datafields: Union[Sequence[str], str] = ..., + rowfields: Union[Sequence[str], str] = ..., + columnfields: Union[Sequence[str], str] = ..., + filterbutton: bool = ..., + rowtotals: bool = ..., + columntotals: bool = ..., + ) -> RANGE: + """ + Creates a new pivot table with the properties defined by the arguments passed to the method. + + A name must be provided for the pivot table. + If a pivot table with the same name already exists in the targeted sheet, + it will be replaced without warning. + + Args + ``pivottablename``: the user-defined name of the new pivot table. + + ``sourcerange``: the range containing the raw data, as a string. + It is assumed that the first row contains the field names that are used by the pivot table. + + ``targetcell``: the top-left cell where the new pivot table will be placed. + If a range is specified, only its top-left cell is considered. + + ``datafields``: it can be either a single string or a list of strings + that define field names and functions to be applied. + When a list is specified, it must follow the syntax ["FieldName[;Function]", ...]. + The allowed functions are: ``Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP`` and ``Median``. + Function names must be provided in English. + When all values are numerical, ``Sum`` is the default function, otherwise + the default function is ``Count``. + + ``rowfields``: a single string or a list with the field names that will be used as the pivot + table rows. + + ``columnfields``: a single string or a list with the field names that will be used + as the pivot table columns. + + ``filterbutton``: determines whether a filter button will be displayed above the pivot + table (Default = ``True``). + + ``rowtotals``: specifies if a separate column for row totals will be added to the pivot + table (Default = ``True``). + + ``columntotals``: specifies if a separate row for column totals will be added to the pivot + table (Default = ``True``) + Returns + A string containing the range where the new pivot table was placed. + """ + ... + + def DAvg(self, range: RANGE) -> float: + """ + Get the number of the numeric values stored in the given range, excluding values from filtered + and hidden rows and hidden columns, the same as for the status bar functions. + Args + ``range``: the range as a string where to get the values from. + """ + ... + + def DCount(self, range: RANGE) -> int: + """ + Get the number of numeric values stored in the given range, excluding values from filtered + and hidden rows and hidden columns, the same as for the status bar functions. + Args + ``range``: the range as a string where to get the values from. + """ + ... + + def DMax(self, range: RANGE) -> float: + """ + Get the greatest of the numeric values stored in the given range, excluding values from filtered + and hidden rows and hidden columns, the same as for the status bar functions. + Args + ``range``: the range as a string where to get the values from. + """ + ... + + def DMin(self, range: RANGE) -> float: + """ + Get the smallest of the numeric values stored in the given range, excluding values from filtered + and hidden rows and hidden columns, the same as for the status bar functions. + Args + ``range``: the range as a string where to get the values from. + """ + ... + + def DSum(self, range: RANGE) -> float: + """ + Get the sum of the numeric values stored in the given range, excluding values from filtered + and hidden rows and hidden columns, the same as for the status bar functions. + Args + ``range``: the range as a string where to get the values from. + """ + ... + + def ExportRangeToFile(self, + range: RANGE, + filename: FILE, + imagetype: Literal['pdf', 'jpeg', 'png'] = ..., + overwrite: bool = ..., + ) -> bool: + """ + Exports the specified range as an image or PDF file. + Args + ``range``: a sheet name or a cell range to be exported, as a string. + + ``filename``: the name of the file to be saved. It must follow the + ``SF_FileSystem. FileNaming`` notation. + + ``imagetype``: identifies the destination file type. Possible values are ``jpeg, pdf`` + and ``png``. Defaults to ``pdf``. + + ``overwrite``: when set to ``True``, the destination file may be overwritten. + Defaults to ``False``. + Returns + ``True`` if the destination file was successfully saved. + """ + ... + + def Forms(self, sheetname: SHEETNAME, form: Union[int, str] = ...) -> Union[FORM, Tuple[str, ...]]: + """ + Depending on the parameters provided this method will return: + + - A tuple with the names of all the forms contained in a given sheet (if the form argument is absent) + - A ``SFDocuments.Form`` service instance representing the form specified as argument. + + Args + ``sheetname``: the name of the sheet, as a string, from which the form will be retrieved. + + ``form``: the name or index corresponding to a form stored in the specified sheet. + If this argument is absent, the method will return a list with the names of all forms available + in the sheet. + """ + ... + + def GetColumnName(self, columnnumber: int) -> str: + """ + Converts a column number ranging between 1 and 16384 into its corresponding + letter (column 'A', 'B', ..., 'XFD'). If the given column number is outside + the allowed range, a zero-length string is returned. + Args + ``columnnumber``: the column number as an integer value in the interval 1 ... 16384. + """ + ... + + def GetFormula(self, range: RANGE) -> Union[str, Tuple[str, ...], Tuple[Tuple[str, ...]], ...]: + """ + Get the formula(s) stored in the given range of cells as a single string, a tuple of strings, + or a tuple of tuples of strings. + Args + ``range``: the range where to get the formulas from, as a string. + Returns + The names of ``Calc`` functions used in the returned formulas are expressed in English. + """ + ... + + def GetValue(self, + range: RANGE + ) -> Union[str, Tuple[Union[str, float], ...], Tuple[Tuple[Union[str, float], ...]], ...]: + """ + Get the value(s) stored in the given range of cells as a single value, a tuple or a tuple of tuples. + All returned values are either doubles or strings. + Args + ``range``: the range where to get the values from, as a string. + Returns + If a cell contains a date, the number corresponding to that date will be returned. + To convert numeric values to dates, use the ``CDate()`` function from the + ``SFScriptForge.SF_Basic`` service. + """ + ... + + def ImportFromCSVFile(self, + filename: FILE, + destinationcell: RANGE, + filteroptions: str = ... + ) -> RANGE: + """ + Imports the contents of a CSV-formatted text file and places it on a given destination cell. + The destination area is cleared of all contents and formats before inserting the contents + of the CSV file. + Args + ``filename``: identifies the file to open. It must follow the ``SF_FileSystem.FileNaming`` + notation. + + ``destinationcell``: the destination cell to insert the imported data, as a string. + If instead a range is given, only its top-left cell is considered. + + ``filteroptions``: the arguments for the CSV input filter. + Returns + A string representing the modified range of cells. + The modified area depends only on the content of the source file. + Note + Default ``filteroptions`` make the following assumptions: + - The input file encoding is UTF8. + - The field separator is a comma, a semicolon or a Tab character. + - The string delimiter is the double quote ("). + - All lines are included. + - Quoted strings are formatted as text. + - Special numbers are detected. + - All columns are presumed to be texts, except if recognized as valid numbers. + - The language is English/US, which implies that the decimal separator is "." and the thousands separator is ",". + """ + ... + + def ImportFromDatabase(self, + filename: FILE = ..., + registrationname: str = ..., + destinationcell: RANGE = ..., + sqlcommand: SQL_SELECT = ..., + directsql: bool = ..., + ) -> None: + """ + Imports the contents of a database table, query or resultset, i.e. the result of a + SELECT SQL command, inserting it on a destination cell. + + The destination area is cleared of all contents and formats before inserting the + imported contents. The size of the modified area is fully determined by the contents in + the table or query. + Args + ``filename``: identifies the file to open. It must follow the ``SF_FileSystem.FileNaming`` + notation. + + ``registrationname``: the name to use to find the database in the databases register. + This argument is ignored if a filename is provided. + + ``destinationcell``: the destination of the imported data, as a string. + If a range is given, only its top-left cell is considered. + + ``sqlcommand``: a table or query name (without surrounding quotes or square brackets) + or a SELECT SQL statement in which table and field names may be surrounded by square brackets + or quotes to improve its readability. + + ``directsql``: when ``True``, the SQL command is sent to the database engine without + pre-analysis. Default is ``False``. The argument is ignored for tables.For queries, + the applied option is the one set when the query was defined. + """ + ... + + def ImportStylesFromFile(self, + filename: FILE, + families: Union[str, Sequence[str]] = ..., + overwrite: bool = ... + ): + """ + This method loads all the styles belonging to one or more style families from a closed + file into the actual ``Calc`` document. + + Are always imported together: + - ``ParagraphStyles`` and ``CharacterStyles`` + - ``NumberingStyles`` and ``ListStyles`` + + Args + ``filename``: the file from which to load the styles in the ``SFScriptForge.FileSystem`` + notation. The file is presumed to be a ``Calc`` document. + + ``families``: one of the style families present in the actual document, + as a case-sensitive string or a tuple of such strings. + Leave this argument blank to import all families. + + ``overwrite``: when ``True``, the actual styles may be overwritten. Default is ``False``. + Returns + ``True`` if styles were successfully imported. + + """ + ... + + def InsertSheet(self, sheetname: SHEETNAME, beforesheet: Union[SHEETNAME, int] = ...) -> bool: + """ + Inserts a new empty sheet before an existing sheet or at the end of the list of sheets. + Args + ``sheetname``: the name of the new sheet. + + ``beforesheet``: the name (string) or index (numeric, starting from 1) of the sheet + efore which to insert the new sheet. This argument is optional and the default behavior + is to insert the sheet at the last position. + Returns + ``True`` if the sheet could be inserted successfully. + """ + ... + + def MoveRange(self, source: RANGE, destination: RANGE) -> RANGE: + """ + Moves a specified source range to a destination cell. + Args + ``source``: the source range of cells, as a string. + + ``destination``: the destination cell, as a string. If a range is given, + its top-left cell is considered as the destination. + Returns + A string representing the modified range of cells. + The modified area depends only on the size of the source area. + """ + ... + + def MoveSheet(self, + sheetname: SHEETNAME, + beforesheet: Union[SHEETNAME, int] = ... + ) -> bool: + """ + Moves an existing sheet and places it before a specified sheet or at the end of the list of sheets. + Args + ``sheetname``: the name of the sheet to move. The sheet must exist or an exception is raised. + + ``beforesheet``: The name (string) or index (numeric, starting from 1) of the sheet + before which the original sheet will be placed. This argument is optional and + the default behavior is to move the sheet to the last position. + Returns + ``True`` if the sheet could be moved successfully. + """ + ... + + def Offset(self, + range: RANGE, + rows: int = ..., + columns: int = ..., + height: int = ..., + width: int = ..., + ) -> RANGE: + """ + Returns a new range (as a string) offset and/or resized by a certain number of rows and columns + from a given range. + + This method has the same behavior as the homonymous Calc's ``Offset()`` built-in function. + + Args + ``range``: the range, as a string, that the method will use as reference to perform + the offset operation. + + ``rows``: the number of rows by which the initial range is offset upwards (negative value) + or downwards (positive value). Use 0 (default) to stay in the same row. + + ``columns``: the number of columns by which the initial range is offset to the left + (negative value) or to the right (positive value). Use 0 (default) to stay in the same column. + + ``height``: the vertical height for an area that starts at the new range position. + Omit this argument when no vertical resizing is needed. + + ``width``: the horizontal width for an area that starts at the new range position. + Omit this argument when no horizontal resizing is needed. + Returns + A new range. + Note + - Arguments ``rows`` and ``columns`` must not lead to zero or negative start row or column. + - Arguments ``height`` and ``width`` must not lead to zero or negative count of rows or columns. + """ + ... + + def OpenRangeSelector(self, + title: str = ..., + selection: RANGE = ..., + singlecell: bool = ..., + closeafterselect: bool = ..., + ) -> RANGE: + """ + Opens a non-modal dialog that can be used to select a range in the document and returns a string + containing the selected range. + Args + ``title``: the title of the dialog, as a string. + + ``selection``: an initial range that is selected when the dialog is displayed. + + ``singlecell``: when ``True`` (default) only single-cell selection is allowed. + When ``False`` range selection is allowed. + + ``closeafterselect``: when ``True`` (default) the dialog is closed immediately after + the selection is made. wWhen ``False`` the user can change the selection as many times + as needed. Dialog closure is manual. + Returns + The selected range as a string, or the empty string when the user cancelled the request. + Note + This method opens the same dialog that is used by ``LibreOffice`` when the ``Shrink`` + button is pressed. For example, the vTools - Goal Seek`` dialog has a ``Shrink`` button + to the right of the ``Formula`` cell field. + """ + ... + + def Printf(self, + inputstr: str, + range: RANGE, + tokencharacter: str = ... + ) -> str: + """ + Returns the input string after substituting its tokens by their values in a given range. + + This method can be used to quickly extract specific parts of a range name, such as the sheet name + or the first cell column and row, and use them to compose a new range address or a formula. + + Args + ``inputstr``: the string containing the tokens that will be replaced by the corresponding + values in ``range``. + + ``range``: the range from which values will be extracted. If it contains a sheet name, + the sheet must exist. + + ``tokencharacter``: the character used to identify tokens. Defaults to "%". + Note + Accepted tokens: + - ``%S`` - the sheet name containing the range, including single quotes when necessary. + - ``%R1`` - the row number of the top left cell of the range. + - ``%C1`` - the column letter of the top left cell of the range. + - ``%R2`` - the row number of the bottom right cell of the range. + - ``%C2`` - the column letter of the bottom right cell of the range. + Returns + The input string after substitution of the contained tokens. + """ + ... + + def PrintOut(self, + sheetname: SHEETNAME = ..., + pages: str = ..., + copies: int = ...) -> bool: + """ + Send the content of the given sheet to the printer. + The printer might be defined previously by default, by the user or by the ``SF_Document.SetPrinter()`` + method. + Args + ``sheetname``: the sheet to print, default is the active sheet. + + ``pages``: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". + Default is all pages. + + ``copies``: the number of copies. Defaults to 1. + Returns + ``True`` when successful. + """ + ... + + def RemoveDuplicates(self, + range: RANGE, + columns: Union[int | Sequence[int]], + header: bool = ..., + casesensitive: bool = ..., + mode: Literal["CLEAR", "COMPACT"] = ..., + ) -> RANGE: + """ + Removes duplicate rows from a specified range. + The comparison to determine if a given row is a duplicate is done based on a subset + of the columns in the range. + + The resulting range replaces the input range, in which, either: + + - all duplicate rows are cleared from their content + - all duplicate rows are suppressed and rows below are pushed upwards. + + Anyway, the first copy of each set of duplicates is kept and the initial sequence is preserved. + + Args + ``range``: the range, as a string, from which the duplicate rows should be removed. + + ``columns``: a single integer or a tuple of integers containing column numbers, + indicating which columns will be considered to determine if a row is a duplicate or not. + If this argument is left blank, then only the first column is used. + Column numbers must be in the interval between ``1`` and the range width. + + ``header``: when ``True``, the first row is a header row. Default is ``False``. + + ``casesensitive``: for string comparisons. Default is ``False``. + + ``mode``: either ``"CLEAR"`` or ``"COMPACT"`` (default). + For large ranges, the ``"COMPACT"`` mode is probably significantly slower. + Returns + The resulting range as a string. + """ + ... + + def RemoveSheet(self, sheetname: SHEETNAME) -> bool: + """ + Removes an existing sheet from the document. + Args + ``sheetname``: the name of the sheet to remove. + Returns + ``True`` if the sheet could be removed successfully. + """ + ... + + def RenameSheet(self, sheetname: SHEETNAME, newname: SHEETNAME) -> bool: + """ + Renames the given sheet. + Args + ``sheetname``: the name of the sheet to rename. + + ``newname``: the new name of the sheet. It must not exist yet. + Returns + ``True`` if successful. + """ + ... + + def SetArray(self, + targetcell: RANGE, + value: Union[SCALAR, VECTOR, MATRIX] + ) -> RANGE: + """ + Stores the given value starting from a specified target cell. The updated area expands + itself from the target cell or from the top-left corner of the given range to accommodate + the size of the input value argument. Vectors are always expanded vertically. + Args + ``targetcell``: the cell or a range as a string from where to start to store the given value. + + ``value``: a scalar, a vector or an array with the new values to be stored from the target + cell or from the top-left corner of the range if targetcell is a range. + The new values must be strings, numeric values or dates. Other types will cause the + corresponding cells to be emptied. + Returns + A string representing the modified area as a range of cells. + Note + To dump the full contents of an array in a sheet, use ``SetArray()``. To dump the contents + of an array only within the boundaries of the targeted range of cells, use ``SetValue()``. + """ + ... + + def SetCellStyle(self, + targetrange: RANGE, + style: str, + filterformula: str = ..., + filterscope: Literal['CELL', 'ROW', 'COLUMN'] = ..., + ) -> RANGE: + """ + Applies the specified cell style to the given target range. + The range is updated and the remainder of the sheet is left untouched. + Either the full range is updated or a selection based on a ``filterformula``. + If the cell style does not exist, an error is raised. + Args + ``targetrange``: the range to which the style will be applied, as a string. + + ``style``: the name of the cell style to apply. + + ``filterformula``: a ``Calc`` formula that shall be applied to the given range + to determine which cells will be affected. The specified formula must return ``True`` + or ``False``. If this argument is not specified, then all cells in the range are affected. + + Express the formula in terms of (examples assume a range = ``"A1:J10"``): + - the top-left cell of the range when ``filterscope`` = "CELL" e.g. ``"=(A1>100)"`` + - the topmost row of the range when ``filterscope`` = "ROW" e.g. ``"=(SUM($A1:$J1)<1000)"`` + - the leftmost column of the range when ``filterscope`` = "COLUMN" e.g. ``"=(A$10=SUM(A$1:A$9))"`` + + ``filterscope``: determines how ``filterformula`` is expanded to the given range. + Tuple The argument is mandatory if a ``filterformula`` is specified. + Returns + A string representing the modified area as a range of cells. + """ + ... + + def SetFormula(self, + targetrange: RANGE, + formula: Union[str, Sequence[str], Sequence[Sequence[str]]] + ) -> RANGE: + """ + Inserts the given (list of) formula(s) in the specified range. + The size of the modified area is equal to the size of the range. + Args + ``targetrange``: the range to insert the formulas, as a string. + + ``formula``: a string, a tuple or a tuple of tuples of strings with the new + formulas for each cell in the target range. + Returns + A string representing the modified area as a range of cells. + Notes + The full range is updated and the remainder of the sheet is left unchanged. + + If the given ``formula`` is a string, the unique formula is pasted along the + whole range with adjustment of the relative references. + + If the size of ``formula`` is smaller than the size of ``targetrange``, then the + remaining cells are emptied. + + If the size of ``formula`` is larger than the size of ``targetrange``, then the + formulas are only partially copied until they fill the size of ``targetrange``. + + Vectors are always expanded vertically, except if ``targetrange`` has a height + of exactly 1 row. + """ + ... + + def SetValue(self, + targetrange: RANGE, + value: Union[SCALAR, VECTOR, MATRIX] + ) -> RANGE: + """ + Stores the given value(s) in the specified range. The size of the modified area + is equal to the size of the target range. + Args + ``targetrange``: the range where to store the given value, as a string. + + ``value``: a scalar, a vector or an array with the new values for each + cell of the range. The new values must be strings, numeric values or + dates. Other types will cause the corresponding cells to be emptied. + Returns + A string representing the modified area as a range of cells. + """ + ... + def ShiftDown(self, range: RANGE, wholerow: bool = ..., rows: int = ...) -> RANGE: + """ + Moves a given range of cells downwards by inserting empty rows. + The current selection is not affected. + + Depending on the value of the ``wholerows`` argument the inserted rows can either + span the width of the specified range or span all columns in the row. + Args + ``range``: the range above which rows will be inserted, as a string. + + ``wholerow``: if set to ``False`` (default), then the width + of the inserted rows will be the same as the width of the specified range. + Otherwise, the inserted row will span all columns in the sheet. + + ``rows``: the number of rows to be inserted. The default value is + the height of the original range. The number of rows must be a positive number. + Returns + A string representing the new location of the initial range. + """ + ... + + def ShiftLeft(self, range: RANGE, wholecolumn: bool = ..., columns: int = ...) -> RANGE: + """ + Deletes the leftmost columns of a given range and moves to the left all cells to the right + of the given range. The current selection is not affected. + + Depending on the value of the ``wholecolumn`` argument the deleted columns can either span the + height of the specified range or span all rows in the column. + Args + ``range``: the range from which cells will be deleted, as a string. + + ``wholecolumn``: if set to ``False`` (default), then the height of the deleted + columns will be the same as the height of the specified range. Otherwise, the deleted + columns will span all rows in the sheet. + + ``columns``: the number of columns to be deleted from the specified range. + The default value is the width of the original range, which is also the maximum + value of this argument. + Returns + A string representing the location of the remaining portion of the initial range. + If all cells in the original range have been deleted, then an empty string is returned. + """ + ... + + def ShiftRight(self, range: RANGE, wholecolumn: bool = ..., columns: int = ...) -> RANGE: + """ + Moves a given range of cells to the right by inserting empty columns. + The current selection is not affected. + + Depending on the value of the ``wholecolumn`` argument the inserted columns can + either span the height of the specified range or span all rows in the column. + Args + ``range``: the range which will have empty columns inserted to its left, as a string. + + ``wholecolumn``: if set to ``False`` (default), then the height of the inserted + columns will be the same as the height of the specified range. Otherwise, the inserted + columns will span all rows in the sheet. + + ``columns``: the number of columns to be inserted. The default value is the width + of the original range. + Returns + A string representing the new location of the initial range. + Note + If the shifted range exceeds the sheet edges, then nothing happens. + """ + ... + + def ShiftUp(self, range: RANGE, wholerow: bool = ..., rows: int = ...) -> RANGE: + """ + Deletes the topmost rows of a given range and moves upwards all cells below the given range. + The current selection is not affected. + + Depending on the value of the ``wholerow`` argument the deleted rows can either span the width + of the specified range or span all columns in the row. + Args + ``range``: the range from which cells will be deleted, as a string. + + ``wholerow``: if set to ``False`` (default), then the width of the deleted + rows will be the same as the width of the specified range. Otherwise, the deleted + row will span all columns in the sheet. + + ``rows``: the number of rows to be deleted from the specified range. + The default value is the height of the original range, which is also the maximum + value of this argument. + Returns + A string representing the location of the remaining portion of the initial range. + If all cells in the original range have been deleted, then an empty string is returned. + """ + ... + + def SortRange(self, + range: RANGE, + sortkeys: Union[int, Sequence[int]], + sortorder: Union[Literal['ASC', 'DESC', ''], Sequence[Literal['ASC', 'DESC', '']]] = ..., + destinationcell: RANGE = ..., + containsheader: bool = ..., + casesensitive: bool = ..., + sortcolumns: bool = ..., + ) -> RANGE: + """ + Sort the given range on any number of columns/rows. The sorting order may vary by column/row. + Args + ``range``: the range to be sorted, as a string. + + ``sortkeys``: a scalar (if 1 column/row) or a tuple of column/row numbers starting from 1. + + ``sortorder``: a scalar or a tuple of strings containing the values + ``"ASC"`` (ascending), ``"DESC"`` (descending) or ``""`` (which defaults to ascending). + Each item is paired with the corresponding item in ``sortkeys``. + If the sortorder tuple is shorter than ``sortkeys``, the remaining keys are sorted + in ascending order. + + ``destinationcell``: the destination cell of the sorted range of cells, + as a string. If a range is given, only its top-left cell is considered. + By default, the source range is overwritten. + + ``containsheader``: when ``True``, the first row/column is not sorted. + + ``casesensitive``: only for string comparisons. Default is ``False``. + + ``sortcolumns``: when ``True``, the columns are sorted from left to right. + Default is ``False`` : rows are sorted from top to bottom. + Returns + A string representing the modified range of cells. + """ + ... + + # ######################################################################### + # SF_CalcReference CLASS + # ######################################################################### + class SF_CalcReference(SFServices): + """ + The SF_CalcReference class has as unique role to hold sheet and range references. + """ + + # ######################################################################### + # SF_Chart CLASS + # ######################################################################### + class SF_Chart(SFServices): + """ + The SF_Chart module is focused on the description of chart documents + stored in Calc sheets. + With this service, many chart types and chart characteristics available + in the user interface can be read or modified. + """ + + ChartType: Literal['Pi', 'Bar', 'Donut', 'Column', 'Area', 'Line', 'CY', 'Bubble', 'Net'] + """ Get/set the chart type as a string that can assume one of the following values: "Pie", "Bar", + "Donut", "Column", "Area", "Line", "XY", "Bubble", "Net". """ + Deep: bool + """ When ``True`` indicates that the chart is three-dimensional and each series is arranged in the z-direction. + When ``False`` series are arranged considering only two dimensions. """ + Dim3D: Union[bool, str] + """ Get/set if the chart is displayed with 3D elements. If the value is a string, it must be either + ``"Bar", "Cylinder", "Cone"`` or ``"Pyramid"``. If the boolean ``True`` value is specified, + then the chart is displayed using 3D bars. """ + Exploded: Union[int, float] + """ Get/set how much pie segments are offset from the chart center as a percentage of the radius. + Applicable to ``Pie`` and ``Donut`` charts only. """ + Filled: bool + """ When ``True``, specifies a filled net chart. Applicable to ``net`` charts only. """ + Legend: bool + """ Specifies whether the chart has a legend. """ + Percent: bool + """ When ``True``, chart series are stacked and each category sums up to 100%. + Applicable to ``Area``, ``Bar``, ``Bubble``, ``Column`` and ``Net`` charts. """ + Stacked: bool + """ When ``True``, chart series are stacked. + Applicable to ``Area``, ``Bar``, ``Bubble``, ``Column`` and ``Net`` charts. """ + Title: str + """ Get/set the main title of the chart. """ + XTitle: str + """ Get/set the title of the X-axis. """ + YTitle: str + """ Get/set the title of the Y-axis. """ + + XChartObj: UNO + """ Returns the object representing the chart, which is an instance of the ``ScChartObj`` class. """ + XDiagram: UNO + """ Returns the ``com.sun.star.chart.XDiagram`` object representing the diagram of the chart. """ + XShape: UNO + """ Returns the ``com.sun.star.drawing.XShape`` object representing the shape of the chart. """ + XTableChart: UNO + """ Returns the ``com.sun.star.table.XTableChart`` object representing the data being displayed in the chart. + """ + + def ExportToFile(self, + filename: FILE, + imagetype: Literal['gif', 'jpeg', 'png', 'svg', 'tiff'] = ..., + overwrite: bool = ... + ) -> bool: + """ + Saves the chart as an image file in a specified location. + Args + ``filename``: identifies the path and file name where the image will be saved. + It must follow the notation defined in ``SF_FileSystem.FileNaming``. + + ``imagetype``: the name of the image type to be created. + The following values are accepted: ``gif, jpeg, png`` (default), ``svg`` and ``tiff``. + + ``overwrite``: specifies if the destination file can be overwritten. Defaults to ``False``. + Returns + ``True`` if the image file could be successfully created. + """ + ... + + def Resize(self, xpos: int = ..., ypos: int = ..., width: int = ..., height: int = ...) -> bool: + """ + Changes the position of the chart in the current sheet and modifies its width and height. + Args + ``xpos``: specify the new ``X`` position of the chart. + + ``ypos``: specify the new ``Y`` position of the chart. + + ``width``: specify the new width of the chart. + + ``height``: specify the new height of the chart. + Returns + ``True`` if repositioning/resizing was successful. + Note + - All arguments are provided as integer values that correspond to ``1/100`` of a millimeter. + - Omitted arguments leave the corresponding actual values unchanged. + - Negative arguments are ignored. + """ + ... + + # ######################################################################### + # SF_Form CLASS + # ######################################################################### + class SF_Form(SFServices): + """ + Management of forms defined in LibreOffice documents. Supported types are Base, Calc and Writer documents. + It includes the management of sub-forms + Each instance of the current class represents a single form or a single sub-form + A form may optionally be (understand "is often") linked to a data source manageable with + the SFDatabases.Database service. The current service offers rapid access to that service. + """ + + AllowDeletes: bool + """ Get/set if the form allows to delete records. """ + AllowInserts: bool + """ Get/set if the form allows to add records. """ + AllowUpdates: bool + """ Get/set if the form allows to update records. """ + BaseForm: str + """ Get the hierarchical name of the Base form document containing the actual form. """ + Bookmark: SCALAR + """ Specifies uniquely the current record of the form's underlying table, query or SQL statement. """ + CurrentRecord: int + """ Identifies the current record in the dataset being viewed on a form. If the row number is positive, + the cursor moves to the given row number with respect to the beginning of the result set. Row count starts at 1. + If the given row number is negative, the cursor moves to an absolute row position with respect to the end + of the result set. Row -1 refers to the last row in the result set. """ + Filter: str + """ Specifies a subset of records to be displayed as a ``SQL WHERE``-clause without the ``WHERE`` keyword. """ + LinkChildFields: Tuple[str, ...] + """ Specifies how records in a child subform are linked to records in its parent form. """ + LinkParentFields: Tuple[str, ...] + """ Specifies how records in a child subform are linked to records in its parent form. """ + Name: str + """ The name of the current form. """ + + OnApproveCursorMove: SCRIPT_URI + """ Get/set the macro triggered by the ``Before record change`` event.""" + OnApproveParameter: SCRIPT_URI + """ Get/set the macro triggered by the ``Fill parameters`` event.""" + OnApproveReset: SCRIPT_URI + """ Get/set the macro triggered by the ``Prior to reset`` event.""" + OnApproveRowChange: SCRIPT_URI + """ Get/set the macro triggered by the ``Before record action`` event.""" + OnApproveSubmit: SCRIPT_URI + """ Get/set the macro triggered by the ``Before submitting`` event.""" + OnConfirmDelete: SCRIPT_URI + """ Get/set the macro triggered by the ``Confirm deletion`` event.""" + OnCursorMoved: SCRIPT_URI + """ Get/set the macro triggered by the ``After record change`` event.""" + OnErrorOccurred: SCRIPT_URI + """ Get/set the macro triggered by the ``Error occurred`` event.""" + OnLoaded: SCRIPT_URI + """ Get/set the macro triggered by the ``When loading`` event.""" + OnReloaded: SCRIPT_URI + """ Get/set the macro triggered by the ``When reloading`` event.""" + OnReloading: SCRIPT_URI + """ Get/set the macro triggered by the ``Before reloading`` event.""" + OnResetted: SCRIPT_URI + """ Get/set the macro triggered by the ``After resetting`` event.""" + OnRowChanged: SCRIPT_URI + """ Get/set the macro triggered by the ``After record action`` event.""" + OnUnloaded: SCRIPT_URI + """ Get/set the macro triggered by the ``When unloading`` event.""" + OnUnloading: SCRIPT_URI + """ Get/set the macro triggered by the ``Before unloading`` event.""" + + OrderBy: str + """ Specifies in which order the records should be displayed as a ``SQL ORDER BY`` clause + without the ``ORDER BY`` keywords. """ + Parent: Union[FORM, FORMDOCUMENT, DOCUMENT, CALC, WRITER] + """ The parent of the current form. It can be either a ``SFDocuments.Form``, a ``SFDocuments.FormDocument``, + a ``SFDocuments.Document`` object or one of its subclasses. """ + RecordSource: Union[SQL_SELECT, str] + """ Specifies the source of the data, as a table name, a query name or a SQL statement. """ + + XForm: UNO + """ The UNO object representing interactions with the form. Refer to ``com.sun.star.form.XForm`` and + ``com.sun.star.form.component.DataForm`` in the API documentation for detailed information. """ + + def Activate(self) -> bool: + """ + Sets the focus on the container of the current ``Form`` instance. + + The behavior of the ``Activate`` method depends on the type of document where the form is located. + * In `Writer`` documents: Sets the focus on that document. + * In ``Calc`` documents: Sets the focus on the sheet to which the form belongs. + * In ``Base`` documents: Sets the focus on the ``FormDocument`` the ``Form`` refers to. + Returns + ``True`` if focusing was successful. + """ + ... + + def CloseFormDocument(self) -> bool: + """ + Closes the ``form`` document containing the actual ``Form`` instance. The ``Form`` instance is disposed. + + The method is deprecated. Use the ``SF_FormDocument.CloseDocument()`` method instead. + + Returns + ``True`` if closure is successful. + Note + This method only closes form documents located in ``Base`` documents. + If the form is stored in a ``Writer`` or ``Calc`` document, calling ``CloseFormDocument()`` + will have no effect. + """ + ... + + def Controls(self, controlname: str = ...) -> Union[FORMCONTROL, Tuple[str, ...]]: + """ + The value returned by the method depends on the arguments provided: + - If the method is called without arguments, then it returns the list of the controls contained in the form. + + - If the optional ``controlName`` argument is provided, the method returns a ``FormControl`` class instance referring to the specified control. + + Note + Subform controls are ignored by this method. + """ + ... + + def GetDatabase(self, user: str = ..., password: str = ...) -> Optional[DATABASE]: + """ + Gets a ``SFDatabases.Database`` instance giving access to the execution of SQL commands + on the database the current form is connected to and/or that is stored in the current ``Base`` document. + + Each form has its own database connection, except in ``Base`` documents where they all + share the same connection. + Args + ``user``, ``password````: the login parameters. + Returns + A ``SFDatabases.Database`` class instance. + """ + ... + + def MoveFirst(self) -> bool: + """ + The form cursor is positioned on the first record. + + Returns + ``True`` if successful. + """ + ... + + def MoveLast(self) -> bool: + """ + The form cursor is positioned on the last record. + + Returns + ``True`` if successful. + """ + ... + + def MoveNew(self) -> bool: + """ + The form cursor is positioned on the new record area. + + Returns + ``True`` if successful. + """ + ... + + def MoveNext(self, offset: int = ...) -> bool: + """ + The form cursor is positioned on the next record. + Args + ``offset``: the number of records to go forward. Defaults to 1. + Returns + ``True`` if successful. + """ + ... + + def MovePrevious(self, offset: int = ...) -> bool: + """ + The form cursor is positioned on the previous record. + Args + ``offset``: the number of records to go backward. Defaults to 1. + Returns + ``True`` if successful. + """ + ... + + def Requery(self) -> bool: + """ + Reloads the current data from the database and refreshes the form. + The cursor is positioned on the first record. + + Returns + ``True`` if successful. + """ + ... + + def Subforms(self, subform: Union[int, str] = ...) -> Union[FORM, Tuple[str, ...]]: + """ + Depending on the parameters provided this method will return: + + - A tuple with the names of all the subforms contained in the actual form (if the form argument is absent) + - A ``SFDocuments.Form`` service instance representing the subform specified as argument. + + Args + ``subform``: the name or index corresponding to a subform stored in the actual form. + If this argument is absent, the method will return a list with the names of + all available subforms. + """ + ... + + # ######################################################################### + # SF_FormControl CLASS + # ######################################################################### + class SF_FormControl(SFServices): + """ + Manage the controls belonging to a form or subform stored in a document. + + Each instance of the current class represents a single control within a form, a subform or a column + in a table-control. A prerequisite is that all controls within the same form, subform or table-control + must have a unique name. + """ + + Action: Literal['none', 'submitForm', 'resetForm', 'refreshForm', 'moveToFirst', 'moveToLast', 'moveToNext', + 'moveToPrev', 'saveRecord', 'moveToNew', 'deleteRecord', 'undoRecord'] + """ Get/set the action triggered when the button is clicked. Applicable to ``Button`` controls. """ + Caption: str + """ Get/set the text associated with the control. Applicable to ``Button, CheckBox, FixedText, + GroupBox, RadioButton`` controls. """ + ControlSource: str + """ Specifies the rowset field mapped onto the current control. Applicable to + ``CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, + PatternField, RadioButton, TextField, TimeField`` controls. """ + ControlType: str + """ get the type of control as a string. """ + Default: bool + """ Get/set whether a command button is the default (OK) button. + Applicable to ``Button`` controls. """ + DefaultValue: bool + """ Specifies the default value used to initialize a control in a new record. + Applicable to ``CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, + NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField`` controls. """ + Enabled: bool + """ Specifies if the control is accessible with the cursor. """ + Format: Literal["Standard (short)", "Standard (short YY)", "Standard (short YYYY)", "Standard (long)", + "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY", "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD", + "24h short", "24h long", "12h short", "12h long"] + """ Get/set the format used to display dates and times. Applicable to ``DateField, TimeFiels, FormattedField`` + controls. """ + ListCount: int + """ Get the number of rows in the control. Applicable to ``ComboBox, ListBox`` controls. """ + ListIndex: int + """ Get/set which item is selected in the control. In case of multiple selection, the index of the first + item is returned. Applicable to ``ComboBox, ListBox`` controls. """ + ListSource: Union[str, Tuple[str, ...]] + """ Specifies the data contained in a control as a tuple of string values. + Combined with ``ListSourceType``, may also contain the name of a table, a query or a complete SQL statement. + Applicable to ``ComboBox, ListBox`` controls. """ + ListSourceType: int + """ Specifies the type of data contained in a control. It must be one of + the ``com.sun.star.form.ListSourceType.*`` constants. Applicable to ``ComboBox, ListBox`` controls. """ + Locked: bool + """ Get/set if the control is read-only.. Applicable to ``ComboBox, CurrencyField, DateField, FileControl, + FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField`` controls. """ + MultiSelect: bool + """ Get/set whether a user can make multiple selections in a ``listbox``. """ + Name: str + """ The name of the control. """ + + OnActionPerformed: SCRIPT_URI + """ Get/set the macro triggered by the ``Execute action`` event. """ + OnAdjustmentValueChanged: SCRIPT_URI + """ Get/set the macro triggered by the ``While adjusting`` event. """ + OnApproveAction: SCRIPT_URI + """ Get/set the macro triggered by the ``Approve action`` event. """ + OnApproveReset: SCRIPT_URI + """ Get/set the macro triggered by the ``Prior to reset`` event. """ + OnApproveUpdate: SCRIPT_URI + """ Get/set the macro triggered by the ``WBefore updating`` event. """ + OnChanged: SCRIPT_URI + """ Get/set the macro triggered by the ``Changed`` event. """ + OnErrorOccurred: SCRIPT_URI + """ Get/set the macro triggered by the ``Error occurred`` event. """ + OnFocusGained: SCRIPT_URI + """ Get/set the macro triggered by the ``When receiving focus`` event.""" + OnFocusLost: SCRIPT_URI + """ Get/set the macro triggered by the ``When losing focus`` event.""" + OnItemStateChanged: SCRIPT_URI + """ Get/set the macro triggered by the ``Item status changed`` event. """ + OnKeyPressed: SCRIPT_URI + """ Get/set the macro triggered by the ``Key pressed`` event.""" + OnKeyReleased: SCRIPT_URI + """ Get/set the macro triggered by the ``Key released`` event.""" + OnMouseDragged: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse moved while button pressed`` event.""" + OnMouseEntered: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse inside`` event.""" + OnMouseExited: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse outside`` event.""" + OnMouseMoved: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse moved`` event.""" + OnMousePressed: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse button pressed`` event.""" + OnMouseReleased: SCRIPT_URI + """ Get/set the macro triggered by the ``Mouse button released`` event.""" + OnResetted: SCRIPT_URI + """ Get/set the macro triggered by the ``After resetting`` event. """ + OnTextChanged: SCRIPT_URI + """ Get/set the macro triggered by the ``Text modified`` event. """ + OnUpdated: SCRIPT_URI + """ Get/set the macro triggered by the ``After updating`` event. """ + + Parent: Union[FORM, FORMCONTROL] + """ Depending on the parent type, a form, a subform or a tablecontrol, returns the parent + ``SFDocuments.SF_Form`` or ``SFDocuments.SF_FormControl`` class instance. """ + Picture: FILE + """ Get/se the file name (in ``FileSystem.FileNaming`` notation) containing a bitmap or other type of graphic + to be displayed on the control. Applicable to ``Button, ImageButton, ImageControl`` controls. """ + Required: bool + """ A control is said required when the underlying data must not contain a ``NULL`` value. + Applicable to ``CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, + RadioButton, SpinButton, TextField, TimeField`` controls.""" + Text: str + """ Get the text being displayed by the control. Applicable to ``ComboBox, DateField, FileControl, + FormattedField, PatternField, TextField, TimeField`` controls. """ + TipText: str + """ Specifies the text that appears as a tooltip when you hover the mouse pointer over the control. """ + TripleState: bool + """ Get/set whether the ``checkbox`` control may appear dimmed (grayed). """ + Value: Any + """ + Get/set the content of the control: + + - ``Button``: bool - For toggle buttons only. + - ``CheckBox``: bool, int - 0, ``False``: not checked, 1, ``True``: checked, 2: grayed, don't know. + - ``ComboBox``: str - The selected value. The ``ListIndex`` property is an alternate option. + - ``CurrencyField``: int, float. + - ``DateField``: datetime.datetime. + - ``FileControl``: FILE. + - ``FormattedField``: str, int, float. + - ``HiddenControl``: str, + - ``ListBox``: List(str), str - Get the selected row(s) as a single string or an array of strings. Only a single value can be set. + - ``NumericField``: int, float. + - ``PatternField``: str. + - ``RadioButton``: bool - Each button has its own name. Multiple RadioButton controls are linked together when they share the same group name. If a radiobutton is set to ``True``, the other related buttons are automatically set to ``False``. + - ``ScrollBar``: int - Must be within the predefined bounds. + - ``SpinButton``: int - Must be within the predefined bounds. + - ``TextField``: str - The text appearing in the control. + - ``TimeField``: datetime.datetime. + Not applicable to ``FixedText, GroupBox, ImageButton, ImageControl, NavigationBar`` and ``TableControl`` + form controls. + """ + Visible: bool + """ Get/set if the form control is hidden or visible. """ + + XControlModel: UNO + """ The UNO representation (``com.sun.star.awt.XControlModel``) of the control model. """ + XControlView: UNO + """ The UNO representation (``com.sun.star.awt.XControl``) of the control view. """ + + def Controls(self, controlname: str = ...) -> Union[FORMCONTROL, Tuple[str, ...]]: + """ + This method is applicable only to controls of the ``TableControl`` type. + The returned value depends on the arguments provided. + + If ``controlname`` is absent, then a tuple containing the names of all controls is returned. + + If ``controlname`` is provided, the method returns a ``FormControl`` class instance + corresponding to the specified control. + + Args + ``controlname``: a valid control name as a case-sensitive string. + Returns + The list of available control names + or an instance of the ``SFDocuments.SF_FormControl`` class. + """ + ... + + def SetFocus(self) -> bool: + """ + Sets the focus on the control. + + Returns + ``True`` if focusing was successful. + """ + ... + + # ######################################################################### + # SF_FormDocument CLASS + # ######################################################################### + class SF_FormDocument(SF_Document, SFServices): + """ + The ``FormDocument`` service allows to access form documents stored in ``Base`` documents. + + Each form document may be composed of one or more forms, including the main form and other sub-forms. + + This service inherits methods and properties from the ``Document`` service and is often used alongside + the ``Base`` and ``Database`` services. + """ + + def CloseDocument(self) -> bool: + """ + Close the form document and dispose the actual instance. + + Returns + ``True`` if closure is successful. + """ + ... + + def Forms(self, form: Union[int, str] = ...) -> Union[FORM, Tuple[str, ...]]: + """ + Depending on the parameters provided this method will return: + + - A tuple with the names of all the forms contained in the form document (if the form argument is absent) + - A ``SFDocuments.Form`` service instance representing the form specified as argument. + + Args + ``form``: the name or index corresponding to a form stored in the form document. + If this argument is absent, the method will return a list with the names of all available forms. + """ + ... + + def GetDatabase(self, user: str = ..., password: str = ...) -> Optional[DATABASE]: + """ + Returns a Database service instance (service = ``SFDatabases.Database``) giving access + to the execution of SQL commands on the database linked with the actual form document. + Args + ``user``, ``oassword``: the login parameters. + """ + ... + + def PrintOut(self, + pages: str = ..., + copies: int = ..., + printbackground: bool = ..., + printblankpages: bool = ..., + printevenpages: bool = ..., + printoddpages: bool = ..., + printimages: bool = ..., + ) -> bool: + """ + Send the content of the document to the printer. + + The printer might be defined previously by default, by the user or by the SetPrinter() method. + + Args + ``pages``: the pages to print as a string, like in the user interface. + Example: "1-4;10;15-18". Defaults to all pages. + + ``copies``: the number of copies to print. Defaults to 1. + + ``printbackground``: print the background image when ``True`` (default). + + ``printblankpages``: when ``False`` (default), omit empty pages. + + ``printevenpages``: print the left pages when ``True`` (default). + + ``printoddpages``: print the right pages when ``True`` (default). + + ``printimages``: print the graphic objects when ``True`` (defauly). + Returns + ``True`` when successful. + """ + ... + + # ######################################################################### + # SF_Writer CLASS + # ######################################################################### + class SF_Writer(SF_Document, SFServices): + """ + Many methods are generic for all types of documents and are inherited from the ``SF_Document`` + module, whereas other methods that are specific for ``Writer`` documents are defined + in the ``SF_Writer`` module. + """ + + def Forms(self, form: Union[int, str] = ...) -> Union[FORM, Tuple[str, ...]]: + """ + Depending on the parameters provided this method will return: + + - A tuple with the names of all the forms contained in the writer document (if the form argument is absent) + - A ``SFDocuments.Form`` service instance representing the form specified as argument. + + Args + ``form``: the name or index corresponding to a form stored in the form document. + If this argument is absent, the method will return a list with the names of all available forms. + """ + ... + + def ImportStylesFromFile(self, + filename: FILE, + families: Union[str, Sequence[str]] = ..., + overwrite: bool = ... + ): + """ + This method loads all the styles belonging to one or more style families from a closed + file into the actual ``Writer`` document. + + Are always imported together: + - ``ParagraphStyles`` and ``CharacterStyles`` + - ``NumberingStyles`` and ``ListStyles`` + + Args + ``filename``: the file from which to load the styles in the ``SFScriptForge.FileSystem`` + notation. The file is presumed to be a ``Writer`` document. + + ``families``: one of the style families present in the actual document, + as a case-sensitive string or a tuple of such strings. + Leave this argument blank to import all families. + + ``overwrite``: when ``True``, the actual styles may be overwritten. Default is ``False``. + Returns + ``True`` if styles were successfully imported. + + """ + ... + + def PrintOut(self, + pages: str = ..., + copies: int = ..., + printbackground: bool = ..., + printblankpages: bool = ..., + printevenpages: bool = ..., + printoddpages: bool = ..., + printimages: bool = ..., + ) -> bool: + """ + Send the content of the document to the printer. + + The printer might be defined previously by default, by the user or by the SetPrinter() method. + + Args + ``pages``: the pages to print as a string, like in the user interface. + Example: "1-4;10;15-18". Defaults to all pages. + + ``copies``: the number of copies to print. Defaults to 1. + + ``printbackground``: print the background image when ``True`` (default). + + ``printblankpages``: when ``False`` (default), omit empty pages. + + ``printevenpages``: print the left pages when ``True`` (default). + + ``printoddpages``: print the right pages when ``True`` (default). + + ``printimages``: print the graphic objects when ``True`` (defauly). + Returns + ``True`` when successful. + """ + ... + +class SFWidgets: + """ + The SFWidgets class manages toolbars, menus and popup menus. + """ + + # ######################################################################### + # SF_Menu CLASS + # ######################################################################### + class SF_Menu(SFServices): + """ + Display a menu in the menubar of a document or a form document. + After use, the menu will not be saved neither in the application settings, nor in the document. + + The menu will be displayed, as usual, when its header in the menubar is clicked. + When one of its items is selected, there are 3 alternative options: + - a UNO command (like ".uno:About") is triggered + - a user script is run receiving a standard argument defined in this service + - one of above combined with a toggle of the status of the item + + The menu is described from top to bottom. Each menu item receives a numeric and a string identifier. + + The ``SF_Menu`` service provides the following capabilities: + - Creation of menus with custom entries, checkboxes, radio buttons and separators. + - Decoration of menu items with icons and tooltips. + Menu entries associated with a script receive a comma-separated string argument with the following values: + - The toplevel name of the menu. + - The string ID of the selected menu entry. + - The numeric ID of the selected menu entry. + - The current state of the menu item. This is useful for checkboxes and radio buttons. If the item is checked, the value "1" is returned, otherwise "0" is returned. + """ + + ShortcutCharacter: str + """ Character used to define the access key of a menu item. The default character is "~" (tilde). """ + SubmenuCharacter: str + """ Character or string that defines how menu items are nested. The default character is ">". + + Example + ``oMenu.AddItem("Item A")`` + + ``oMenu.AddItem("Item B>Item B.1")`` + + ``oMenu.AddItem("Item B>Item B.2")`` + + ``oMenu.AddItem("---")`` + + ``oMenu.AddItem("Item C>Item C.1>Item C.1.1")`` + + ``oMenu.AddItem("Item C>Item C.1>Item C.1.2")`` + + ``oMenu.AddItem("Item C>Item C.2>Item C.2.1")`` + + ``oMenu.AddItem("Item C>Item C.2>Item C.2.2")`` + + ``oMenu.AddItem("Item C>Item C.2>---")`` + + ``oMenu.AddItem("Item C>Item C.2>Item C.2.3")`` + + ``oMenu.AddItem("Item C>Item C.2>Item C.2.4")`` + """ + + def AddCheckBox(self, + menuitem: str, + name: str = ..., + status: bool = ..., + icon: str = ..., + tooltip: str = ..., + command: str = ..., + script: SCRIPT_URI = ..., + ) -> int: + """ + Inserts a checkbox in the menu. + Args + ``menuitem``: defines the text to be displayed in the menu. + This argument also defines the hierarchy of the item inside the menu by using the submenu + character. + + ``name``: the string value used to identify the menu item. + By default, the last component of the menu hierarchy is used. + + ``status``: defines whether the item is selected when the menu is created. Defaults to ``False``. + + ``icon``: the relative path and name of the icon to be displayed versus the folder structure + found in the ZIP files located in the ``$INSTALLDIR/share/config`` directory. + The actual icon shown depends on the icon set being used. + + ``tooltip``: text to be displayed as tooltip. + + ``command``: the name of a UNO command without the .uno: prefix. If the command name + does not exist, nothing will happen when the item is clicked. + + ``script``: the URI for a Basic or Python script that will be executed when the item is clicked. + Note + The ``command`` and ``script`` arguments are mutually exclusive. + Returns + A numeric value that uniquely identifies the inserted item. + """ + ... + + def AddItem(self, + menuitem: str, + name: str = ..., + icon: str = ..., + tooltip: str = ..., + command: str = ..., + script: SCRIPT_URI = ..., + ) -> int: + """ + Inserts a label entry in the menu. + Args + ``menuitem``: defines the text to be displayed in the menu. + This argument also defines the hierarchy of the item inside the menu by using the submenu + character. + + ``name``: the string value used to identify the menu item. + By default, the last component of the menu hierarchy is used. + + ``icon``: the relative path and name of the icon to be displayed versus the folder structure + found in the ZIP files located in the ``$INSTALLDIR/share/config`` directory. + The actual icon shown depends on the icon set being used. + + ``tooltip``: text to be displayed as tooltip. + + ``command``: the name of a UNO command without the .uno: prefix. If the command name + does not exist, nothing will happen when the item is clicked. + + ``script``: the URI for a Basic or Python script that will be executed when the item is clicked. + Note + The ``command`` and ``script`` arguments are mutually exclusive. + Returns + A numeric value that uniquely identifies the inserted item. + """ + ... + + def AddRadioButton(self, + menuitem: str, + name: str = ..., + status: bool = ..., + icon: str = ..., + tooltip: str = ..., + command: str = ..., + script: SCRIPT_URI = ..., + ) -> int: + """ + Inserts a radio btton in the menu. + Args + ``menuitem``: defines the text to be displayed in the menu. + This argument also defines the hierarchy of the item inside the menu by using the submenu + character. + + ``name``: the string value used to identify the menu item. + By default, the last component of the menu hierarchy is used. + + ``status``: defines whether the item is selected when the menu is created. Defaults to ``False``. + + ``icon``: the relative path and name of the icon to be displayed versus the folder structure + found in the ZIP files located in the ``$INSTALLDIR/share/config`` directory. + The actual icon shown depends on the icon set being used. + + ``tooltip``: text to be displayed as tooltip. + + ``command``: the name of a UNO command without the .uno: prefix. If the command name + does not exist, nothing will happen when the item is clicked. + + ``script``: the URI for a Basic or Python script that will be executed when the item is clicked. + Note + The ``command`` and ``script`` arguments are mutually exclusive. + Returns + A numeric value that uniquely identifies the inserted item. + """ + ... + + # ######################################################################### + # SF_Menu CLASS + # ######################################################################### + class SF_PopupMenu(SFServices): + """ + Display a popup menu anywhere and any time. + A popup menu is usually triggered by a mouse action (typically a right-click) on a dialog, a form + or one of their controls. In this case the menu will be displayed below the clicked area. + + When triggered by other events, including in the normal flow of a user script, the script should + provide the coordinates of the top-left edge of the menu versus the actual component. + + The menu is described from top to bottom. Each menu item receives a numeric and a string identifier. + The ``Execute()`` method returns the item selected by the user. + + The ``SF_PopupMenu`` service provides the following capabilities: + - Creation of menus with custom entries, checkboxes, radio buttons and separators. + - Decoration of menu items with icons and tooltips. + """ + + ShortcutCharacter: str + """ Character used to define the access key of a menu item. The default character is "~" (tilde). """ + SubmenuCharacter: str + """ Character or string that defines how menu items are nested. The default character is ">". + + Example + ``oMenu.AddItem("Item A")`` + + ``oMenu.AddItem("Item B>Item B.1")`` + + ``oMenu.AddItem("Item B>Item B.2")`` + + ``oMenu.AddItem("---")`` + + ``oMenu.AddItem("Item C>Item C.1>Item C.1.1")`` + + ``oMenu.AddItem("Item C>Item C.1>Item C.1.2")`` + + ``oMenu.AddItem("Item C>Item C.2>Item C.2.1")`` + + ``oMenu.AddItem("Item C>Item C.2>Item C.2.2")`` + + ``oMenu.AddItem("Item C>Item C.2>---")`` + + ``oMenu.AddItem("Item C>Item C.2>Item C.2.3")`` + + ``oMenu.AddItem("Item C>Item C.2>Item C.2.4")`` + """ + + def AddCheckBox(self, + menuitem: str, + name: str = ..., + status: bool = ..., + icon: str = ..., + tooltip: str = ..., + ) -> int: + """ + Inserts a checkbox in the menu. + Args + ``menuitem``: defines the text to be displayed in the menu. + This argument also defines the hierarchy of the item inside the menu by using the submenu + character. + + ``name``: the string value used to identify the menu item. + By default, the last component of the menu hierarchy is used. + + ``status``: defines whether the item is selected when the menu is created. Defaults to ``False``. + + ``icon``: the relative path and name of the icon to be displayed versus the folder structure + found in the ZIP files located in the ``$INSTALLDIR/share/config`` directory. + The actual icon shown depends on the icon set being used. + + ``tooltip``: text to be displayed as tooltip. + Returns + A numeric value that uniquely identifies the inserted item. + """ + ... + + def AddItem(self, + menuitem: str, + name: str = ..., + icon: str = ..., + tooltip: str = ..., + ) -> int: + """ + Inserts a label entry in the menu. + Args + ``menuitem``: defines the text to be displayed in the menu. + This argument also defines the hierarchy of the item inside the menu by using the submenu + character. + + ``name``: the string value used to identify the menu item. + By default, the last component of the menu hierarchy is used. + + ``icon``: the relative path and name of the icon to be displayed versus the folder structure + found in the ZIP files located in the ``$INSTALLDIR/share/config`` directory. + The actual icon shown depends on the icon set being used. + + ``tooltip``: text to be displayed as tooltip. + Returns + A numeric value that uniquely identifies the inserted item. + """ + ... + + def AddRadioButton(self, + menuitem: str, + name: str = ..., + status: bool = ..., + icon: str = ..., + tooltip: str = ..., + ) -> int: + """ + Inserts a radio btton in the menu. + Args + ``menuitem``: defines the text to be displayed in the menu. + This argument also defines the hierarchy of the item inside the menu by using the submenu + character. + + ``name``: the string value used to identify the menu item. + By default, the last component of the menu hierarchy is used. + + ``status``: defines whether the item is selected when the menu is created. Defaults to ``False``. + + ``icon``: the relative path and name of the icon to be displayed versus the folder structure + found in the ZIP files located in the ``$INSTALLDIR/share/config`` directory. + The actual icon shown depends on the icon set being used. + + ``tooltip``: text to be displayed as tooltip. + Returns + A numeric value that uniquely identifies the inserted item. + """ + ... + + def Execute(self, returnid: bool = ...) -> Union[int, str]: + """ + Displays the popup menu and waits for a user action. + Args + ``returnid``: if ``True`` (default), the numeric identfier of the selected item is returned. + If ``False``, the method returns the item's name. + Returns + The item clicked by the user. + If the user clicks outside the popup menu or presses the ``Esc`` key, then no item is selected. + In such cases, the returned value is either ``0`` (zero) or the empty string, depending + on the ``returnid`` argument. + """ + ... + + # ######################################################################### + # SF_Toolbar CLASS + # ######################################################################### + class SF_Toolbar(SFServices): + """ + Each component has its own set of toolbars, depending on the component type + (Calc, Writer, Basic IDE, ...). + + In the context of the actual class, a toolbar is presumed defined statically: + - either bat LibreOffice installation, + - or by a customization done by the user at application or at document levels. + + The ``Toolbar`` service allows to retrieve information related to the toolbars available for + a specific document window. + + With this service it is possible to: + - toggle the visibility of specific toolbars. + - access to information about the buttons available in each toolbar. + + This service handles both built-in and custom toolbars. + """ + + BuiltIn: bool + """ Returns ``True`` when the toolbar is part of the set of standard toolbars shipped with LibreOffice. """ + Docked: bool + """ Returns ``True`` when the toolbar is active in the window and docked. """ + HasGlobalScope: bool + """ Returns ``True`` when the toolbar is available in all documents of the same type. """ + Name: str + """ Returns the name of the toolbar. """ + ResourceURL: str + """ Returns the resource URL of the toolbar, in the form ``"private:toolbar/toolbar_name"``. """ + Visible: bool + """ Get/set whether the toolbar is active and visible in the document window. """ + XUIElement: UNO + """ Returns the ``com.sun.star.ui.XUIElement`` UNO object that represents the toolbar. """ + + def ToolbarButtons(self, buttonname: str = ...) -> Union[TOOLBARBUTTON, Tuple[str]]: + """ + Returns either a list of the available toolbar button names in the actual toolbar + or a ``ToolbarButton`` object instance. + Args + ``buttonname``: the usual name of one of the available buttons in the actual toolbar. + The button name is the localized button name defined in the ``Tools - Customize - Toolbars`` + dialog. + Returns + A tuple of button names when the argument is absent, + or a new ``SF_ToolbarButton`` object instance otherwise. + """ + ... + + # ######################################################################### + # SF_Toolbar CLASS + # ######################################################################### + class SF_ToolbarButton(SFServices): + """ + A toolbar consists in a series of graphical controls to trigger actions. + The ``Toolbar`` service gives access to the ``ToolbarButton`` service to manage + the individual buttons belonging to the toolbar. + + With this service it is possible to: + - know the characteristics of the button + - toggle the visibility of the button. + - execute the command associated with the toolbar button. + """ + + Caption: str + """ Returns the name of the button. """ + Height: int + """ Returns the height of the button, in pixels. """ + Index: int + """ Returns the index of the button in its parent toolbar. """ + OnClick: str + """ Get/set the UNO command or the script executed when the button is pressed. """ + Parent: TOOLBAR + """ Returns a ``Toolbar`` service instance corresponding to the parent toolbar of the current + toolbar button. """ + TipText: str + """ Get/set the tooltip text shown when the user hovers the toolbar button. """ + Visible: bool + """ Get/set whether the toolbar button is visible or not. """ + Width: int + """ Returns the width of the button, in pixels. """ + X: int + """ Returns the X (horizontal) coordinate of the top-left corner of the button, in pixels. """ + Y: int + """ Returns the Y (vertical) coordinate of the top-left corner of the button, in pixels. """ + + def Execute(self) -> Optional[Any]: + """ + Execute the command stored in the toolbar button. + The command can be a UNO command or a Basic/Python script (expressed in the + ``scripting framework_URI`` notation). + Returns + The output of the script or None + """ + ... + + +# ############################################################################# +# CreateScriptService signatures +# ############################################################################# +@overload +def CreateScriptService(service: Literal['servicename', 'Servicename', 'Library.Servicename'], *args: Any + ) -> Optional[SERVICE]: + """ + The modules and classes implemented in the ScriptForge libraries are invoked + from user scripts as "Services". A generic constructor of those services has been designed for that purpose. + + Args + ``service``: the name of the service as a string 'library.service' or one of its synonyms. + + The service names created with ``CreateScriptService()`` are: + - ``Array``, ``Basic``, ``Dictionary``, ``Exception``, ``FileSystem``, ``L10N``, ``Platform``, ``Region``, ``Session``, ``String``, ``Timer``, ``UI`` + - ``Database`` + - ``Dialog``, ``NewDialog``, ``DialogEvent`` + - ``Document``, ``Base``, ``Calc``, ``Writer`` + - ``PopupMenu`` + + ``args``: the optional arguments to pass to the service constructor. + ``Dictionary`` + (positional): a Python dictionary. Default = ``None``. + ``Timer`` + ``start``: when ``True``, the timer starts immediately. Default = ``False``. + ``Database`` + ``filename``: the name of the ``Base`` file containing the database. Must be expressed + using the ``SF_FileSystem.FileNaming`` notation. + + ``registrationname``: the name of a registered database. + If ``filename`` is provided, this argument is ignored. + + ``readonly``: determines if the database will be opened as readonly. Defaults to ``True``. + + ``user``, ``password``: additional connection parameters. + ``Dialog`` + ``container``: ``"GlobalScope"`` for preinstalled libraries or a window name. + Defaults to the current document. + + ``library``: the case-sensitive name of a library contained in the container. + Default value is ``"Standard"``. + + ``dialogname``: a case-sensitive string designating the dialog. + ``NewDialog`` + ``dialogname``: an identifier for the dialog to be built from scratch. + + ``place``: the size and position expressed in "``APPFONT units``". Either: + - a tuple (X, Y, Width, Height). + - a ``com.sun.star.awt.Rectangle`` structure. + ``DialogEvent`` + (positional): the event object passed by ``LibreOffice`` to the event-handling routine. + ``Document``, ``Base``, ``Calc``, ``Writer`` + ``windowname``: see definitions at ``SF_UI`` class level. + ``PopupMenu`` + ``event``: the mouse event object passed by ``LibreOffice`` to the event-handling routine. + + ``x``, ``y``: the screen coordinates where the menu will be displayed. + + ``submenuchar``: character or string that defines how menu items are nested. + The default character is ``">"``. + Returns + The service as a Python class instance. + """ + ... +@overload +def CreateScriptService(service: Literal['array', 'Array', 'ScriptForge.Array']) -> ARRAY: ... +@overload +def CreateScriptService(service: Literal['basic', 'Basic', 'ScriptForge.Basic']) -> BASIC: ... +@overload +def CreateScriptService(service: Literal['dictionary', 'Dictionary', 'ScriptForge.Dictionary'], + dic: Optional[Dict] = None) -> Optional[DICTIONARY]: ... +@overload +def CreateScriptService(service: Literal['exception', 'Exception', 'ScriptForge.Exception']) -> EXCEPTION: ... +@overload +def CreateScriptService(service: Literal['filesystem', 'FileSystem', 'ScriptForge.FileSystem']) -> FILESYSTEM: ... +@overload +def CreateScriptService(service: Literal['l10n', 'L10N', 'ScriptForge.L10N'], foldername: str = '', + locale: str = '', encoding: str = '', locale2: str = '', encoding2: str = '') -> Optional[L10N]: ... +@overload +def CreateScriptService(service: Literal['platform', 'Platform', 'ScriptForge.Platform']) -> PLATFORM: ... +@overload +def CreateScriptService(service: Literal['region', 'Region', 'ScriptForge.Region']) -> Optional[REGION]: ... +@overload +def CreateScriptService(service: Literal['session', 'Session', 'ScriptForge.Session']) -> SESSION: ... +@overload +def CreateScriptService(service: Literal['string', 'String', 'ScriptForge.String']) -> STRING: ... +@overload +def CreateScriptService(service: Literal['timer', 'Timer', 'ScriptForge.Timer'], start: bool = False + ) -> Optional[TIMER]: ... +@overload +def CreateScriptService(service: Literal['ui', 'UI', 'ScriptForge.UI']) -> UI: ... +@overload +def CreateScriptService(service: Literal['database', 'Database', 'SFDatabases.Database'], filename: str = '', + registrationname: str = '', readonly: bool = True, user: str = '', password: str = '' + ) -> Optional[DATABASE]: ... +@overload +def CreateScriptService(service: Literal['dialog', 'Dialog', 'SFDialogs.Dialog'], container: str = '', + library: str = 'Standard', dialogname: str = '') -> Optional[DIALOG]: ... +@overload +def CreateScriptService(service: Literal['newdialog', 'NewDialog', 'SFDialogs.NewDialog'], dialogname: str, + place: Tuple[int, int, int, int]) -> Optional[DIALOG]: ... +@overload +def CreateScriptService(service: Literal['dialogevent', 'DialogEvent', 'SFDialogs.DialogEvent'], + event: Optional[UNO] = None) -> Optional[DIALOG, DIALOGCONTROL]: ... +@overload +def CreateScriptService(service: Literal['document', 'Document', 'SFDocuments.Document'], + windowname: Union[UNO, str] = '') -> Optional[DOCUMENT]: ... +@overload +def CreateScriptService(service: Literal['base', 'Base', 'SFDocuments.Base'], windowname: Union[UNO, str] = '' + ) -> Optional[BASE]: ... +@overload +def CreateScriptService(service: Literal['calc', 'Calc', 'SFDocuments.Calc'], windowname: Union[UNO, str] = '' + ) -> Optional[CALC]: ... +@overload +def CreateScriptService(service: Literal['writer', 'Writer', 'SFDocuments.Writer'], windowname: Union[UNO, str] = '' + ) -> Optional[WRITER]: ... +@overload +def CreateScriptService(service: Literal['popupmenu', 'PopupMenu', 'SFWidgets.PopupMenu'], event: Optional[UNO] = None, + x: int = 0, y: int = 0, submenuchar:str = '') -> Optional[POPUPMENU]: ... + +createScriptService, createscriptservice = CreateScriptService, CreateScriptService |