ScriptForge.UI service /text/sbasic/shared/03/sf_ui.xhp

UI service

ScriptForge.UI service

The UI (User Interface) service simplifies the identification and the manipulation of the different windows composing the whole LibreOffice application: Windows selection Windows moving and resizing Statusbar settings 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.

Definitions

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.

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. The implementation of the document objects class is done in the SFDocuments associated library. See its "Document" service.

Service invocation

Dim ui As Variant GlobalScope.BasicLibraries.loadLibrary("ScriptForge") Set 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.

Dim vDocs As Variant, sDoc As String vDocs = ui.Documents() For each sDoc In vDocs ' ... Next sDoc Methods Activate
CreateBaseDocument
CreateDocument (*)
GetDocument Maximize
Minimize
OpenBaseDocument
OpenDocument (*) Resize
SetStatusBar (*)
ShowProgressBar
WindowExists

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

Activate -------------------------------------------------------------------------------------------------------------------------- UI service;Activate

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.

ui.Activate(WindowName As String) As Boolean

WindowName: see the definitions above.

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

CreateBaseDocument -------------------------------------------------------------------------------------------------------------------------- UI service;CreateBaseDocument

CreateBaseDocument

Create and store a new LibreOffice Base document embedding an empty database of the given type. The method returns a document object.

ui.CreateBaseDocument(FileName As String, [EmbeddedDatabase As String], [RegistrationName As String]) As Object

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.

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

CreateDocument -------------------------------------------------------------------------------------------------------------------------- UI service;CreateDocument

CreateDocument (*)

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

ui.CreateDocument([DocumentType As String], [TemplateFile As STring], [Hidden As Boolean]) As Object

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.

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

GetDocument -------------------------------------------------------------------------------------------------------------------------- UI service;GetDocument

GetDocument

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

ui.GetDocument([WindowName As String]) As Object

WindowName: see the definitions above.

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

Maximize -------------------------------------------------------------------------------------------------------------------------- UI service;Maximize

Maximize

Maximizes the active window or the given window.

ui.Maximize([WindowName As String])

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

ui.Maximize("Untitled 1")

Minimize -------------------------------------------------------------------------------------------------------------------------- UI service;Minimize

Minimize

Minimizes the active window or the given window.

ui.Minimize([WindowName As String])

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

ui.Minimize()

OpenBaseDocument -------------------------------------------------------------------------------------------------------------------------- UI service;OpenBaseDocument

OpenBaseDocument

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

ui.OpenBaseDocument([FileName As String], [RegistrationName As String], [MacroExecution As Integer]) As Object

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.

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

OpenDocument -------------------------------------------------------------------------------------------------------------------------- UI service;OpenDocument

OpenDocument (*)

Open an existing LibreOffice document with the given options. Returns a document object or one of its subclasses or Null if the opening failed, including when due to a user decision.

ui.OpenDocument(FileName As String, [Password As String], [ReadOnly As Boolean], _ [Hidden As Boolean], [MacroExecution As Integer], [FilterName As String], [FilterOptions As String]) As Object

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.

Dim myDoc As Object, FSO As Object Set myDoc = ui.OpenDocument("C:\Temp\myFile.odt", MacroExecution := 1)

Resize -------------------------------------------------------------------------------------------------------------------------- UI service;Resize

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.

ui.Resize([Left As Long], [Top As Long], [Width As Long], [Height As Long])

Left, Top: Distances of the top-left corner from top and left edges of the screen. Width, Height: New dimensions of the window.

ui.Resize(10,,500) ' Top and Height are left unchanged

SetStatusbar -------------------------------------------------------------------------------------------------------------------------- UI service;SetStatusbar

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.

ui.SetStatusbar([Text As String], [Percentage As Integer])

Text: An optional text to be displayed in front of the progress bar. Percentage: an optional degree of progress between 0 and 100.

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

ShowProgressBar -------------------------------------------------------------------------------------------------------------------------- UI service;ShowProgressBar

ShowProgressBar

Display a non-modal dialog box. Specify its title, an explicatory text and a percentage of progress represented on a progressbar. The box will remain visible until a call to the method without argument, or until the end of the currently running macro.

ui.ShowProgressBar([Title As String], [Text As String], [Percentage As Integer])

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.

Dim i As Integer For i = 0 To 100 ui.ShowProgressBar(, "Progress ..." & i & "/100", i) Wait 50 Next i ui.ShowProgressBar

WindowExists -------------------------------------------------------------------------------------------------------------------------- UI service;WindowExists

WindowExists

Returns True if the given window could be identified.

ui.WindowExists(WindowName As String) As Boolean

WindowName: see the definitions above.

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