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.

Document object

The methods CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument 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.

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

Service invocation

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

In Basic


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

In Python


    from scriptforge import CreateScriptService
    ui = 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.
Height	Yes	Integer	Returns the height of the active window in pixels.
Width	Yes	Integer	Returns the width of the active window in pixels.
X	Yes	Integer	Returns the X coordinate of the active window, which is the distance to the left edge of the screen in pixels.
Y	Yes	Integer	Returns the Y coordinate of the active window, which is the distance to the top edge of the screen in pixels. This value does not consider window decorations added by your operating system, so even when the window is maximized this value may not be zero.

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


     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 (*) 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

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


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

CreateBaseDocument

Creates and stores a new Office 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 = '', opt calcfilename: 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), "FIREBIRD" or "CALC".

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.

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

Example:

In Basic


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

In Python


     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 Office 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 = ui.CreateDocument("Calc")
     fs = CreateScriptService("FileSystem")
     myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))

GetDocument

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

Syntax:

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

svc.GetDocument(windowname: uno): svc

Parameters:

windowname: See the definitions above. If this argument is absent, the active window is used. UNO objects of types com.sun.star.lang.XComponent or com.sun.star.comp.dba.ODatabaseDocument are also accepted. Thus passing ThisComponent or ThisDatabaseDocument as argument creates a new SFDocuments.Document, Base or Calc service.

Example:

In Basic


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

In Python


     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

Maximises 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 maximised.

Example:

In Basic


      ui.Maximize("Untitled 1")

In Python


     ui.Maximize("Untitled 1")

Minimize

Minimises 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 minimised.

Example:

In Basic


     ui.Minimize()

In Python


     ui.Minimize()

OpenBaseDocument

Open an existing Office 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.

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


     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 (*)

Opens an existing Office 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


     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 maximised, 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


     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 Office, refer to the Wiki page Development/DispatchCommands.

Syntax:

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

Parameters:

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. If nothing happens after the command call, then the command is probably wrong.

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

Example:

In Basic

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  = "Office Macros & Dialogs"
    ' LibName = "ScriptForge"
    ' Name = "SF-Session"
    ' Line = 600
    ui.RunCommand(".uno:BasicIDEAppear", "Document", "Office Macros & Dialogs", - 
                  "LibName", "ScriptForge", "Name", "SF-Session", "Line", 600)

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

In Python


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


    ui.RunCommand(".uno:BasicIDEAppear", "Document", "Office 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 = "Office Macros & Dialogs", \
                  LibName = "ScriptForge", Name = "SF-Session", Line = 600)

Each Office component has its own set of commands available. One easy way to learn commands is going to Tools - Customise - Keyboard. When you position your mouse over a function in the Function list, a tooltip will appear with the corresponding UNO command.

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):
         ui.SetStatusbar("Test:", i)
         sleep(0.05)
     ui.SetStatusbar()

ShowProgressBar

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

Syntax:

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

Parameters:

title : The title appearing on top of the dialogue 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):
         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.

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 ui.WindowExists(r"C:\Document\My file.odt"):
         # ...

ScriptForge.UI serviceDefinitions Service invocation Properties Constants Activate CreateBaseDocument CreateDocument (*)GetDocument Maximize Minimize OpenBaseDocument OpenDocument (*)Resize RunCommand SetStatusbar (*)ShowProgressBar WindowExists Related Topics