| Quellcodebibliothek Statistik Leitseite products/Sources/formale Sprachen/C/LibreOffice/wizards/source/scriptforge/python/ (Office von Apache Version 25.8.3.2©) Datei vom 5.10.2025 mit Größe 383 kB |
|
Quellcode-Bibliothek scriptforge.pyi Sprache: unbekannt |
|
|
Spracherkennung für: .pyi vermutete Sprache: Unknown {[0] [0] [0]} [Methode: Schwerpunktbildung, einfache Gewichte, sechs Dimensionen] # -*- 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 eith # 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 f to be invoked from user Basic or Python macros. Users familiar with other BASIC macro variants o times to dig into the extensive LibreOffice Application Programming Interface even for the si By collecting most-demanded document operations in a set of easy to use, easy to read routines, 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 inte 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 Sc 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?Db """ # IMPORTS from __future__ import annotations import datetime import time from typing import Any, Dict, List, Literal, NewType, Optional, overload, Sequence, Tuple, T # 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 CONTEXTMENU = SFWidgets.SF_ContextMenu POPUPMENU = SFWidgets.SF_PopupMenu TOOLBAR = SFWidgets.SF_Toolbar TOOLBARBUTTON = SFWidgets.SF_ToolbarButton # Aggregate SERVICE = Union[ARRAY, BASIC, DICTIONARY, EXCEPTION, FILESYSTEM, L10N, PLATFORM, REGION, S TEXTSTREAM, TIMER, UI, DATABASE, DATASET, DATASHEET, DIALOG, DIALOGCONTROL, DOCUMENT, BASE, CALC, CALCREFERENCE, CHART, FORM, FORMCONTROL, FORMDOCUMENT, WRITER, MENU, CONTEXTMENU, POPUPMENU, TOOLBAR, TOOLBARBUTTON] # UNO UNO = TypeVar('UNO', Any, Any) # 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: "[]*?:\\\/". Th is forbidden in the first and last positions. The "~" (tilde) character designates the active s 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 " Otherwise surrounding single quotes and $ signs are allowed but ignored. The shortcut "~" (tilde) represents the current selection or the first selected range if multi 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 """ SQL_SELECT = TypeVar('SQL_SELECT', str, str) """ A SQL command containing a SELECT statement, a tablename or a queryname. In a SELECT statement, table-, query- 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.awt import XRectangle 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) XRectangle = NewType('XRectangle', 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 stri # 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 ("Single """ def __init__(self, hostname: str = ..., port: int = ..., pipe: str = ...): """ 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 ("Single 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 ``pipe``: pipe name """ ... # ############################################################################### # 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 strin 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.dat """ Converts a ``UNO date/time`` representation to a ``datetime.datetime`` Python native objec 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, dateti ) -> 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 refer """ ... @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 librarie 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 if no 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 col ``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 Wait(cls, millisec: Union[int, float]) -> None: """ Interrupts the program execution for the amount of time that you specify in milliseconds. The method is an alternative to ``time.sleep()`` that sometimes freezes the LibreOffice user interface. Args ``millisec``: The amount of time (in milliseconds) to wait before the program is continued. """ ... @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 ``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], overwrit """ 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`` instanc 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 overwritte 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 erro Use the console when the Python shell is not available, for example in ``Calc`` user defined fun or during events processing. Use the ``DebugPrint()`` and ``DebugDisplay()`` methods to log any relevant information, ev of any type to the console. Console entries can be dumped to a text file or visualized in a dialogue. """ ReportScriptErrors: bool """ When set to ``False``, an error occur silently. Useful f.i. in Calc user-defined functions The set value is preserved until it is explicitly set again. """ ReturnCode: str """ Returns the code returned by the last call to the ScriptForge API from a user script. It is the zero-length string if everything ran without error. """ ReturnCodeDescription: str """ Returns the localized description of the code returned by the last call to the ScriptForge A from a user script. It is the zero-length string if everything ran without error. """ StopWhenError: bool """ When set to ``False``, the process continues when ScriptForge detects a user script error. Default = ``True``. The set value is preserved until it is explicitly set again. """ def Clear(self): """ Reset the current error status and return code. """ ... def Console(self, modal: bool = ...) -> None: """ Displays the console messages in a modal or non-modal dialog. In both modes, all the past messag issued by a ``DebugPrint()`` method or resulting from an exception are displayed. In non-moda 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 use 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 = ...) -> None: """ Clears the console keeping an optional number of recent messages. If the console is activated i 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_FileSyste 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 = ..., background: int = ..., foreground: int = ... ) -> 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. ``background``: the background color of the window as an integer value. Usually given as a hexadecimal value, like 0xFFFFFF, or as the output of the ``basic.RGB()`` method. ``foreground``: the foreground color of the window as an integer value. Note Typical use ``exc.PythonShell({**globals(), **locals()}, background = 0x0, foreground = 0xFFFFFF)`` """ ... # ######################################################################### # 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 oper system's notation for input arguments but always return URL strings. ``URL``: the methods of the ``FileSystem`` service expect URL notation for input arguments an return URL strings. ``SYS``: the methods of the ``FileSystem`` service expect current operating system's notati for both input arguments and return strings. Once set, the ``FileNaming`` property remains unchanged either until the end of the ``LibreOf 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 = ...) -> boo """ 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 ``foldername``. 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[s """ 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 ext 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 and does not match any 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 u references. For instance, the path names ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` a 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.ForA ``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 = ..., title: str = ...) -> FILE: """ Display a dialog box to select a folder. Args ``defaultfolder``: the folder from which to start. Default = the last selected folder. ``title``: an optional text to display in the dialog header. 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 n 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, Gr - 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 comman Args ``filename``: the complete file name (in ``filesystem.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 en 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 Foundat 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-readabl 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 2 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 property. """ PythonVersion: str """ The version of the Python interpreter being used as a string in the format ``Python major.mi (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. """ UntitledPrefix: str """ The prefix used to name new documents (in English = "Untitled "). """ 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 timezo - 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 lang 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 the 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 lang 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 = ...) -> i """ 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 = ...) """ 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 lang 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 ``timezone``: 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 = ...) """ 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 gi 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 calculate 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 may be either - a string, a numeric value, a bool or a datetime.datetime instance - a tuple or a tuple of tuples combining those types - a com.sun.star.table.XCellRange UNO object Returns The value returned by the function as a scalar or a tuple of tuples. """ ... @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 acc 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', 'SOLARI """ 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 lo 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 wi 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 creat 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 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 functi 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 ``AtEndOfStr 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 susp 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 ru ``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 whol ``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 ide 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 p Y: int """ The Y coordinate of the active window, which is the distance to the top edge of the screen in pi This value does not consider window decorations added by your operating system, so even when th 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', 'FIREBIRD_EXTERNAL', 'CALC'] = ..., registrationname: str = ..., datafilename: str = ..., ) -> BASE: """ Create a new LibreOffice Base document embedding an empty database of the given type or finding its datasource in an external database file (Calc or Firebird). 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``, ``FIREBIRD``, ``FIREBIRD_EXTERNAL`` 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. ``datafilename``: when ``embeddeddatabase`` = ``CALC``, the name of the file containing the tables as Calc sheets. When ``embeddeddatabase`` = ``FIREBIRD_EXTERNAL``, the name of th Firebird external database file. The name of the file must be given in ``FileSystem.FileNamin 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 inv 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] = . """ 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 nam instead of the (RDBMS-dependent) normal surrounding character. ``SQL`` statements may be run in direct or indirect modes. In direct mode the statement is trans 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.XConnect 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 = ..., or ) -> 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`` keywor ``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[Union[float """ 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 = .. """ 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[Union[float, int, str, datetime.datetime]]: """ 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[Union[float, int, str, datetime.datetime]]: """ 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[Union[float """ 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 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 ``sqlcommand`` 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 ``transactionmode``: specifies the transaction mode. This argument must be one of the constants defined in ``com.sun.star.sdbc.TransactionIsola (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 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 to their corresponding Python data types. When the field type is undefined, the default value i 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 d 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 ` 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 i ``SQL`` statement. This property is expressed as a ``ORDER BY`` clause without the ``ORDER BY` ParentDatabase: DATABASE """ Returns the ``Database`` instance corresponding to the parent database of the current dat RowCount: int """ Returns the exact number of records in the dataset. Note that the evaluation of this propert 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`` stat 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 dat 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 reco 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 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 value 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 defin 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 result 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 ``SQ without the ``WHERE`` keyword. If an empty string is specified then the active Filter is remove IsAlive: bool """ Returns True when the datasheet component has not been closed by the user. """ LastRow: int """ Returns the number of rows in the datasheet. """ MenuHeaders: Tuple[str, ...] """ Returns the list, as a tuple of strings, of the menus present in the menubar. """ OrderBy: str """ Specifies the order in which records are shown expressed as the ``ORDER BY`` clause of a ``SQ without the ``ORDER BY`` keyword. If an empty string is specified then the active ``OrderBy`` i ParentDatabase: DATABASE """ Returns the ``Database`` instance corresponding to the parent database of the current dat 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 val ``TABLE``, ``QUERY`` or ``SQL``. """ XComponent: UNO """ Returns the ``com.sun.star.lang.XComponent`` ``UNO`` object representing the datashe 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 th 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 = ...) """ Creates a new menu entry in the data view window and returns a ``SFWidgets.Menu`` service insta 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.da """ 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 or dialogs created on-the-fly. Each instance of the ``Dialog`` class represents a single dial 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 execute 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. """ IsAlive: bool """ Returns True when the dialog is not terminated due to a user intervention. """ 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, DATASH """ 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[DIALOGCON """ 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 n 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`` c """ ... 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 ``CurrencyField`` 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 dropdown 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_Interf ``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 cell Default is ``False``. Returns A ``SFDialogs.SF_DialogControl`` instance or ``None``. """ ... def CreateTabPageContainer(self, controlname: str, place: Union[UNO, Tuple[int, int, int, int]], tabheaders: Tuple[str, ...], border: Literal["3D", "FLAT", "NONE"] = ..., ) -> Optional[DIALOGCONTROL]: """ Create a new control of type TabPageContainer in the actual dialog. Only one such creation is al per dialog. This type of control has no equivalent in the Basic IDE. The actual method may nevertheless be ap to a dialog built in the IDE. It is recommended for control stacking reasons to define a tab container control AFTER all or most other editable controls. The creation request is ignored if the dialog is already displayed. 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. ``tabheaders``: a tuple of strings to define the texts displayed in each respective tab. ``border``: "3D" (default), "FLAT" or "NONE". 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". ``mintime``: 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, - 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 ImportControl(self, sourcedialog: DIALOG, sourcename: str, controlname: str = ..., page: int = ..., offsetx: int = ..., offsety: int = ..., includeonproperties: bool = ...) -> DIALOGCONTROL: """ Import and duplicate an existing control of any type from one dialog to the actual dialog. The duplicated control is left unchanged. The new control can be renamed and relocated. The events, when defined, may optionally be imported too. Args ``sourcedialog``: a ``SFDialogs.SF_Dialog`` class instance. The dialog must be at least 'cr (with CreateScriptService). ``sourcename``: the name of the control to import. ``controlname``: the name of the new control. It must not exist yet. Default = id. ``sourcename ``page``: the page number of the new control. Default = 0. ``offsetx``, ``offsety``: the number of pixels to add to the source control coordinates in "Map AppFont" units. Default = 0. Their values may be negative. ``includeonproperties``: when True (default = False) include the OnXXX event properties in the import. Returns An instance of the ``SFDialogs.SF_DialogControl`` class or ``None``. Note Use the ``page`` argument to load in a multi-pages dialog individual smaller dialogs, one per page, designed in the Basic IDE. """ ... 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``dialo property. If the ``Page`` property is left unchanged, the default visible page is equal to ``0` meaning that no particular page is defined and all visible controls are displayed regardless o 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 five 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. - Group of radio buttons: defines a group of radio buttons that will control which page is visibl - Sequence of buttons: defines a set of buttons, each of which corresponding to a dialog page. Th - Previous/Next buttons: defines which buttons in the dialog that will be used to navigate to th - If the dialog contains a TabPageContainer control, the control always contributes implicit 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 as 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. Note It is possible to use more than one page management mechanism at the same time. They will all be synchronized to point to the actual dialog page number. """ ... 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 dialo 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, FixedLin 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`` cont 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)", "Stan "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY", "YYYY/MM/DD", "YY-MM-D "24h short", "24h long", "12h short", "12h long"] """ Get/set the format used to display dates and times. Applicable to ``DateField, TimeField, 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`` c ListIndex: int """ Get/set which item is selected in the control. Applicable to ``ComboBox, ListBox, TableCo controls. """ Locked: bool """ Get/set if the control is read-only.. Applicable to ``ComboBox, CurrencyField, DateFiel 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` OnNodeSelected: SCRIPT_URI """ Get/set the macro triggered by the ``Node in a tree control is selected`` event.""" OnTabSelected: SCRIPT_URI """ Get/set the macro triggered by the ``Tab in a TabPageContainer control is selected`` event OnTextChanged: SCRIPT_URI """ Get/set the macro triggered by the ``Text modified`` 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 othe 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`` cont 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, Forma PatternField, TextField`` controls. """ TripleState: bool """ Get/set whether the ``checkbox`` control may appear dimmed (grayed). """ URL: str """ Get/set the URL to open when clicking 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 k - ``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 `` - ``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 pos - ``ScrollBar``: int - Must be within the predefined bounds. - ``TableControl``: List[Any] - The data of the currently selected row. - ``TabPageContainer``: int, str - The index (starting from 1) of the selected tab. - ``TextField``: str - The text appearing in the control. - ``TimeField``: datetime.datetime. Not applicable to ``FixedLine, FixedText, GroupBox, Hyperlink, ImageControl`` and ``TreeC """ 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 ``tablecon XGridDataModel: UNO """ The UNO representation (``com.sun.star.awt.grid.XGridDataModel``) of a ``tablecontr XTreeDataModel: UNO """ The UNO representation (``com.sun.star.awt.tree.MutableTreeDataModel``) of a ``tree 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- 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_B """ CustomProperties: DICTIONARY """ Returns a ``ScriptForge.Dictionary`` object instance. After update, can be passed again 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. Docum are included. Note that they are specific to the type of document. As an example, a ``Calc`` docu 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 st 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. """ IsAlive: bool """ Returns True when the document component has not been closed by the user. """ 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-separated list of keywords. This property is not applicable to ``Base`` documents. """ MenuHeaders: Tuple[str, ...] """ Returns the list, as a tuple of strings, of the menus present in the menubar. """ 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` the document. """ XDocumentSettings: UNO """ A ``com.sun.star.XXX.DocumentSettings`` UNO object, where XXX is either ``sheet, text, ``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 ContextMenus(self, contextmenuname: str = ..., submenuchar: str = ... ) -> Union[CONTEXTMENU, Tuple[str, ...]]: """ Returns either a list of the available ContextMenu names in the actual document or a ``SFWidgets.SF_ContextMenu`` object instance. Args ``contextmenuname``: the usual name of one of the available context menus. ``submenuchar``: the delimiter used to create menu trees when calling the ``AddItem()`` method from the ``ContextMenu`` service. The default value is ">". Returns The list of available context menu names as a tuple of strings when ``contextmenuname`` is absent, a ``ContextMenu`` class instance otherwise. """ ... 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 created menu is only available during the current LibreOffice session and is not saved neit 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 famil 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 th 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 ``Fals """ ... 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()`` meth 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 c 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 appli Args ``filename``: identifies the file where to save. It must follow the ``SF_FileSystem.FileNam 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.FileNam 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 emp 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 a 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 - 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 Document 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 doc """ ... 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. """ ... 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()`` meth 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 `` 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 stri DefinedNames: Tuple[str, ...] """ The list of all names defined in the document, at global and sheet levels. """ Sheets: Tuple[str, ...] """ The list with the names of all existing sheets. """ 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 XRectangle(self, rangename: RANGE) -> XRectangle: """ A ``com.sun.star.awt.XRectangle`` UNO structure describing the area in pixels on the scr where the range is located. """ ... 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: SHEE ) -> 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 curren 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 AlignRange(self, targetrange: RANGE, alignment: str, filterformula: str = ..., filterscope: Literal['CELL', 'ROW', 'COLUMN'] = ..., ) -> RANGE: """ Align horizontally or vertically a range of cells. 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``. Args ``targetrange``: the cell or the range as a string in which cells should be re-aligned. ``alignment``: a string combining 1 or 2 of next characters. - L align Left - C align Center - R align Right - B align Bottom - M center vertically (Middle) - T align Top ``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$ ``filterscope``: determines how ``filterformula`` is expanded to the given range. The argument is mandatory if a ``filterformula`` is specified. Returns A string representing the modified area as a range of cells. """ ... def BorderRange(self, targetrange: RANGE, borders: str, filterformula: str = ..., filterscope: Literal['CELL', 'ROW', 'COLUMN'] = ..., ) -> RANGE: """ Apply within and around a range of cells a set of line borders. All the borders have the same standard width, style and color. Pre-existing border lines in the impacted cells, rows or columns are first cleared. Other cells in the range are left untouched. To clear the full range use Border = "" without the ``filterformula`` argument. Either the full range is updated or a selection based on a ``filterformula``. Args ``targetrange``: the cell or the range as a string on which borders should be applied. ``borders``: a string combining next characters. - B Bottom outer line - L Left outer line - T Top outer line - R Right outer line - H Horizontal inner line - V Vertical inner line - U diagonal bottom-Up line - D diagonal top-Down line ``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$ ``filterscope``: determines how ``filterformula`` is expanded to the given range. The argument is mandatory if a ``filterformula`` is specified. Returns A string representing the modified area as a range of cells. """ ... 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 ret |