Tartalom

# ScriptForge.UI service

The UI (User Interface) service simplifies the identification and the manipulation of the different windows composing the whole LibreOffice application:

- Ablak kiválasztása

- Windows moving and resizing

- Állapotsor beállításai

- Display of a floating progress bar

- Creation of new windows

- Access to the underlying "documents"

The UI service is the starting point to open, create or access to the content of new or existing documents from a user script.

## Meghatározások

### WindowName

A window can be designated using various ways:

- 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"

The window name is case-sensitive.

### Dokumentumobjektum

Az alább ismertetett CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument és OpenDocument metódusok dokumentumobjektumokat hoznak létre. Amikor egy ablak dokumentumot tartalmaz, a Document osztály egy példánya képviseli a dokumentumot. Ellenpéldaként a Basic IDE nem dokumentum, hanem a mi terminológiánk szerint ablak. Továbbá egy dokumentumnak van egy típusa: Calc, Impress, Writer, ...

The specific properties and methods applicable on documents are implemented in a document class.

The implementation of the document objects class is done in the SFDocuments associated library. See its "Document" service.

## A szolgáltatás igénybevétele

Before using the UI service the ScriptForge library needs to be loaded or imported:

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService

##### A Basic nyelvben

        Dim ui As Variant
        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Set ui = CreateScriptService("UI")

##### A Python nyelvben

        from scriptforge import CreateScriptService
        ui = CreateScriptService("UI")

## Tulajdonságok

Név | Írásvédett | Típus | Leírás
--- | --- | --- | ---
ActiveWindow | Igen | String | a valid and unique WindowName for the currently active window. When the window cannot be identified, a zero-length string is returned.
Height | Igen | Integer | Returns the height of the active window in pixels.
Width | Igen | Integer | Returns the width of the active window in pixels.
X | Igen | Integer | Returns the X coordinate of the active window, which is the distance to the left edge of the screen in pixels.
Y | Igen | Integer | Visszaadja az aktív ablak Y-koordinátáját, amely a képernyő felső szélétől mért távolságot jelenti pixelben. Ez az érték nem veszi figyelembe az operációs rendszer által hozzáadott ablakdekorációkat, így még akkor sem biztos, hogy ez az érték nulla, ha az ablak maximalizálva van.

## Állandók

Név | Érték | Leírás
--- | --- | ---
MACROEXECALWAYS | 2 | Macros are always executed
MACROEXECNEVER | 1 | Macros are never executed
MACROEXECNORMAL | 0 | Macro execution depends on user settings

### Példa:

The examples below show a MsgBox with the names of all currently open documents.

##### A Basic nyelvben

         Dim openDocs As Object, strDocs As String
         Set openDocs = ui.Documents()
         strDocs = openDocs(0)
         For i = 1 To UBound(openDocs)
             strDocs = strDocs & Chr(10) & openDocs(i)
         Next i
         MsgBox strDocs

##### A Python nyelvben

         ui = CreateScriptService("UI")
         bas = CreateScriptService("Basic")
         openDocs = ui.Documents()
         strDocs = "\n".join(openDocs)
         bas.MsgBox(strDocs)

List of Methods in the UI Service
Activate CreateBaseDocument CreateDocument (*) Documents GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) Resize | RunCommand SetStatusBar (*) ShowProgressBar WindowExists

Note, as an exception, that the methods marked (*) are not applicable to Base documents.

## Activate

A megadott ablak aktívvá tétele. A metódus True értéket ad vissza, ha a megadott ablak megtalálható és aktiválható. A tényleges felhasználói felületen nem történik változás, ha nincs a kiválasztásnak megfelelő ablak.

### Szintaxis:

svc.Activate(windowname: str): bool

### Paraméterek:

windowname: see the definitions above.

### Példa:

##### A Basic nyelvben

          ui.Activate("C:\Documents\My file.odt")

##### A Python nyelvben

          ui.Activate(r"C:\Documents\My file.odt")

