| blob | ca6bf79e40ab859915232566b8a905a217c80d8b |
3 <script:module xmlns:script="http://openoffice.org/2000/script" script:name="SF_UI" script:language="StarBasic" script:moduleType="normal">REM =======================================================================================================================
4 REM === The ScriptForge library and its associated libraries are part of the LibreOffice project. ===
5 REM === Full documentation is available on https://help.libreoffice.org/ ===
6 REM =======================================================================================================================
8 Option Compatible
9 Option Explicit
11 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
12 ''' SF_UI
13 ''' =====
14 ''' Singleton class module for the identification and the manipulation of the
15 ''' different windows composing the whole LibreOffice application:
16 ''' - Windows selection
17 ''' - Windows moving and resizing
18 ''' - Statusbar settings
19 ''' - Creation of new windows
21 '''
22 ''' WindowName: how to designate a window. It can be either
23 ''' a full FileName given in the notation indicated by the current value of SF_FileSystem.FileNaming
24 ''' or the last component of the full FileName or even only its BaseName
25 ''' or the title of the window
27 ''' or one of the special windows "BASICIDE" and "WELCOMESCREEN"
28 ''' The window search is case-sensitive
29 '''
30 ''' Service invocation example:
31 ''' Dim ui As Variant
34 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
36 REM ================================================================== EXCEPTIONS
39 Const DOCUMENTCREATIONERROR = "DOCUMENTCREATIONERROR" ' Incoherent arguments, new document could not be created
40 Const DOCUMENTOPENERROR = "DOCUMENTOPENERROR" ' Document could not be opened, check the arguments
43 REM ============================================================= PRIVATE MEMBERS
45 Type Window
46 Component As Object ' com.sun.star.lang.XComponent
47 Frame As Object ' com.sun.star.comp.framework.Frame
48 WindowName As String ' Object Name
49 WindowTitle As String ' Only mean to identify new documents
50 WindowFileName As String ' URL of file name
51 DocumentType As String ' Writer, Calc, ...
52 End Type
54 ' The progress/status bar of the active window
57 REM ============================================================ MODULE CONSTANTS
59 ' Special windows
71 ' Window subtypes - Not supported yet
77 ' Macro execution modes
82 REM ===================================================== CONSTRUCTOR/DESTRUCTOR
84 REM -----------------------------------------------------------------------------
85 Public Function Dispose() As Variant
86 Set Dispose = Nothing
87 End Function ' ScriptForge.SF_UI Explicit destructor
89 REM ================================================================== PROPERTIES
91 REM -----------------------------------------------------------------------------
92 Public Function ActiveWindow() As String
93 ''' Returns a valid WindowName for the currently active window
96 Dim vWindow As Window ' A component
97 Dim oComp As Object ' com.sun.star.lang.XComponent
99 Set oComp = StarDesktop.CurrentComponent
100 If Not IsNull(oComp) Then
101 vWindow = SF_UI._IdentifyWindow(oComp)
102 With vWindow
104 ActiveWindow = SF_FileSystem._ConvertFromUrl(.WindowFileName)
106 ActiveWindow = .WindowName
108 ActiveWindow = .WindowTitle
109 Else
110 ActiveWindow = ""
111 End If
112 End With
113 End If
115 End Function ' ScriptForge.SF_UI.ActiveWindow
117 REM -----------------------------------------------------------------------------
118 Property Get MACROEXECALWAYS As Integer
119 ''' Macros are always executed
120 MACROEXECALWAYS = cstMACROEXECALWAYS
121 End Property ' ScriptForge.SF_UI.MACROEXECALWAYS
123 REM -----------------------------------------------------------------------------
124 Property Get MACROEXECNEVER As Integer
125 ''' Macros are not executed
126 MACROEXECNEVER = cstMACROEXECNEVER
127 End Property ' ScriptForge.SF_UI.MACROEXECNEVER
129 REM -----------------------------------------------------------------------------
130 Property Get MACROEXECNORMAL As Integer
131 ''' Default, execution depends on user configuration and choice
132 MACROEXECNORMAL = cstMACROEXECNORMAL
133 End Property ' ScriptForge.SF_UI.MACROEXECNORMAL
135 REM -----------------------------------------------------------------------------
136 Property Get ObjectType As String
137 ''' Only to enable object representation
139 End Property ' ScriptForge.SF_UI.ObjectType
141 REM ===================================================================== METHODS
143 REM -----------------------------------------------------------------------------
144 Public Function Activate(Optional ByVal WindowName As Variant) As Boolean
145 ''' Make the specified window active
146 ''' Args:
147 ''' WindowName: see definitions
148 ''' Returns:
149 ''' True if the given window is found and can be activated
150 ''' There is no change in the actual user interface if no window matches the selection
151 ''' Examples:
154 Dim bActivate As Boolean ' Return value
155 Dim oEnum As Object ' com.sun.star.container.XEnumeration
156 Dim oComp As Object ' com.sun.star.lang.XComponent
157 Dim vWindow As Window ' A single component
158 Dim oContainer As Object ' com.sun.star.awt.XWindow
162 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
163 bActivate = False
165 Check:
166 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
167 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
169 End If
171 Try:
172 Set oEnum = StarDesktop.Components().createEnumeration
173 Do While oEnum.hasMoreElements
174 Set oComp = oEnum.nextElement
175 vWindow = SF_UI._IdentifyWindow(oComp)
176 With vWindow
177 ' Does the current window match the arguments ?
178 If (Len(.WindowFileName) > 0 And .WindowFileName = SF_FileSystem._ConvertToUrl(WindowName)) _
181 Set oContainer = vWindow.Frame.ContainerWindow
182 With oContainer
183 If .isVisible() = False Then .setVisible(True)
184 .IsMinimized = False
185 .setFocus()
186 .toFront() ' Force window change in Linux
188 End With
189 bActivate = True
190 Exit Do
191 End If
192 End With
193 Loop
195 Finally:
196 Activate = bActivate
197 SF_Utils._ExitFunction(cstThisSub)
198 Exit Function
199 Catch:
200 GoTo Finally
201 End Function ' ScriptForge.SF_UI.Activate
203 REM -----------------------------------------------------------------------------
204 Public Function CreateBaseDocument(Optional ByVal FileName As Variant _
205 , Optional ByVal EmbeddedDatabase As Variant _
206 , Optional ByVal RegistrationName As Variant _
207 ) As Object
208 ''' Create a new LibreOffice Base document embedding an empty database of the given type
209 ''' Args:
210 ''' FileName: Identifies the file to create. It must follow the SF_FileSystem.FileNaming notation
211 ''' If the file already exists, it is overwritten without warning
212 ''' EmbeddedDatabase: either "HSQLDB" (default) or "FIREBIRD"
213 ''' RegistrationName: the name used to store the new database in the databases register
215 ''' If the name already exists it is overwritten without warning
216 ''' Returns:
217 ''' A SFDocuments.SF_Document object or one of its subclasses
218 ''' Examples:
219 ''' Dim myBase As Object
220 ''' Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
222 Dim oCreate As Variant ' Return value
223 Dim oDBContext As Object ' com.sun.star.sdb.DatabaseContext
224 Dim oDatabase As Object ' com.sun.star.comp.dba.ODatabaseSource
225 Dim oComp As Object ' Loaded component com.sun.star.lang.XComponent
226 Dim sFileName As String ' Alias of FileName
227 Dim FSO As Object ' Alias for FileSystem service
230 Const cstSubArgs = "FileName, [EmbeddedDatabase=""HSQLDB""|""FIREBIRD""], [RegistrationName=""""]"
232 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
233 Set oCreate = Nothing
235 Check:
236 If IsMissing(EmbeddedDatabase) Or IsEmpty(EmbeddedDatabase) Then EmbeddedDatabase = "HSQLDB"
237 If IsMissing(RegistrationName) Or IsEmpty(RegistrationName) Then RegistrationName = ""
238 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
240 If Not SF_Utils._Validate(EmbeddedDatabase, "EmbeddedDatabase", V_STRING, Array("HSQLDB", "FIREBIRD")) Then GoTo Finally
241 If Not SF_Utils._Validate(RegistrationName, "RegistrationName", V_STRING) Then GoTo Finally
242 End If
244 Try:
246 With oDBContext
247 Set oDatabase = .createInstance()
249 ' Create empty Base document
251 sFileName = FSO._ConvertToUrl(FileName)
252 ' An existing file is overwritten without warning
253 If FSO.FileExists(FileName) Then FSO.DeleteFile(FileName)
254 If FSO.FileExists(FileName & ".lck") Then FSO.DeleteFile(FileName & ".lck")
255 oDatabase.DatabaseDocument.storeAsURL(sFileName, Array(SF_Utils._MakePropertyValue("Overwrite", True)))
256 ' Register database if requested
258 If .hasRegisteredDatabase(RegistrationName) Then
259 .changeDatabaseLocation(RegistrationName, sFileName)
260 Else
261 .registerDatabaseLocation(RegistrationName, sFileName)
262 End If
263 End If
264 End With
266 Set oCreate = OpenBaseDocument(FileName)
268 Finally:
269 Set CreateBaseDocument = oCreate
270 SF_Utils._ExitFunction(cstThisSub)
271 Exit Function
272 Catch:
273 GoTo Finally
274 End Function ' ScriptForge.SF_UI.CreateBaseDocument
276 REM -----------------------------------------------------------------------------
277 Public Function CreateDocument(Optional ByVal DocumentType As Variant _
278 , Optional ByVal TemplateFile As Variant _
279 , Optional ByVal Hidden As Variant _
280 ) As Object
281 ''' Create a new LibreOffice document of a given type or based on a given template
282 ''' Args:
283 ''' DocumentType: "Calc", "Writer", etc. If absent, a TemplateFile must be given
284 ''' TemplateFile: the full FileName of the template to build the new document on
285 ''' If the file does not exist, the argument is ignored
286 ''' The "FileSystem" service provides the TemplatesFolder and UserTemplatesFolder
287 ''' properties to help to build the argument
288 ''' Hidden: if True, open in the background (default = False)
289 ''' To use with caution: activation or closure can only happen programmatically
290 ''' Returns:
291 ''' A SFDocuments.SF_Document object or one of its subclasses
292 ''' Exceptions:
293 ''' DOCUMENTCREATIONERROR Wrong arguments
294 ''' Examples:
295 ''' Dim myDoc1 As Object, myDoc2 As Object, FSO As Object
298 ''' Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))
300 Dim oCreate As Variant ' Return value
301 Dim vProperties As Variant ' Array of com.sun.star.beans.PropertyValue
302 Dim bTemplateExists As Boolean ' True if TemplateFile is valid
303 Dim sNew As String ' File url
304 Dim oComp As Object ' Loaded component com.sun.star.lang.XComponent
307 Const cstSubArgs = "[DocumentType=""""], [TemplateFile=""""], [Hidden=False]"
309 '>>> If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
310 Set oCreate = Nothing
312 Check:
313 If IsMissing(DocumentType) Or IsEmpty(DocumentType) Then DocumentType = ""
314 If IsMissing(TemplateFile) Or IsEmpty(TemplateFile) Then TemplateFile = ""
315 If IsMissing(Hidden) Or IsEmpty(Hidden) Then Hidden = False
317 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
319 , Array("", BASEDOCUMENT, CALCDOCUMENT, DRAWDOCUMENT _
320 , IMPRESSDOCUMENT, MATHDOCUMENT, WRITERDOCUMENT)) Then GoTo Finally
323 End If
325 If Len(DocumentType) + Len(TemplateFile) = 0 Then GoTo CatchError
326 If Len(TemplateFile) > 0 Then bTemplateExists = SF_FileSystem.FileExists(TemplateFile) Else bTemplateExists = False
327 If Len(DocumentType) = 0 Then
328 If Not bTemplateExists Then GoTo CatchError
329 End If
331 Try:
332 If bTemplateExists Then sNew = SF_FileSystem._ConvertToUrl(TemplateFile) Else sNew = cstDocType & LCase(DocumentType)
333 vProperties = Array( _
336 )
338 If Not IsNull(oComp) Then Set oCreate = CreateScriptService("SFDocuments.Document", oComp)
340 Finally:
341 Set CreateDocument = oCreate
342 SF_Utils._ExitFunction(cstThisSub)
343 Exit Function
344 Catch:
345 GoTo Finally
346 CatchError:
347 SF_Exception.RaiseFatal(DOCUMENTCREATIONERROR, "DocumentType", DocumentType, "TemplateFile", TemplateFile)
348 GoTo Finally
349 End Function ' ScriptForge.SF_UI.CreateDocument
351 REM -----------------------------------------------------------------------------
352 Public Function Documents() As Variant
353 ''' Returns the list of the currently open documents. Special windows are ignored.
354 ''' Returns:
356 ''' or of window titles for unsaved documents
357 ''' Examples:
358 ''' Dim vDocs As Variant, sDoc As String
359 ''' vDocs = ui.Documents()
360 ''' For each sDoc In vDocs
361 ''' ...
363 Dim vDocuments As Variant ' Return value
364 Dim oEnum As Object ' com.sun.star.container.XEnumeration
365 Dim oComp As Object ' com.sun.star.lang.XComponent
366 Dim vWindow As Window ' A single component
368 Const cstSubArgs = ""
370 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
371 vDocuments = Array()
373 Check:
374 SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
376 Try:
377 Set oEnum = StarDesktop.Components().createEnumeration
378 Do While oEnum.hasMoreElements
379 Set oComp = oEnum.nextElement
380 vWindow = SF_UI._IdentifyWindow(oComp)
381 With vWindow
383 vDocuments = SF_Array.Append(vDocuments, SF_FileSystem._ConvertFromUrl(.WindowFileName))
385 vDocuments = SF_Array.Append(vDocuments, .WindowTitle)
386 End If
387 End With
388 Loop
390 Finally:
391 Documents = vDocuments
392 SF_Utils._ExitFunction(cstThisSub)
393 Exit Function
394 Catch:
395 GoTo Finally
396 End Function ' ScriptForge.SF_UI.Documents
398 REM -----------------------------------------------------------------------------
399 Public Function GetDocument(Optional ByVal WindowName As Variant) As Variant
400 ''' Returns a SFDocuments.Document object referring to the active window or the given window
401 ''' Args:
402 ''' WindowName: see definitions. If absent the active window is considered
403 ''' Exceptions:
404 ''' DOCUMENTERROR The targeted window could not be found
405 ''' Examples:
406 ''' Dim oDoc As Object
407 ''' Set oDoc = ui.GetDocument
408 ''' oDoc.Save()
410 Dim oDocument As Object ' Return value
414 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
415 Set oDocument = Nothing
417 Check:
418 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
419 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
421 End If
423 Try:
425 If IsNull(oDocument) Then GoTo CatchDeliver
427 Finally:
428 Set GetDocument = oDocument
429 SF_Utils._ExitFunction(cstThisSub)
430 Exit Function
431 Catch:
432 GoTo Finally
433 CatchDeliver:
435 GoTo Finally
436 End Function ' ScriptForge.SF_UI.GetDocument
438 REM -----------------------------------------------------------------------------
439 Public Function GetProperty(Optional ByVal PropertyName As Variant) As Variant
440 ''' Return the actual value of the given property
441 ''' Args:
442 ''' PropertyName: the name of the property as a string
443 ''' Returns:
444 ''' The actual value of the property
445 ''' Exceptions
446 ''' ARGUMENTERROR The property does not exist
451 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
452 GetProperty = Null
454 Check:
455 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
456 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
457 End If
459 Try:
460 Select Case UCase(PropertyName)
462 Case Else
463 End Select
465 Finally:
466 SF_Utils._ExitFunction(cstThisSub)
467 Exit Function
468 Catch:
469 GoTo Finally
470 End Function ' ScriptForge.SF_UI.GetProperty
472 REM -----------------------------------------------------------------------------
473 Public Sub Maximize(Optional ByVal WindowName As Variant)
474 ''' Maximizes the active window or the given window
475 ''' Args:
476 ''' WindowName: see definitions. If absent the active window is considered
477 ''' Examples:
478 ''' ui.Maximize
479 ''' ...
481 Dim oEnum As Object ' com.sun.star.container.XEnumeration
482 Dim oComp As Object ' com.sun.star.lang.XComponent
483 Dim vWindow As Window ' A single component
484 Dim oContainer As Object ' com.sun.star.awt.XWindow
485 Dim bFound As Boolean ' True if window found
489 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
491 Check:
492 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
493 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
495 End If
497 Try:
498 bFound = False
500 Set oEnum = StarDesktop.Components().createEnumeration
501 Do While oEnum.hasMoreElements And Not bFound
502 Set oComp = oEnum.nextElement
503 vWindow = SF_UI._IdentifyWindow(oComp)
504 With vWindow
505 ' Does the current window match the arguments ?
509 End With
510 Loop
511 Else
512 vWindow = SF_UI._IdentifyWindow(StarDesktop.CurrentComponent)
513 bFound = True
514 End If
516 If bFound Then
517 Set oContainer = vWindow.Frame.ContainerWindow
518 oContainer.IsMaximized = True
519 End If
521 Finally:
522 SF_Utils._ExitFunction(cstThisSub)
523 Exit Sub
524 Catch:
525 GoTo Finally
526 End Sub ' ScriptForge.SF_UI.Maximize
528 REM -----------------------------------------------------------------------------
529 Public Sub Minimize(Optional ByVal WindowName As Variant)
530 ''' Minimizes the current window or the given window
531 ''' Args:
532 ''' WindowName: see definitions. If absent the current window is considered
533 ''' Examples:
535 ''' ...
537 Dim oEnum As Object ' com.sun.star.container.XEnumeration
538 Dim oComp As Object ' com.sun.star.lang.XComponent
539 Dim vWindow As Window ' A single component
540 Dim oContainer As Object ' com.sun.star.awt.XWindow
541 Dim bFound As Boolean ' True if window found
545 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
547 Check:
548 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
549 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
551 End If
553 Try:
554 bFound = False
556 Set oEnum = StarDesktop.Components().createEnumeration
557 Do While oEnum.hasMoreElements And Not bFound
558 Set oComp = oEnum.nextElement
559 vWindow = SF_UI._IdentifyWindow(oComp)
560 With vWindow
561 ' Does the current window match the arguments ?
565 End With
566 Loop
567 Else
568 vWindow = SF_UI._IdentifyWindow(StarDesktop.CurrentComponent)
569 bFound = True
570 End If
572 If bFound Then
573 Set oContainer = vWindow.Frame.ContainerWindow
574 oContainer.IsMinimized = True
575 End If
577 Finally:
578 SF_Utils._ExitFunction(cstThisSub)
579 Exit Sub
580 Catch:
581 GoTo Finally
582 End Sub ' ScriptForge.SF_UI.Minimize
584 REM -----------------------------------------------------------------------------
585 Public Function Methods() As Variant
586 ''' Return the list of public methods of the UI service as an array
601 )
603 End Function ' ScriptForge.SF_UI.Methods
605 REM -----------------------------------------------------------------------------
606 Public Function OpenBaseDocument(Optional ByVal FileName As Variant _
607 , Optional ByVal RegistrationName As Variant _
608 , Optional ByVal MacroExecution As Variant _
609 ) As Object
610 ''' Open an existing LibreOffice Base document and return a SFDocuments.Document object
611 ''' Args:
612 ''' FileName: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation
613 ''' RegistrationName: the name of a registered database
615 ''' MacroExecution: one of the MACROEXECxxx constants
616 ''' Returns:
617 ''' A SFDocuments.SF_Base object
618 ''' Null if the opening failed, including when due to a user decision
619 ''' Exceptions:
620 ''' BASEDOCUMENTOPENERROR Wrong arguments
621 ''' Examples:
622 ''' Dim mBasec As Object, FSO As Object
623 ''' Set myBase = ui.OpenBaseDocument("C:\Temp\myDB.odb", MacroExecution := ui.MACROEXECNEVER)
625 Dim oOpen As Variant ' Return value
626 Dim vProperties As Variant ' Array of com.sun.star.beans.PropertyValue
627 Dim oDBContext As Object ' com.sun.star.sdb.DatabaseContext
628 Dim oComp As Object ' Loaded component com.sun.star.lang.XComponent
629 Dim sFile As String ' Alias for FileName
630 Dim iMacro As Integer ' Alias for MacroExecution
632 Const cstSubArgs = "[FileName=""""], [RegistrationName=""""], [MacroExecution=0|1|2]"
634 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
635 Set oOpen = Nothing
637 Check:
638 If IsMissing(FileName) Or IsEmpty(FileName) Then FileName = ""
639 If IsMissing(RegistrationName) Or IsEmpty(RegistrationName) Then RegistrationName = ""
640 If IsMissing(MacroExecution) Or IsEmpty(MacroExecution) Then MacroExecution = MACROEXECNORMAL
642 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
644 If Not SF_Utils._Validate(RegistrationName, "RegistrationName", V_STRING) Then GoTo Finally
646 , Array(MACROEXECNORMAL, MACROEXECNEVER, MACROEXECALWAYS)) Then GoTo Finally
647 End If
649 ' Check the existence of FileName
651 If Len(RegistrationName) = 0 Then GoTo CatchError
653 If Not oDBContext.hasRegisteredDatabase(RegistrationName) Then GoTo CatchError
654 FileName = SF_FileSystem._ConvertFromUrl(oDBContext.getDatabaseLocation(RegistrationName))
655 End If
656 If Not SF_FileSystem.FileExists(FileName) Then GoTo CatchError
658 Try:
659 With com.sun.star.document.MacroExecMode
660 Select Case MacroExecution
661 Case 0 : iMacro = .USE_CONFIG
662 Case 1 : iMacro = .NEVER_EXECUTE
663 Case 2 : iMacro = .ALWAYS_EXECUTE_NO_WARN
664 End Select
665 End With
669 sFile = SF_FileSystem._ConvertToUrl(FileName)
671 If Not IsNull(oComp) Then Set oOpen = CreateScriptService("SFDocuments.Document", oComp)
673 Finally:
674 Set OpenBaseDocument = oOpen
675 SF_Utils._ExitFunction(cstThisSub)
676 Exit Function
677 Catch:
678 GoTo Finally
679 CatchError:
680 SF_Exception.RaiseFatal(BASEDOCUMENTOPENERROR, "FileName", FileName, "RegistrationName", RegistrationName)
681 GoTo Finally
682 End Function ' ScriptForge.SF_UI.OpenBaseDocument
684 REM -----------------------------------------------------------------------------
685 Public Function OpenDocument(Optional ByVal FileName As Variant _
686 , Optional ByVal Password As Variant _
687 , Optional ByVal ReadOnly As Variant _
688 , Optional ByVal Hidden As Variant _
689 , Optional ByVal MacroExecution As Variant _
690 , Optional ByVal FilterName As Variant _
691 , Optional ByVal FilterOptions As Variant _
692 ) As Object
693 ''' Open an existing LibreOffice document with the given options
694 ''' Args:
695 ''' FileName: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation
696 ''' Password: To use when the document is protected
697 ''' If wrong or absent while the document is protected, the user will be prompted to enter a password
698 ''' ReadOnly: Default = False
699 ''' Hidden: if True, open in the background (default = False)
700 ''' To use with caution: activation or closure can only happen programmatically
701 ''' MacroExecution: one of the MACROEXECxxx constants
702 ''' FilterName: the name of a filter that should be used for loading the document
703 ''' If present, the filter must exist
704 ''' FilterOptions: an optional string of options associated with the filter
705 ''' Returns:
706 ''' A SFDocuments.SF_Document object or one of its subclasses
707 ''' Null if the opening failed, including when due to a user decision
708 ''' Exceptions:
709 ''' DOCUMENTOPENERROR Wrong arguments
710 ''' Examples:
711 ''' Dim myDoc As Object, FSO As Object
712 ''' Set myDoc = ui.OpenDocument("C:\Temp\myFile.odt", MacroExecution := ui.MACROEXECNEVER)
714 Dim oOpen As Variant ' Return value
715 Dim oFilterFactory As Object ' com.sun.star.document.FilterFactory
716 Dim vProperties As Variant ' Array of com.sun.star.beans.PropertyValue
717 Dim oComp As Object ' Loaded component com.sun.star.lang.XComponent
718 Dim sFile As String ' Alias for FileName
719 Dim iMacro As Integer ' Alias for MacroExecution
721 Const cstSubArgs = "FileName, [Password=""""], [ReadOnly=False], [Hidden=False], [MacroExecution=0|1|2], [FilterName=""""], [FilterOptions=""""]"
723 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
724 Set oOpen = Nothing
726 Check:
727 If IsMissing(Password) Or IsEmpty(Password) Then Password = ""
728 If IsMissing(ReadOnly) Or IsEmpty(ReadOnly) Then ReadOnly = False
729 If IsMissing(Hidden) Or IsEmpty(Hidden) Then Hidden = False
730 If IsMissing(MacroExecution) Or IsEmpty(MacroExecution) Then MacroExecution = MACROEXECNORMAL
731 If IsMissing(FilterName) Or IsEmpty(FilterName) Then FilterName = ""
732 If IsMissing(FilterOptions) Or IsEmpty(FilterOptions) Then FilterOptions = ""
734 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
740 , Array(MACROEXECNORMAL, MACROEXECNEVER, MACROEXECALWAYS)) Then GoTo Finally
743 End If
745 ' Check the existence of FileName and FilterName
746 If Not SF_FileSystem.FileExists(FileName) Then GoTo CatchError
749 If Not oFilterFactory.hasByName(FilterName) Then GoTo CatchError
750 End If
752 Try:
753 With com.sun.star.document.MacroExecMode
754 Select Case MacroExecution
755 Case 0 : iMacro = .USE_CONFIG
756 Case 1 : iMacro = .NEVER_EXECUTE
757 Case 2 : iMacro = .ALWAYS_EXECUTE_NO_WARN
758 End Select
759 End With
761 vProperties = Array( _
767 )
769 vProperties = SF_Array.Append(vProperties, SF_Utils._MakePropertyValue("Password", Password))
770 End If
772 sFile = SF_FileSystem._ConvertToUrl(FileName)
774 If Not IsNull(oComp) Then Set oOpen = CreateScriptService("SFDocuments.Document", oComp)
776 Finally:
777 Set OpenDocument = oOpen
778 SF_Utils._ExitFunction(cstThisSub)
779 Exit Function
780 Catch:
781 GoTo Finally
782 CatchError:
783 SF_Exception.RaiseFatal(DOCUMENTOPENERROR, "FileName", FileName, "Password", Password, "FilterName", FilterName)
784 GoTo Finally
785 End Function ' ScriptForge.SF_UI.OpenDocument
787 REM -----------------------------------------------------------------------------
788 Public Function Properties() As Variant
789 ''' Return the list or properties of the Timer class as an array
791 Properties = Array( _
793 )
795 End Function ' ScriptForge.SF_UI.Properties
797 REM -----------------------------------------------------------------------------
798 Public Sub Resize(Optional ByVal Left As Variant _
799 , Optional ByVal Top As Variant _
800 , Optional ByVal Width As Variant _
801 , Optional ByVal Height As Variant _
802 )
803 ''' Resizes and/or moves the active window. Negative arguments are ignored.
804 ''' If the window was minimized or without arguments, it is restored
805 ''' Args:
806 ''' Left, Top: Distances from top and left edges of the screen
807 ''' Width, Height: Dimensions of the window
808 ''' Examples:
810 ''' ...
812 Dim vWindow As Window ' A single component
813 Dim oContainer As Object ' com.sun.star.awt.XWindow
818 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
820 Check:
821 If IsMissing(Left) Or IsEmpty(Left) Then Left = -1
822 If IsMissing(Top) Or IsEmpty(Top) Then Top = -1
823 If IsMissing(Width) Or IsEmpty(Width) Then Width = -1
824 If IsMissing(Height) Or IsEmpty(Height) Then Height = -1
825 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
830 End If
832 Try:
833 vWindow = SF_UI._IdentifyWindow(StarDesktop.CurrentComponent)
834 If Not IsNull(vWindow.Frame) Then
835 Set oContainer = vWindow.Frame.ContainerWindow
836 iPosSize = 0
841 With oContainer
842 .IsMaximized = False
843 .IsMinimized = False
844 .setPosSize(Left, Top, Width, Height, iPosSize)
845 End With
846 End If
848 Finally:
849 SF_Utils._ExitFunction(cstThisSub)
850 Exit Sub
851 Catch:
852 GoTo Finally
853 End Sub ' ScriptForge.SF_UI.Resize
855 REM -----------------------------------------------------------------------------
856 Public Function SetProperty(Optional ByVal PropertyName As Variant _
857 , Optional ByRef Value As Variant _
858 ) As Boolean
859 ''' Set a new value to the given property
860 ''' Args:
861 ''' PropertyName: the name of the property as a string
862 ''' Value: its new value
863 ''' Exceptions
864 ''' ARGUMENTERROR The property does not exist
869 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
870 SetProperty = False
872 Check:
873 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
874 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
875 End If
877 Try:
878 Select Case UCase(PropertyName)
879 Case Else
880 End Select
882 Finally:
883 SF_Utils._ExitFunction(cstThisSub)
884 Exit Function
885 Catch:
886 GoTo Finally
887 End Function ' ScriptForge.SF_UI.SetProperty
889 REM -----------------------------------------------------------------------------
890 Public Sub SetStatusbar(Optional ByVal Text As Variant _
891 , Optional ByVal Percentage As Variant _
892 )
893 ''' Display a text and a progressbar in the status bar of the active window
894 ''' Any subsequent calls in the same macro run refer to the same status bar of the same window,
895 ''' even if the window is not active anymore
896 ''' A call without arguments resets the status bar to its normal state.
897 ''' Args:
898 ''' Text: the optional text to be displayed before the progress bar
900 ''' Examples:
901 ''' Dim i As Integer
905 ''' Next i
906 ''' ui.SetStatusbar
908 Dim oComp As Object
909 Dim oControl As Object
910 Static oStatusbar As Object
914 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
916 Check:
917 If IsMissing(Text) Or IsEmpty(Text) Then Text = ""
918 If IsMissing(Percentage) Or IsEmpty(Percentage) Then Percentage = -1
919 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
922 End If
924 Try:
925 With oStatusbar
926 If IsNull(oStatusbar) Then ' Initial call
927 Set oComp = StarDesktop.CurrentComponent
928 If Not IsNull(oComp) Then
929 Set oControl = Nothing
930 If SF_Session.HasUnoProperty(oComp, "CurrentController") Then Set oControl = oComp.CurrentController
931 If Not IsNull(oControl) Then
932 If SF_Session.HasUnoMethod(oControl, "getStatusIndicator") Then oStatusbar = oControl.getStatusIndicator()
933 End If
934 End If
935 If Not IsNull(oStatusbar) Then
937 End If
938 End If
939 If Not IsNull(oStatusbar) Then
941 .end()
942 Else
945 End If
946 End If
947 End With
949 Finally:
950 SF_Utils._ExitFunction(cstThisSub)
951 Exit Sub
952 Catch:
953 GoTo Finally
954 End Sub ' ScriptForge.SF_UI.SetStatusbar
956 REM -----------------------------------------------------------------------------
957 Public Sub ShowProgressBar(Optional Title As Variant _
958 , Optional ByVal Text As Variant _
959 , Optional ByVal Percentage As Variant _
960 )
961 ''' Display a non-modal dialog box. Specify its title, an explicatory text and the progress on a progressbar
962 ''' A call without arguments erases the progress bar dialog.
963 ''' The box will anyway vanish at the end of the macro run.
964 ''' Args:
965 ''' Title: the title appearing on top of the dialog box (Default = "ScriptForge")
966 ''' Text: the optional text to be displayed above the progress bar (default = zero-length string)
968 ''' Examples:
969 ''' Dim i As Integer
971 ''' ui.ShowProgressBar(, "Progress ... " & i & "/100", i)
973 ''' Next i
974 ''' ui.ShowProgressBar
976 Dim bFirstCall As Boolean ' True at first invocation of method
977 Static oDialog As Object ' SFDialogs.Dialog object
978 Static oFixedText As Object ' SFDialogs.DialogControl object
979 Static oProgressBar As Object ' SFDialogs.DialogControl object
980 Dim sTitle As String ' Alias of Title
984 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
986 Check:
987 If IsMissing(Title) Or IsEmpty(Title) Then Title = ""
988 If IsMissing(Text) Or IsEmpty(Text) Then Text = ""
989 If IsMissing(Percentage) Or IsEmpty(Percentage) Then Percentage = -1
990 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
994 End If
996 Try:
997 With oDialog
998 bFirstCall = ( IsNull(oDialog) )
999 If Not bFirstCall Then bFirstCall = Not ._IsStillAlive(False) ' False to not raise an error
1000 If bFirstCall Then Set oDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", "ScriptForge", "dlgProgress")
1002 If Not IsNull(oDialog) Then
1004 Set oDialog = .Dispose()
1005 Else
1007 If bFirstCall Then
1011 .Execute(Modal := False)
1012 End If
1015 End If
1016 End If
1017 End With
1019 Finally:
1020 SF_Utils._ExitFunction(cstThisSub)
1021 Exit Sub
1022 Catch:
1023 GoTo Finally
1024 End Sub ' ScriptForge.SF_UI.ShowProgressBar
1026 REM -----------------------------------------------------------------------------
1027 Public Function WindowExists(Optional ByVal WindowName As Variant) As Boolean
1028 ''' Returns True if the specified window exists
1029 ''' Args:
1030 ''' WindowName: see definitions
1031 ''' Returns:
1032 ''' True if the given window is found
1033 ''' Examples:
1036 Dim bWindowExists As Boolean ' Return value
1037 Dim oEnum As Object ' com.sun.star.container.XEnumeration
1038 Dim oComp As Object ' com.sun.star.lang.XComponent
1039 Dim vWindow As Window ' A single component
1040 Dim oContainer As Object ' com.sun.star.awt.XWindow
1044 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
1045 bWindowExists = False
1047 Check:
1048 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
1049 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
1051 End If
1053 Try:
1054 Set oEnum = StarDesktop.Components().createEnumeration
1055 Do While oEnum.hasMoreElements
1056 Set oComp = oEnum.nextElement
1057 vWindow = SF_UI._IdentifyWindow(oComp)
1058 With vWindow
1059 ' Does the current window match the arguments ?
1060 If (Len(.WindowFileName) > 0 And .WindowFileName = SF_FileSystem.ConvertToUrl(WindowName)) _
1063 bWindowExists = True
1064 Exit Do
1065 End If
1066 End With
1067 Loop
1069 Finally:
1070 WindowExists = bWindowExists
1071 SF_Utils._ExitFunction(cstThisSub)
1072 Exit Function
1073 Catch:
1074 GoTo Finally
1075 End Function ' ScriptForge.SF_UI.WindowExists
1077 REM =========================================================== PRIVATE FUNCTIONS
1079 REM -----------------------------------------------------------------------------
1080 Public Sub _CloseProgressBar(Optional ByRef poEvent As Object)
1081 ''' Triggered by the Close button in the dlgProgress dialog
1082 ''' to simply close the dialog
1086 End Sub ' ScriptForge.SF_UI._CloseProgressBar
1088 REM -----------------------------------------------------------------------------
1089 Public Function _IdentifyWindow(ByRef poComponent As Object) As Object
1090 ''' Return a Window object (definition on top of module) based on component given as argument
1091 ''' Is a shortcut to explore the most relevant properties or objects bound to a UNO component
1093 Dim oWindow As Window ' Return value
1096 Dim vArg As Variant ' One single item of the Args UNO property
1097 Dim FSO As Object ' Alias for SF_FileSystem
1099 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
1100 Set _IdentifyWindow = Nothing
1103 Set FSO = SF_FileSystem
1104 With oWindow
1105 Set .Frame = Nothing
1106 Set .Component = Nothing
1107 .WindowName = ""
1108 .WindowTitle = ""
1109 .WindowFileName = ""
1110 .DocumentType = ""
1111 If IsNull(poComponent) Then GoTo Finally
1112 If SF_Session.HasUnoProperty(poComponent, "ImplementationName") Then sImplementation = poComponent.ImplementationName
1113 If SF_Session.HasUnoProperty(poComponent, "Identifier") Then sIdentifier = poComponent.Identifier
1114 Set .Component = poComponent
1115 Select Case sImplementation
1117 .WindowName = BASICIDE
1120 If Len(.WindowFileName) > 0 Then .WindowName = FSO.GetName(FSO._ConvertFromUrl(.WindowFileName))
1121 .DocumentType = BASEDOCUMENT
1123 Case "org.openoffice.comp.dbu.OTableDesign", "org.openoffice.comp.dbu.OQueryDesign" ' Table or Query in Edit mode
1126 Set .Frame = poComponent.Frame
1127 .WindowName = WELCOMESCREEN
1128 Case Else
1130 ' Do not use URL : it contains the TemplateFile when new documents are created from a template
1131 .WindowFileName = poComponent.Location
1132 If Len(.WindowFileName) > 0 Then .WindowName = FSO.GetName(FSO._ConvertFromUrl(.WindowFileName))
1133 If SF_Session.HasUnoProperty(poComponent, "Title") Then .WindowTitle = poComponent.Title
1134 Select Case sIdentifier
1138 .DocumentType = WRITERDOCUMENT
1140 .DocumentType = CALCDOCUMENT
1142 .DocumentType = IMPRESSDOCUMENT
1144 .DocumentType = DRAWDOCUMENT
1146 .DocumentType = MATHDOCUMENT
1147 Case Else
1148 End Select
1149 End If
1150 End Select
1151 If IsNull(.Frame) Then
1152 If Not IsNull(poComponent.CurrentController) Then Set .Frame = poComponent.CurrentController.Frame
1153 End If
1154 End With
1156 Finally:
1157 Set _IdentifyWindow = oWindow
1158 Exit Function
1159 Catch:
1160 GoTo Finally
1161 End Function ' ScriptForge.SF_UI._IdentifyWindow
1163 REM -----------------------------------------------------------------------------
1164 Private Function _Repr() As String
1165 ''' Convert the UI instance to a readable string, typically for debugging purposes (DebugPrint ...)
1166 ''' Args:
1167 ''' Return:
1172 End Function ' ScriptForge.SF_UI._Repr
1174 REM ============================================ END OF SCRIPTFORGE.SF_UI
1175 </script:module>