ScriptForge.UI service

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

tip

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


Definitions

WindowName

A window can be designated using various ways:

The window name is case-sensitive.

Document object

The methods CreateDocument, CreateBaseDocument, GetDocument and OpenDocument, described below, generate document objects. When a window contains a document, an instance of the Document class represents that document. A counterexample the Basic IDE is not a document but is a window in our terminology. Additionally a document has a type: Calc, Impress, Writer, ...

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

tip

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


Service invocation

In Basic

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

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

Properties

Name

ReadOnly

Type

Description

ActiveWindow

Yes

String

a valid and unique WindowName for the currently active window. When the window cannot be identified, a zero-length string is returned.

Documents

Yes

String array

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


Constants

Name

Value

Description

MACROEXECALWAYS

2

Macros are always executed

MACROEXECNEVER

1

Macros are never executed

MACROEXECNORMAL

0

Macro execution depends on user settings


Example:

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

In Basic

      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
   
In Python

     svcUI = CreateScriptService("UI")
     sBasic = CreateScriptService("Basic")
     openDocs = svcUI.Documents()
     strDocs = "\n".join(openDocs)
     sBasic.MsgBox(strDocs)
   

List of Methods in the UI Service

Activate
CreateBaseDocument
CreateDocument (*)
GetDocument

Maximize
Minimize
OpenBaseDocument
OpenDocument (*)

Resize
SetStatusBar (*)
ShowProgressBar
WindowExists


warning

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


Activate

Make the specified window active. The method 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.

Syntax:

svc.Activate(windowname: str): bool

Parameters:

windowname: see the definitions above.

Example:

In Basic

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

      svcUI.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.

Syntax:

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

Parameters:

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) or "FIREBIRD".

registrationname : The name used to store the new database in the databases register. When = "" (default), no registration takes place. If the name already exists it is overwritten without warning.

Example:

In Basic

      Dim myBase As Object
      Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
   
In Python

     myBase = svcUI.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
   

CreateDocument (*)

Create a new LibreOffice document of a given type or based on a given template. The method returns a document object.

Syntax:

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

Parameters:

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

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.

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

Example:

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.

In Basic

      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"))
   
In Python

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

GetDocument

Returns a document object referring to either the active window or the given window.

Syntax:

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

Parameters:

windowname: See the definitions above. If this argument is absent, the active window is used.

Example:

In Basic

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

     myDoc = svcUI.GetDocument(r"C:\Documents\My file.odt")
   
tip

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


Maximize

Maximizes the active window or the given window.

Syntax:

svc.Maximize(windowname: str)

Parameters:

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

Example:

In Basic

      ui.Maximize("Untitled 1")
   
In Python

     svcUI.Maximize("Untitled 1")
   

Minimize

Minimizes the active window or the given window.

Syntax:

svc.Minimize(windowname: str)

Parameters:

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

Example:

In Basic

     ui.Minimize()
   
In Python

     svcUI.Minimize()
   

OpenBaseDocument

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

Syntax:

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

Parameters:

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

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.

Example:

In Basic

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

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

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


OpenDocument (*)

Opens an existing LibreOffice document with the given options. Returns a document object or one of its subclasses. The method returns Nothing (in Basic) / None (in Python) if the opening failed, even when the failure is caused by a user decision.

Syntax:

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

Parameters:

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.

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.

Example:

In Basic

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

     svcUI.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.

Syntax:

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

Parameters:

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.

Example:

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

In Basic

      ui.Resize(, ,500, 500)
   
In Python

     svcUI.Resize(width = 500, height = 500)
   
tip

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


SetStatusbar (*)

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 visible anymore. A call without arguments resets the status bar to its normal state.

Syntax:

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

Parameters:

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

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

Example:

In Basic

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

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

ShowProgressBar

Displays a non-modal dialog box. Specify its title, an explicatory text and a percentage of progress to be represented on a progressbar. The dialog will remain visible until a call to the method without arguments or until the user manually closes the dialog.

Syntax:

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

Parameters:

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.

Example:

In Basic

      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
   
In Python

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

WindowExists

Returns True if the given window could be identified.

Syntax:

svc.WindowExists(windowname: str): bool

Parameters:

windowname: see the definitions above.

Example:

In Basic

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

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

Please support us!