## CreateBaseDocument

Creates and stores a new LibreOffice Base document embedding an empty database of the given type. The method returns a Document service instance.

### Szintaxis:

svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc

### Paraméterek:

filename : Identifies the file to create. It must follow the SF_FileSystem.FileNaming notation. If the file already exists, it is overwritten without warning.

embeddeddatabase : Either "HSQLDB" (default), "FIREBIRD" or "CALC".

registrationname : Az új adatbázisnak az adatbázis-nyilvántartásban való tárolására használt név. Ha = "" (alapértelmezett), akkor nem történik regisztráció. Ha a név már létezik, akkor figyelmeztetés nélkül felülíródik.

calcfilename : Only when embeddeddatabase = "CALC", calcfilename represents the file containing the tables as Calc sheets. The file must exist or an error is raised.

### Példa:

##### A Basic nyelvben

          Dim myBase As Object, myCalcBase As Object
          Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
          Set myCalcBase = ui.CreateBaseDocument("C:\Databases\MyCalcBaseFile.odb", _
              "CALC", , "C:\Databases\MyCalcFile.ods")

##### A Python nyelvben

         myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
         myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
             "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")

## CreateDocument (*)

Create a new LibreOffice document of a given type or based on a given template. The method returns an instance of the document class or one of its subclasses (Calc, Writer).

### Szintaxis:

svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc

### Paraméterek:

documenttype : "Calc", "Writer", etc. If absent, the templatefile argument must be present.

templatefile : A sablon teljes FileName értéke, amelyre az új dokumentumot építeni kell. Ha a fájl nem létezik, az argumentumot figyelmen kívül hagyjuk. A FileSystem szolgáltatás a TemplatesFolder és UserTemplatesFolder tulajdonságokkal segít az argumentum felépítésében.

hidden: if True, open the new document in the background (default = False). To use with caution: activation or closure afterwards can only happen programmatically.

### Példa:

In both examples below, the first call to CreateDocument method creates a blank Calc document, whereas the second creates a document from a template file.

##### A Basic nyelvben

          Dim myDoc1 As Object, myDoc2 As Object, FSO As Object
          Set myDoc1 = ui.CreateDocument("Calc")
          Set FSO = CreateScriptService("FileSystem")
          Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))

##### A Python nyelvben

         myDoc1 = ui.CreateDocument("Calc")
         fs = CreateScriptService("FileSystem")
         myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))

## Documents

The list of the currently open documents. Special windows are ignored. This list consists of a zero-based one dimensional array either of filenames - using ScriptForge.FileSystem.FileNaming notation - or of window titles for unsaved documents.

### Szintaxis:

svc.Documents(): str[1..*]

### Példa:

In both examples below, the method may return an empty array if there are no documents open.

##### A Basic nyelvben

          Dim docList As Variant
          docList = ui.Documents

##### A Python nyelvben

         docList = ui.Documents()

## GetDocument

Returns an instance of the Document class or one of its subclasses (Calc, Writer, Base, FormDocument) referring to either a given window or the active document.

### Szintaxis:

svc.GetDocument(windowname: str = ''): svc

svc.GetDocument(windowname: uno): svc

### Paraméterek:

windowname: Lásd a fentebb definícióit. Ha ez az argumentum hiányzik, az aktív ablakot használja a rendszer. A com.sun.star.lang.XComponent vagy com.sun.star.comp.dba.ODatabaseDocument típusú UNO objektumok is elfogadottak. Így a ThisComponent vagy ThisDatabaseDocument argumentumként való átadása egy új SFDocuments.Document, Base vagy Calc szolgáltatást hoz létre.

### Példa:

##### A Basic nyelvben

          Dim myDoc As Object
          Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
          Set myBase = ui.GetDocument(ThisDatabaseDocument)

##### A Python nyelvben

         from scriptforge import CreateScriptService
         bas = CreateScriptService("Basic")
         myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
         myDoc = ui.GetDocument(bas.ThisComponent)

To access the name of the currently active window, refer to the ActiveWindow property.

## Maximize

Maximizes the active window or the given window.

### Szintaxis:

svc.Maximize(windowname: str)

### Paraméterek:

windowname: see the definitions above. If this argument is absent, the active window is maximized.

### Példa:

##### A Basic nyelvben

          ui.Maximize("Untitled 1")

##### A Python nyelvben

         ui.Maximize("Untitled 1")

## Minimize

Minimizes the active window or the given window.

### Szintaxis:

svc.Minimize(windowname: str)

### Paraméterek:

windowname: see the definitions above. If this argument is absent, the active window is minimized.

### Példa:

##### A Basic nyelvben

         ui.Minimize()

##### A Python nyelvben

         ui.Minimize()

## OpenBaseDocument

Open an existing LibreOffice Base document. The method returns a Base object.

### Szintaxis:

svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc

### Paraméterek:

filename: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation.

registrationname: The name to use to find the database in the databases register. It is ignored if FileName <> "".

macroexecution: 0 = behaviour is defined by the user configuration, 1 = macros are not executable, 2 = macros are executable. Default is 0.

### Példa:

##### A Basic nyelvben

          Dim myBase As Object
          Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)

##### A Python nyelvben

         myBase = ui.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = ui.MACROEXECALWAYS)

To improve code readability you can use predefined constants for the macroexecution argument, as in the examples above.

## OpenDocument (*)

Megnyit egy meglévő LibreOffice dokumentumot a megadott beállításokkal. Visszaad egy dokumentumobjektumot vagy annak egyik alosztályát. A metódus Nothing (BASIC-ben) vagy None (Python-ban) eredményt ad vissza, ha a megnyitás sikertelen, még akkor is, ha a sikertelenséget felhasználói döntés okozta.

### Szintaxis:

svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc

### Paraméterek:

filename: Identifies the file to open. It must follow the FileNaming notation of the FileSystem service.

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: Default = False.

hidden: if True, open the new document in the background (default = False). To use with caution: activation or closure afterwards can only happen programmatically.

macroexecution: 0 = behaviour is defined by the user configuration, 1 = macros are not executable, 2 = macros are executable. Default is 0.

filtername: The name of a filter that should be used for loading the document. If present, the filter must exist.

filteroptions: An optional string of options associated with the filter.

### Példa:

##### A Basic nyelvben

          Dim myDoc As Object, FSO As Object
          Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)

##### A Python nyelvben

         myDoc = ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)

## Resize

Resizes and/or moves the active window. Absent and negative arguments are ignored. If the window is minimized or maximized, calling Resize without arguments restores it.

### Szintaxis:

svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)

### Paraméterek:

left, top: Distances of the top-left corner from top and left edges of the screen, in pixels.

width, height: New dimensions of the window, in pixels.

### Példa:

In the following examples, the width and height of the window are changed while top and left are left unchanged.

##### A Basic nyelvben

          ui.Resize(Width := 500, Height := 500)

##### A Python nyelvben

         ui.Resize(width = 500, height = 500)

To resize a window that is not active, first activate it using the Activate method.

## RunCommand

Runs a UNO command on the current window. A few typical commands are: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

Commands can be run with or without arguments. Arguments are not validated before running the command. If the command or its arguments are invalid, then nothing will happen.

For a complete list of UNO commands that can be run in LibreOffice, refer to the Wiki page Development/DispatchCommands.

### Szintaxis:

svc.RunCommand(command: str, [args: any])

### Paraméterek:

command: Nagy- és kisbetűket megkülönböztető karakterlánc, amely az UNO-parancs nevét tartalmazza. A ".uno:" előtag szerepeltetése a parancsban opcionális. Maga a parancs helyességét nem ellenőrzi a rendszer. Ha a parancshívás után nem történik semmi, akkor a parancs valószínűleg hibás.

args: For each argument to be passed to the command, specify a pair containing the argument name and value.

### Példa:

##### A Basic nyelvben

The following example runs the .uno:About command in the current window.

        Set ui = CreateScriptService("UI")
        ui.RunCommand("About")

Below is an example that runs the UNO command .uno:BasicIDEAppear and passes the arguments required to open the Basic IDE at a specific line of a module.

        ' Arguments passed to the command:
        ' Document  = "LibreOffice Macros & Dialogs"
        ' LibName = "ScriptForge"
        ' Name = "SF_Session"
        ' Line = 600
        ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", _
                      "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)

Note that calling the command BasicIDEAppear without arguments will simply open the Basic IDE.

##### A Python nyelvben

        ui = CreateScriptService("UI")
        ui.RunCommand("About")

        ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", \
                      "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)

In Python it is also possible to call RunCommand using keyword arguments:

        ui.RunCommand(".uno:BasicIDEAppear", Document = "LibreOffice Macros & Dialogs", \
                      LibName = "ScriptForge", Name = "SF_Session", Line = 600)

Minden egyes LibreOffice komponensnek saját parancskészlete áll rendelkezésre. A parancsok megismerésének egyik egyszerű módja az Eszközök - Testreszabás - Billentyűzet menüpontban található. Ha az egeret a Funkció listában egy funkció fölé helyezi, megjelenik egy helyi súgó a megfelelő UNO-paranccsal.

## SetStatusbar (*)

Egy szöveg és egy folyamatjelző megjelenítése az aktív ablak állapotsorában. Ugyanazon makrófuttatás minden további hívása ugyanannak az ablaknak az állapotsorára hivatkozik, még akkor is, ha az ablak már nem látható. Az argumentumok nélküli hívás visszaállítja az állapotsort a normál állapotba.

### Szintaxis:

svc.SetStatusbar(text: str = '', percentage: int = -1)

### Paraméterek:

text: An optional text to be displayed in front of the progress bar.

percentage: an optional degree of progress between 0 and 100.

### Példa:

##### A Basic nyelvben

          Dim i As Integer
          For i = 0 To 100
              ui.SetStatusbar("Progress ...", i)
              Wait 50
          Next i
          ' Resets the statusbar
          ui.SetStatusbar

##### A Python nyelvben

         from time import sleep
         for i in range(101):
             ui.SetStatusbar("Test:", i)
             sleep(0.05)
         ui.SetStatusbar()

## ShowProgressBar

Megjelenít egy nem modális párbeszédablakot. Adja meg a címét, egy magyarázó szöveget és a haladás százalékos arányát, amely a folyamatjelzőn fog megjelenni. A párbeszédablak mindaddig látható marad, amíg a metódus argumentumok nélküli meghívásra kerül vagy a felhasználó manuálisan be nem zárja a párbeszédablakot.

### Szintaxis:

svc.ShowProgressBar(title: str = '', text: str = '', percentage: int = -1)

### Paraméterek:

title : The title appearing on top of the dialog box. Default = "ScriptForge".

text: An optional text to be displayed above the progress bar.

percentage: an optional degree of progress between 0 and 100.

### Példa:

##### A Basic nyelvben

          Dim i As Integer
          For i = 0 To 100
              ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
              Wait 50
          Next i
          ' Closes the Progress Bar window
          ui.ShowProgressBar

##### A Python nyelvben

         from time import sleep
         for i in range(101):
             ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
             sleep(0.05)
         # Closes the Progress Bar window
         ui.ShowProgressBar()

## WindowExists

Returns True if the given window could be identified.

### Szintaxis:

svc.WindowExists(windowname: str): bool

### Paraméterek:

windowname: see the definitions above.

### Példa:

##### A Basic nyelvben

          If ui.WindowExists("C:\Document\My file.odt") Then
              ' ...

##### A Python nyelvben

         if ui.WindowExists(r"C:\Document\My file.odt"):
             # ...

Kapcsolódó témakörök

ScriptForge.Basic service

SFDocuments.Calc service

SFDocuments.Document service