| blob | 186d88244d75ef7ba3367c8763c1d55194c0846c |
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
33 '''
34 ''' Detailed user documentation:
35 ''' https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/sf_ui.html?DbPAR=BASIC
36 '''
37 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
39 REM ================================================================== EXCEPTIONS
42 Const DOCUMENTCREATIONERROR = "DOCUMENTCREATIONERROR" ' Incoherent arguments, new document could not be created
43 Const DOCUMENTOPENERROR = "DOCUMENTOPENERROR" ' Document could not be opened, check the arguments
47 REM ============================================================= PRIVATE MEMBERS
49 Type Window
50 Component As Object ' com.sun.star.lang.XComponent
51 Frame As Object ' com.sun.star.comp.framework.Frame
52 WindowName As String ' Object Name
53 WindowTitle As String ' Only mean to identify new documents
54 WindowFileName As String ' URL of file name
55 DocumentType As String ' Writer, Calc, ...
56 ParentName As String ' Identifier of the parent Base file when Window is a subcomponent
57 End Type
59 ' The progress/status bar of the active window
62 REM ============================================================ MODULE CONSTANTS
64 ' Special windows
76 ' Window subtypes
83 ' Macro execution modes
88 REM ===================================================== CONSTRUCTOR/DESTRUCTOR
90 REM -----------------------------------------------------------------------------
91 Public Function Dispose() As Variant
92 Set Dispose = Nothing
93 End Function ' ScriptForge.SF_UI Explicit destructor
95 REM ================================================================== PROPERTIES
97 REM -----------------------------------------------------------------------------
98 Public Function ActiveWindow() As String
99 ''' Returns a valid WindowName for the currently active window
102 Dim vWindow As Window ' A component
103 Dim oComp As Object ' com.sun.star.lang.XComponent
105 Set oComp = StarDesktop.CurrentComponent
106 If Not IsNull(oComp) Then
107 vWindow = SF_UI._IdentifyWindow(oComp)
108 With vWindow
110 ActiveWindow = SF_FileSystem._ConvertFromUrl(.WindowFileName)
112 ActiveWindow = .WindowName
114 ActiveWindow = .WindowTitle
115 Else
116 ActiveWindow = ""
117 End If
118 End With
119 End If
121 End Function ' ScriptForge.SF_UI.ActiveWindow
123 REM -----------------------------------------------------------------------------
124 Property Get Height() As Long
125 ''' Returns the height of the active window
126 Dim oPosSize As Object ' com.sun.star.awt.Rectangle
127 Set oPosSize = SF_UI._PosSize()
128 If Not IsNull(oPosSize) Then Height = oPosSize.Height Else Height = -1
129 End Property ' ScriptForge.SF_UI.Height
131 REM -----------------------------------------------------------------------------
132 Property Get MACROEXECALWAYS As Integer
133 ''' Macros are always executed
134 MACROEXECALWAYS = cstMACROEXECALWAYS
135 End Property ' ScriptForge.SF_UI.MACROEXECALWAYS
137 REM -----------------------------------------------------------------------------
138 Property Get MACROEXECNEVER As Integer
139 ''' Macros are not executed
140 MACROEXECNEVER = cstMACROEXECNEVER
141 End Property ' ScriptForge.SF_UI.MACROEXECNEVER
143 REM -----------------------------------------------------------------------------
144 Property Get MACROEXECNORMAL As Integer
145 ''' Default, execution depends on user configuration and choice
146 MACROEXECNORMAL = cstMACROEXECNORMAL
147 End Property ' ScriptForge.SF_UI.MACROEXECNORMAL
149 REM -----------------------------------------------------------------------------
150 Property Get ObjectType As String
151 ''' Only to enable object representation
153 End Property ' ScriptForge.SF_UI.ObjectType
155 REM -----------------------------------------------------------------------------
156 Property Get ServiceName As String
157 ''' Internal use
159 End Property ' ScriptForge.SF_UI.ServiceName
161 REM -----------------------------------------------------------------------------
162 Property Get Width() As Long
163 ''' Returns the width of the active window
164 Dim oPosSize As Object ' com.sun.star.awt.Rectangle
165 Set oPosSize = SF_UI._PosSize()
166 If Not IsNull(oPosSize) Then Width = oPosSize.Width Else Width = -1
167 End Property ' ScriptForge.SF_UI.Width
169 REM -----------------------------------------------------------------------------
170 Property Get X() As Long
171 ''' Returns the X coordinate of the active window
172 Dim oPosSize As Object ' com.sun.star.awt.Rectangle
173 Set oPosSize = SF_UI._PosSize()
174 If Not IsNull(oPosSize) Then X = oPosSize.X Else X = -1
175 End Property ' ScriptForge.SF_UI.X
177 REM -----------------------------------------------------------------------------
178 Property Get Y() As Long
179 ''' Returns the Y coordinate of the active window
180 Dim oPosSize As Object ' com.sun.star.awt.Rectangle
181 Set oPosSize = SF_UI._PosSize()
182 If Not IsNull(oPosSize) Then Y = oPosSize.Y Else Y = -1
183 End Property ' ScriptForge.SF_UI.Y
185 REM ===================================================================== METHODS
187 REM -----------------------------------------------------------------------------
188 Public Function Activate(Optional ByVal WindowName As Variant) As Boolean
189 ''' Make the specified window active
190 ''' Args:
191 ''' WindowName: see definitions
192 ''' Returns:
193 ''' True if the given window is found and can be activated
194 ''' There is no change in the actual user interface if no window matches the selection
195 ''' Examples:
198 Dim bActivate As Boolean ' Return value
199 Dim oEnum As Object ' com.sun.star.container.XEnumeration
200 Dim oComp As Object ' com.sun.star.lang.XComponent
201 Dim vWindow As Window ' A single component
202 Dim oContainer As Object ' com.sun.star.awt.XWindow
206 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
207 bActivate = False
209 Check:
210 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
211 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
213 End If
215 Try:
216 Set oEnum = StarDesktop.Components().createEnumeration
217 Do While oEnum.hasMoreElements
218 Set oComp = oEnum.nextElement
219 vWindow = SF_UI._IdentifyWindow(oComp)
220 With vWindow
221 ' Does the current window match the arguments ?
222 If (Len(.WindowFileName) > 0 And .WindowFileName = SF_FileSystem._ConvertToUrl(WindowName)) _
225 Set oContainer = vWindow.Frame.ContainerWindow
226 With oContainer
227 If .isVisible() = False Then .setVisible(True)
228 .IsMinimized = False
229 .setFocus()
230 .toFront() ' Force window change in Linux
232 End With
233 bActivate = True
234 Exit Do
235 End If
236 End With
237 Loop
239 Finally:
240 Activate = bActivate
241 SF_Utils._ExitFunction(cstThisSub)
242 Exit Function
243 Catch:
244 GoTo Finally
245 End Function ' ScriptForge.SF_UI.Activate
247 REM -----------------------------------------------------------------------------
248 Public Function CreateBaseDocument(Optional ByVal FileName As Variant _
249 , Optional ByVal EmbeddedDatabase As Variant _
250 , Optional ByVal RegistrationName As Variant _
251 , Optional ByVal CalcFileName As Variant _
252 ) As Object
253 ''' Create a new LibreOffice Base document embedding an empty database of the given type
254 ''' Args:
255 ''' FileName: Identifies the file to create. It must follow the SF_FileSystem.FileNaming notation
256 ''' If the file already exists, it is overwritten without warning
257 ''' EmbeddedDatabase: either "HSQLDB" (default) or "FIREBIRD" or "CALC"
258 ''' RegistrationName: the name used to store the new database in the databases register
260 ''' If the name already exists it is overwritten without warning
261 ''' CalcFileName: only when EmbedddedDatabase = "CALC", the name of the file containing the tables as Calc sheets
262 ''' The name of the file must be given in SF_FileSystem.FileNaming notation
263 ''' The file must exist
264 ''' Returns:
265 ''' A SFDocuments.SF_Document object or one of its subclasses
266 ''' Exceptions
267 ''' UNKNOWNFILEERROR Calc datasource does not exist
268 ''' Examples:
269 ''' Dim myBase As Object, myCalcBase As Object
270 ''' Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
271 ''' Set myCalcBase = ui.CreateBaseDocument("C:\Databases\MyCalcBaseFile.odb", "CALC", , "C:\Databases\MyCalcFile.ods")
273 Dim oCreate As Variant ' Return value
274 Dim oDBContext As Object ' com.sun.star.sdb.DatabaseContext
275 Dim oDatabase As Object ' com.sun.star.comp.dba.ODatabaseSource
276 Dim oComp As Object ' Loaded component com.sun.star.lang.XComponent
277 Dim sFileName As String ' Alias of FileName
278 Dim FSO As Object ' Alias for FileSystem service
281 Const cstSubArgs = "FileName, [EmbeddedDatabase=""HSQLDB""|""FIREBIRD""|""CALC""], [RegistrationName=""""], [CalcFileName]"
283 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
284 Set oCreate = Nothing
287 Check:
288 If IsMissing(EmbeddedDatabase) Or IsEmpty(EmbeddedDatabase) Then EmbeddedDatabase = "HSQLDB"
289 If IsMissing(RegistrationName) Or IsEmpty(RegistrationName) Then RegistrationName = ""
290 If IsMissing(CalcFileName) Or IsEmpty(CalcFileName) Then CalcFileName = ""
291 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
293 If Not SF_Utils._Validate(EmbeddedDatabase, "EmbeddedDatabase", V_STRING, Array("CALC", "HSQLDB", "FIREBIRD")) Then GoTo Finally
294 If Not SF_Utils._Validate(RegistrationName, "RegistrationName", V_STRING) Then GoTo Finally
297 If Not FSO.FileExists(CalcFileName) Then GoTo CatchNotExists
298 End If
299 End If
301 Try:
303 With oDBContext
304 Set oDatabase = .createInstance()
305 ' Build the url link to the database
306 Select Case UCase(EmbeddedDatabase)
311 End Select
312 ' Create empty Base document
313 sFileName = FSO._ConvertToUrl(FileName)
314 ' An existing file is overwritten without warning
315 If FSO.FileExists(FileName) Then FSO.DeleteFile(FileName)
316 If FSO.FileExists(FileName & ".lck") Then FSO.DeleteFile(FileName & ".lck")
317 oDatabase.DatabaseDocument.storeAsURL(sFileName, Array(SF_Utils._MakePropertyValue("Overwrite", True)))
318 ' Register database if requested
320 If .hasRegisteredDatabase(RegistrationName) Then
321 .changeDatabaseLocation(RegistrationName, sFileName)
322 Else
323 .registerDatabaseLocation(RegistrationName, sFileName)
324 End If
325 End If
326 End With
328 Set oCreate = OpenBaseDocument(FileName)
330 Finally:
331 Set CreateBaseDocument = oCreate
332 SF_Utils._ExitFunction(cstThisSub)
333 Exit Function
334 Catch:
335 GoTo Finally
336 CatchNotExists:
338 GoTo Finally
339 End Function ' ScriptForge.SF_UI.CreateBaseDocument
341 REM -----------------------------------------------------------------------------
342 Public Function CreateDocument(Optional ByVal DocumentType As Variant _
343 , Optional ByVal TemplateFile As Variant _
344 , Optional ByVal Hidden As Variant _
345 ) As Object
346 ''' Create a new LibreOffice document of a given type or based on a given template
347 ''' Args:
348 ''' DocumentType: "Calc", "Writer", etc. If absent, a TemplateFile must be given
349 ''' TemplateFile: the full FileName of the template to build the new document on
350 ''' If the file does not exist, the argument is ignored
351 ''' The "FileSystem" service provides the TemplatesFolder and UserTemplatesFolder
352 ''' properties to help to build the argument
353 ''' Hidden: if True, open in the background (default = False)
354 ''' To use with caution: activation or closure can only happen programmatically
355 ''' Returns:
356 ''' A SFDocuments.SF_Document object or one of its subclasses
357 ''' Exceptions:
358 ''' DOCUMENTCREATIONERROR Wrong arguments
359 ''' Examples:
360 ''' Dim myDoc1 As Object, myDoc2 As Object, FSO As Object
363 ''' Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))
365 Dim oCreate As Variant ' Return value
366 Dim vProperties As Variant ' Array of com.sun.star.beans.PropertyValue
367 Dim bTemplateExists As Boolean ' True if TemplateFile is valid
368 Dim sNew As String ' File url
369 Dim oComp As Object ' Loaded component com.sun.star.lang.XComponent
372 Const cstSubArgs = "[DocumentType=""""], [TemplateFile=""""], [Hidden=False]"
374 '>>> If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
375 Set oCreate = Nothing
377 Check:
378 If IsMissing(DocumentType) Or IsEmpty(DocumentType) Then DocumentType = ""
379 If IsMissing(TemplateFile) Or IsEmpty(TemplateFile) Then TemplateFile = ""
380 If IsMissing(Hidden) Or IsEmpty(Hidden) Then Hidden = False
382 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
384 , Array("", BASEDOCUMENT, CALCDOCUMENT, DRAWDOCUMENT _
385 , IMPRESSDOCUMENT, MATHDOCUMENT, WRITERDOCUMENT)) Then GoTo Finally
388 End If
390 If Len(DocumentType) + Len(TemplateFile) = 0 Then GoTo CatchError
391 If Len(TemplateFile) > 0 Then bTemplateExists = SF_FileSystem.FileExists(TemplateFile) Else bTemplateExists = False
392 If Len(DocumentType) = 0 Then
393 If Not bTemplateExists Then GoTo CatchError
394 End If
396 Try:
397 If bTemplateExists Then sNew = SF_FileSystem._ConvertToUrl(TemplateFile) Else sNew = cstDocType & LCase(DocumentType)
398 vProperties = Array( _
401 )
403 If Not IsNull(oComp) Then Set oCreate = CreateScriptService("SFDocuments.Document", oComp)
405 Finally:
406 Set CreateDocument = oCreate
407 SF_Utils._ExitFunction(cstThisSub)
408 Exit Function
409 Catch:
410 GoTo Finally
411 CatchError:
412 SF_Exception.RaiseFatal(DOCUMENTCREATIONERROR, "DocumentType", DocumentType, "TemplateFile", TemplateFile)
413 GoTo Finally
414 End Function ' ScriptForge.SF_UI.CreateDocument
416 REM -----------------------------------------------------------------------------
417 Public Function Documents() As Variant
418 ''' Returns the list of the currently open documents. Special windows are ignored.
419 ''' Returns:
421 ''' or of window titles for unsaved documents
422 ''' Examples:
423 ''' Dim vDocs As Variant, sDoc As String
424 ''' vDocs = ui.Documents()
425 ''' For each sDoc In vDocs
426 ''' ...
428 Dim vDocuments As Variant ' Return value
429 Dim oEnum As Object ' com.sun.star.container.XEnumeration
430 Dim oComp As Object ' com.sun.star.lang.XComponent
431 Dim vWindow As Window ' A single component
433 Const cstSubArgs = ""
435 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
436 vDocuments = Array()
438 Check:
439 SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
441 Try:
442 Set oEnum = StarDesktop.Components().createEnumeration
443 Do While oEnum.hasMoreElements
444 Set oComp = oEnum.nextElement
445 vWindow = SF_UI._IdentifyWindow(oComp)
446 With vWindow
448 vDocuments = SF_Array.Append(vDocuments, SF_FileSystem._ConvertFromUrl(.WindowFileName))
450 vDocuments = SF_Array.Append(vDocuments, .WindowTitle)
451 End If
452 End With
453 Loop
455 Finally:
456 Documents = vDocuments
457 SF_Utils._ExitFunction(cstThisSub)
458 Exit Function
459 Catch:
460 GoTo Finally
461 End Function ' ScriptForge.SF_UI.Documents
463 REM -----------------------------------------------------------------------------
464 Public Function GetDocument(Optional ByVal WindowName As Variant) As Variant
465 ''' Returns a SFDocuments.Document object referring to the active window or the given window
466 ''' Args:
467 ''' WindowName: when a string, see definitions. If absent the active window is considered.
468 ''' when an object, must be a UNO object of types
469 ''' com.sun.star.lang.XComponent or com.sun.star.comp.dba.ODatabaseDocument
470 ''' Exceptions:
471 ''' DOCUMENTERROR The targeted window could not be found
472 ''' Examples:
473 ''' Dim oDoc As Object
475 ''' oDoc.Save()
477 Dim oDocument As Object ' Return value
481 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
482 Set oDocument = Nothing
484 Check:
485 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
486 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
487 If Not SF_Utils._Validate(WindowName, "WindowName", Array(V_STRING, V_OBJECT)) Then GoTo Finally
488 If VarType(WindowName) = V_STRING Then
490 End If
491 End If
493 Try:
495 If IsNull(oDocument) Then GoTo CatchDeliver
497 Finally:
498 Set GetDocument = oDocument
499 SF_Utils._ExitFunction(cstThisSub)
500 Exit Function
501 Catch:
502 GoTo Finally
503 CatchDeliver:
505 GoTo Finally
506 End Function ' ScriptForge.SF_UI.GetDocument
508 REM -----------------------------------------------------------------------------
509 Public Function GetProperty(Optional ByVal PropertyName As Variant) As Variant
510 ''' Return the actual value of the given property
511 ''' Args:
512 ''' PropertyName: the name of the property as a string
513 ''' Returns:
514 ''' The actual value of the property
515 ''' Exceptions
516 ''' ARGUMENTERROR The property does not exist
521 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
522 GetProperty = Null
524 Check:
525 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
526 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
527 End If
529 Try:
530 Select Case UCase(PropertyName)
537 Case Else
538 End Select
540 Finally:
541 SF_Utils._ExitFunction(cstThisSub)
542 Exit Function
543 Catch:
544 GoTo Finally
545 End Function ' ScriptForge.SF_UI.GetProperty
547 REM -----------------------------------------------------------------------------
548 Public Sub Maximize(Optional ByVal WindowName As Variant)
549 ''' Maximizes the active window or the given window
550 ''' Args:
551 ''' WindowName: see definitions. If absent the active window is considered
552 ''' Examples:
553 ''' ui.Maximize
554 ''' ...
556 Dim oEnum As Object ' com.sun.star.container.XEnumeration
557 Dim oComp As Object ' com.sun.star.lang.XComponent
558 Dim vWindow As Window ' A single component
559 Dim oContainer As Object ' com.sun.star.awt.XWindow
560 Dim bFound As Boolean ' True if window found
564 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
566 Check:
567 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
568 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
570 End If
572 Try:
573 bFound = False
575 Set oEnum = StarDesktop.Components().createEnumeration
576 Do While oEnum.hasMoreElements And Not bFound
577 Set oComp = oEnum.nextElement
578 vWindow = SF_UI._IdentifyWindow(oComp)
579 With vWindow
580 ' Does the current window match the arguments ?
584 End With
585 Loop
586 Else
587 vWindow = SF_UI._IdentifyWindow(StarDesktop.CurrentComponent)
588 bFound = True
589 End If
591 If bFound Then
592 Set oContainer = vWindow.Frame.ContainerWindow
593 oContainer.IsMaximized = True
594 End If
596 Finally:
597 SF_Utils._ExitFunction(cstThisSub)
598 Exit Sub
599 Catch:
600 GoTo Finally
601 End Sub ' ScriptForge.SF_UI.Maximize
603 REM -----------------------------------------------------------------------------
604 Public Sub Minimize(Optional ByVal WindowName As Variant)
605 ''' Minimizes the current window or the given window
606 ''' Args:
607 ''' WindowName: see definitions. If absent the current window is considered
608 ''' Examples:
610 ''' ...
612 Dim oEnum As Object ' com.sun.star.container.XEnumeration
613 Dim oComp As Object ' com.sun.star.lang.XComponent
614 Dim vWindow As Window ' A single component
615 Dim oContainer As Object ' com.sun.star.awt.XWindow
616 Dim bFound As Boolean ' True if window found
620 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
622 Check:
623 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
624 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
626 End If
628 Try:
629 bFound = False
631 Set oEnum = StarDesktop.Components().createEnumeration
632 Do While oEnum.hasMoreElements And Not bFound
633 Set oComp = oEnum.nextElement
634 vWindow = SF_UI._IdentifyWindow(oComp)
635 With vWindow
636 ' Does the current window match the arguments ?
640 End With
641 Loop
642 Else
643 vWindow = SF_UI._IdentifyWindow(StarDesktop.CurrentComponent)
644 bFound = True
645 End If
647 If bFound Then
648 Set oContainer = vWindow.Frame.ContainerWindow
649 oContainer.IsMinimized = True
650 End If
652 Finally:
653 SF_Utils._ExitFunction(cstThisSub)
654 Exit Sub
655 Catch:
656 GoTo Finally
657 End Sub ' ScriptForge.SF_UI.Minimize
659 REM -----------------------------------------------------------------------------
660 Public Function Methods() As Variant
661 ''' Return the list of public methods of the UI service as an array
677 )
679 End Function ' ScriptForge.SF_UI.Methods
681 REM -----------------------------------------------------------------------------
682 Public Function OpenBaseDocument(Optional ByVal FileName As Variant _
683 , Optional ByVal RegistrationName As Variant _
684 , Optional ByVal MacroExecution As Variant _
685 ) As Object
686 ''' Open an existing LibreOffice Base document and return a SFDocuments.Document object
687 ''' Args:
688 ''' FileName: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation
689 ''' RegistrationName: the name of a registered database
691 ''' MacroExecution: one of the MACROEXECxxx constants
692 ''' Returns:
693 ''' A SFDocuments.SF_Base object
694 ''' Null if the opening failed, including when due to a user decision
695 ''' Exceptions:
696 ''' BASEDOCUMENTOPENERROR Wrong arguments
697 ''' Examples:
698 ''' Dim mBasec As Object, FSO As Object
699 ''' Set myBase = ui.OpenBaseDocument("C:\Temp\myDB.odb", MacroExecution := ui.MACROEXECNEVER)
701 Dim oOpen As Variant ' Return value
702 Dim vProperties As Variant ' Array of com.sun.star.beans.PropertyValue
703 Dim oDBContext As Object ' com.sun.star.sdb.DatabaseContext
704 Dim oComp As Object ' Loaded component com.sun.star.lang.XComponent
705 Dim sFile As String ' Alias for FileName
706 Dim iMacro As Integer ' Alias for MacroExecution
708 Const cstSubArgs = "[FileName=""""], [RegistrationName=""""], [MacroExecution=0|1|2]"
710 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
711 Set oOpen = Nothing
713 Check:
714 If IsMissing(FileName) Or IsEmpty(FileName) Then FileName = ""
715 If IsMissing(RegistrationName) Or IsEmpty(RegistrationName) Then RegistrationName = ""
716 If IsMissing(MacroExecution) Or IsEmpty(MacroExecution) Then MacroExecution = MACROEXECNORMAL
718 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
720 If Not SF_Utils._Validate(RegistrationName, "RegistrationName", V_STRING) Then GoTo Finally
722 , Array(MACROEXECNORMAL, MACROEXECNEVER, MACROEXECALWAYS)) Then GoTo Finally
723 End If
725 ' Check the existence of FileName
727 If Len(RegistrationName) = 0 Then GoTo CatchError
729 If Not oDBContext.hasRegisteredDatabase(RegistrationName) Then GoTo CatchError
730 FileName = SF_FileSystem._ConvertFromUrl(oDBContext.getDatabaseLocation(RegistrationName))
731 End If
732 If Not SF_FileSystem.FileExists(FileName) Then GoTo CatchError
734 Try:
735 With com.sun.star.document.MacroExecMode
736 Select Case MacroExecution
737 Case 0 : iMacro = .USE_CONFIG
738 Case 1 : iMacro = .NEVER_EXECUTE
739 Case 2 : iMacro = .ALWAYS_EXECUTE_NO_WARN
740 End Select
741 End With
745 sFile = SF_FileSystem._ConvertToUrl(FileName)
747 If Not IsNull(oComp) Then Set oOpen = CreateScriptService("SFDocuments.Document", oComp)
749 Finally:
750 Set OpenBaseDocument = oOpen
751 SF_Utils._ExitFunction(cstThisSub)
752 Exit Function
753 Catch:
754 GoTo Finally
755 CatchError:
756 SF_Exception.RaiseFatal(BASEDOCUMENTOPENERROR, "FileName", FileName, "RegistrationName", RegistrationName)
757 GoTo Finally
758 End Function ' ScriptForge.SF_UI.OpenBaseDocument
760 REM -----------------------------------------------------------------------------
761 Public Function OpenDocument(Optional ByVal FileName As Variant _
762 , Optional ByVal Password As Variant _
763 , Optional ByVal ReadOnly As Variant _
764 , Optional ByVal Hidden As Variant _
765 , Optional ByVal MacroExecution As Variant _
766 , Optional ByVal FilterName As Variant _
767 , Optional ByVal FilterOptions As Variant _
768 ) As Object
769 ''' Open an existing LibreOffice document with the given options
770 ''' Args:
771 ''' FileName: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation
772 ''' Password: To use when the document is protected
773 ''' If wrong or absent while the document is protected, the user will be prompted to enter a password
774 ''' ReadOnly: Default = False
775 ''' Hidden: if True, open in the background (default = False)
776 ''' To use with caution: activation or closure can only happen programmatically
777 ''' MacroExecution: one of the MACROEXECxxx constants
778 ''' FilterName: the name of a filter that should be used for loading the document
779 ''' If present, the filter must exist
780 ''' FilterOptions: an optional string of options associated with the filter
781 ''' Returns:
782 ''' A SFDocuments.SF_Document object or one of its subclasses
783 ''' Null if the opening failed, including when due to a user decision
784 ''' Exceptions:
785 ''' DOCUMENTOPENERROR Wrong arguments
786 ''' Examples:
787 ''' Dim myDoc As Object, FSO As Object
788 ''' Set myDoc = ui.OpenDocument("C:\Temp\myFile.odt", MacroExecution := ui.MACROEXECNEVER)
790 Dim oOpen As Variant ' Return value
791 Dim oFilterFactory As Object ' com.sun.star.document.FilterFactory
792 Dim vProperties As Variant ' Array of com.sun.star.beans.PropertyValue
793 Dim oComp As Object ' Loaded component com.sun.star.lang.XComponent
794 Dim sFile As String ' Alias for FileName
795 Dim iMacro As Integer ' Alias for MacroExecution
797 Const cstSubArgs = "FileName, [Password=""""], [ReadOnly=False], [Hidden=False], [MacroExecution=0|1|2], [FilterName=""""], [FilterOptions=""""]"
799 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
800 Set oOpen = Nothing
802 Check:
803 If IsMissing(Password) Or IsEmpty(Password) Then Password = ""
804 If IsMissing(ReadOnly) Or IsEmpty(ReadOnly) Then ReadOnly = False
805 If IsMissing(Hidden) Or IsEmpty(Hidden) Then Hidden = False
806 If IsMissing(MacroExecution) Or IsEmpty(MacroExecution) Then MacroExecution = MACROEXECNORMAL
807 If IsMissing(FilterName) Or IsEmpty(FilterName) Then FilterName = ""
808 If IsMissing(FilterOptions) Or IsEmpty(FilterOptions) Then FilterOptions = ""
810 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
816 , Array(MACROEXECNORMAL, MACROEXECNEVER, MACROEXECALWAYS)) Then GoTo Finally
819 End If
821 ' Check the existence of FileName and FilterName
822 If Not SF_FileSystem.FileExists(FileName) Then GoTo CatchError
825 If Not oFilterFactory.hasByName(FilterName) Then GoTo CatchError
826 End If
828 Try:
829 With com.sun.star.document.MacroExecMode
830 Select Case MacroExecution
831 Case 0 : iMacro = .USE_CONFIG
832 Case 1 : iMacro = .NEVER_EXECUTE
833 Case 2 : iMacro = .ALWAYS_EXECUTE_NO_WARN
834 End Select
835 End With
837 vProperties = Array( _
843 )
845 vProperties = SF_Array.Append(vProperties, SF_Utils._MakePropertyValue("Password", Password))
846 End If
848 sFile = SF_FileSystem._ConvertToUrl(FileName)
850 If Not IsNull(oComp) Then Set oOpen = CreateScriptService("SFDocuments.Document", oComp)
852 Finally:
853 Set OpenDocument = oOpen
854 SF_Utils._ExitFunction(cstThisSub)
855 Exit Function
856 Catch:
857 GoTo Finally
858 CatchError:
859 SF_Exception.RaiseFatal(DOCUMENTOPENERROR, "FileName", FileName, "Password", Password, "FilterName", FilterName)
860 GoTo Finally
861 End Function ' ScriptForge.SF_UI.OpenDocument
863 REM -----------------------------------------------------------------------------
864 Public Function Properties() As Variant
865 ''' Return the list or properties of the Timer class as an array
867 Properties = Array( _
873 )
875 End Function ' ScriptForge.SF_UI.Properties
877 REM -----------------------------------------------------------------------------
878 Public Sub Resize(Optional ByVal Left As Variant _
879 , Optional ByVal Top As Variant _
880 , Optional ByVal Width As Variant _
881 , Optional ByVal Height As Variant _
882 )
883 ''' Resizes and/or moves the active window. Negative arguments are ignored.
884 ''' If the window was minimized or without arguments, it is restored
885 ''' Args:
886 ''' Left, Top: Distances from top and left edges of the screen
887 ''' Width, Height: Dimensions of the window
888 ''' Examples:
890 ''' ...
892 Dim vWindow As Window ' A single component
893 Dim oContainer As Object ' com.sun.star.awt.XWindow
898 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
900 Check:
901 If IsMissing(Left) Or IsEmpty(Left) Then Left = -1
902 If IsMissing(Top) Or IsEmpty(Top) Then Top = -1
903 If IsMissing(Width) Or IsEmpty(Width) Then Width = -1
904 If IsMissing(Height) Or IsEmpty(Height) Then Height = -1
905 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
910 End If
912 Try:
913 vWindow = SF_UI._IdentifyWindow(StarDesktop.CurrentComponent)
914 If Not IsNull(vWindow.Frame) Then
915 Set oContainer = vWindow.Frame.ContainerWindow
916 iPosSize = 0
921 With oContainer
922 .IsMaximized = False
923 .IsMinimized = False
924 .setPosSize(Left, Top, Width, Height, iPosSize)
925 End With
926 End If
928 Finally:
929 SF_Utils._ExitFunction(cstThisSub)
930 Exit Sub
931 Catch:
932 GoTo Finally
933 End Sub ' ScriptForge.SF_UI.Resize
935 REM -----------------------------------------------------------------------------
936 Public Sub RunCommand(Optional ByVal Command As Variant _
937 , ParamArray Args As Variant _
938 )
939 ''' Run on the current window the given menu command. The command is executed with or without arguments
940 ''' A few typical commands:
941 ''' About, Delete, Edit, Undo, Copy, Paste, ...
942 ''' Dozens can be found on next page: https://wiki.documentfoundation.org/Development/DispatchCommands
943 ''' Args:
944 ''' Command: Case-sensitive. The command itself is not checked.
946 ''' If nothing happens, then the command is probably wrong
947 ''' Args: Pairs of arguments name (string), value (any)
948 ''' Returns:
949 ''' Examples:
956 Dim oDispatch ' com.sun.star.frame.DispatchHelper
957 Dim vProps As Variant ' Array of PropertyValues
958 Dim vValue As Variant ' A single value argument
959 Dim sCommand As String ' Alias of Command
960 Dim i As Long
966 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
968 Check:
969 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
973 If Not SF_Utils._Validate(Args(i), "Arg" & CStr(i/2) & "Name", V_STRING) Then GoTo Finally
974 Next i
975 End If
977 Try:
978 ' Build array of property values
979 vProps = Array()
982 vProps = SF_Array.Append(vProps, SF_Utils._MakePropertyValue(Args(i), vValue))
983 Next i
985 If SF_String.StartsWith(Command, cstPrefix) Then sCommand = Command Else sCommand = cstPrefix & Command
988 Finally:
989 SF_Utils._ExitFunction(cstThisSub)
990 Exit Sub
991 Catch:
992 GoTo Finally
993 End Sub ' ScriptForge.SF_UI.RunCommand
995 REM -----------------------------------------------------------------------------
996 Public Function SetProperty(Optional ByVal PropertyName As Variant _
997 , Optional ByRef Value As Variant _
998 ) As Boolean
999 ''' Set a new value to the given property
1000 ''' Args:
1001 ''' PropertyName: the name of the property as a string
1002 ''' Value: its new value
1003 ''' Exceptions
1004 ''' ARGUMENTERROR The property does not exist
1009 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
1010 SetProperty = False
1012 Check:
1013 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
1014 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
1015 End If
1017 Try:
1018 Select Case UCase(PropertyName)
1019 Case Else
1020 End Select
1022 Finally:
1023 SF_Utils._ExitFunction(cstThisSub)
1024 Exit Function
1025 Catch:
1026 GoTo Finally
1027 End Function ' ScriptForge.SF_UI.SetProperty
1029 REM -----------------------------------------------------------------------------
1030 Public Sub SetStatusbar(Optional ByVal Text As Variant _
1031 , Optional ByVal Percentage As Variant _
1032 )
1033 ''' Display a text and a progressbar in the status bar of the active window
1034 ''' Any subsequent calls in the same macro run refer to the same status bar of the same window,
1035 ''' even if the window is not active anymore
1036 ''' A call without arguments resets the status bar to its normal state.
1037 ''' Args:
1038 ''' Text: the optional text to be displayed before the progress bar
1040 ''' Examples:
1041 ''' Dim i As Integer
1045 ''' Next i
1046 ''' ui.SetStatusbar
1048 Dim oComp As Object
1049 Dim oControl As Object
1050 Dim oStatusbar As Object
1054 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
1056 Check:
1057 If IsMissing(Text) Or IsEmpty(Text) Then Text = ""
1058 If IsMissing(Percentage) Or IsEmpty(Percentage) Then Percentage = -1
1059 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
1062 End If
1064 Try:
1065 Set oStatusbar = _SF_.Statusbar
1066 With oStatusbar
1067 If IsNull(oStatusbar) Then ' Initial call
1068 Set oComp = StarDesktop.CurrentComponent
1069 If Not IsNull(oComp) Then
1070 Set oControl = Nothing
1071 If SF_Session.HasUnoProperty(oComp, "CurrentController") Then Set oControl = oComp.CurrentController
1072 If Not IsNull(oControl) Then
1073 If SF_Session.HasUnoMethod(oControl, "getStatusIndicator") Then oStatusbar = oControl.getStatusIndicator()
1074 End If
1075 End If
1076 If Not IsNull(oStatusbar) Then
1078 End If
1079 End If
1080 If Not IsNull(oStatusbar) Then
1082 .end()
1083 Set oStatusbar = Nothing
1084 Else
1087 End If
1088 End If
1089 End With
1091 Finally:
1092 Set _SF_.Statusbar = oStatusbar
1093 SF_Utils._ExitFunction(cstThisSub)
1094 Exit Sub
1095 Catch:
1096 GoTo Finally
1097 End Sub ' ScriptForge.SF_UI.SetStatusbar
1099 REM -----------------------------------------------------------------------------
1100 Public Sub ShowProgressBar(Optional Title As Variant _
1101 , Optional ByVal Text As Variant _
1102 , Optional ByVal Percentage As Variant _
1103 , Optional ByRef _Context As Variant _
1104 )
1105 ''' Display a non-modal dialog box. Specify its title, an explicatory text and the progress on a progressbar
1106 ''' A call without arguments erases the progress bar dialog.
1107 ''' The box will anyway vanish at the end of the macro run.
1108 ''' Args:
1109 ''' Title: the title appearing on top of the dialog box (Default = "ScriptForge")
1110 ''' Text: the optional text to be displayed above the progress bar (default = zero-length string)
1112 ''' _Context: from Python, the XComponentXontext (FOR INTERNAL USE ONLY)
1113 ''' Examples:
1114 ''' Dim i As Integer
1116 ''' ui.ShowProgressBar(, "Progress ... " & i & "/100", i)
1118 ''' Next i
1119 ''' ui.ShowProgressBar
1121 Dim bFirstCall As Boolean ' True at first invocation of method
1122 Dim oDialog As Object ' SFDialogs.Dialog object
1123 Dim oFixedText As Object ' SFDialogs.DialogControl object
1124 Dim oProgressBar As Object ' SFDialogs.DialogControl object
1125 Dim sTitle As String ' Alias of Title
1129 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
1131 Check:
1132 If IsMissing(Title) Or IsEmpty(Title) Then Title = ""
1133 If IsMissing(Text) Or IsEmpty(Text) Then Text = ""
1134 If IsMissing(Percentage) Or IsEmpty(Percentage) Then Percentage = -1
1135 If IsMissing(_Context) Or IsEmpty(_Context) Then _Context = Nothing
1136 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
1140 End If
1142 Try:
1143 With _SF_
1144 Set oDialog = .ProgressBarDialog
1145 Set oFixedText = .ProgressBarText
1146 Set oProgressBar = .ProgressBarBar
1147 End With
1148 With oDialog
1149 bFirstCall = ( IsNull(oDialog) )
1150 If Not bFirstCall Then bFirstCall = Not ._IsStillAlive(False) ' False to not raise an error
1151 If bFirstCall Then Set oDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", "ScriptForge", "dlgProgress", _Context)
1153 If Not IsNull(oDialog) Then
1155 Set oDialog = .Dispose()
1156 Else
1158 If bFirstCall Then
1161 .Execute(Modal := False)
1162 End If
1165 End If
1166 End If
1167 End With
1169 Finally:
1170 With _SF_
1171 Set .ProgressBarDialog = oDialog
1172 Set .ProgressBarText = oFixedText
1173 Set .ProgressBarBar = oProgressBar
1174 End With
1175 SF_Utils._ExitFunction(cstThisSub)
1176 Exit Sub
1177 Catch:
1178 GoTo Finally
1179 End Sub ' ScriptForge.SF_UI.ShowProgressBar
1181 REM -----------------------------------------------------------------------------
1182 Public Function WindowExists(Optional ByVal WindowName As Variant) As Boolean
1183 ''' Returns True if the specified window exists
1184 ''' Args:
1185 ''' WindowName: see definitions
1186 ''' Returns:
1187 ''' True if the given window is found
1188 ''' Examples:
1191 Dim bWindowExists As Boolean ' Return value
1192 Dim oEnum As Object ' com.sun.star.container.XEnumeration
1193 Dim oComp As Object ' com.sun.star.lang.XComponent
1194 Dim vWindow As Window ' A single component
1195 Dim oContainer As Object ' com.sun.star.awt.XWindow
1199 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
1200 bWindowExists = False
1202 Check:
1203 If IsMissing(WindowName) Or IsEmpty(WindowName) Then WindowName = ""
1204 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
1206 End If
1208 Try:
1209 Set oEnum = StarDesktop.Components().createEnumeration
1210 Do While oEnum.hasMoreElements
1211 Set oComp = oEnum.nextElement
1212 vWindow = SF_UI._IdentifyWindow(oComp)
1213 With vWindow
1214 ' Does the current window match the arguments ?
1215 If (Len(.WindowFileName) > 0 And .WindowFileName = SF_FileSystem.ConvertToUrl(WindowName)) _
1218 bWindowExists = True
1219 Exit Do
1220 End If
1221 End With
1222 Loop
1224 Finally:
1225 WindowExists = bWindowExists
1226 SF_Utils._ExitFunction(cstThisSub)
1227 Exit Function
1228 Catch:
1229 GoTo Finally
1230 End Function ' ScriptForge.SF_UI.WindowExists
1232 REM =========================================================== PRIVATE FUNCTIONS
1234 REM -----------------------------------------------------------------------------
1235 Public Sub _CloseProgressBar(Optional ByRef poEvent As Object)
1236 ''' Triggered by the Close button in the dlgProgress dialog
1237 ''' to simply close the dialog
1241 End Sub ' ScriptForge.SF_UI._CloseProgressBar
1243 REM -----------------------------------------------------------------------------
1244 Public Function _IdentifyWindow(ByRef poComponent As Object) As Object
1245 ''' Return a Window object (definition on top of module) based on component given as argument
1246 ''' Is a shortcut to explore the most relevant properties or objects bound to a UNO component
1248 Dim oWindow As Window ' Return value
1251 Dim vSelection As Variant ' Array of poCOmponent.Selection property values
1252 Dim iCommandType As Integer ' Datasheet type
1253 Dim FSO As Object ' Alias for SF_FileSystem
1255 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
1256 Set _IdentifyWindow = Nothing
1259 Set FSO = SF_FileSystem
1260 With oWindow
1261 Set .Frame = Nothing
1262 Set .Component = Nothing
1263 .WindowName = ""
1264 .WindowTitle = ""
1265 .WindowFileName = ""
1266 .DocumentType = ""
1267 .ParentName = ""
1268 If IsNull(poComponent) Then GoTo Finally
1269 If SF_Session.HasUnoProperty(poComponent, "ImplementationName") Then sImplementation = poComponent.ImplementationName
1270 If SF_Session.HasUnoProperty(poComponent, "Identifier") Then sIdentifier = poComponent.Identifier
1271 Set .Component = poComponent
1272 Select Case sImplementation
1274 .WindowName = BASICIDE
1277 If Len(.WindowFileName) > 0 Then .WindowName = FSO.GetName(FSO._ConvertFromUrl(.WindowFileName))
1278 .DocumentType = BASEDOCUMENT
1279 Case "org.openoffice.comp.dbu.ODatasourceBrowser" ' Base datasheet (table, query or sql in read mode
1280 Set .Frame = poComponent.Frame
1281 If Not IsEmpty(poComponent.Selection) Then ' Empty for (F4) DatasourceBrowser !!
1282 vSelection = poComponent.Selection
1285 Select Case iCommandType
1286 Case com.sun.star.sdb.CommandType.TABLE : .DocumentType = TABLEDATA
1287 Case com.sun.star.sdb.CommandType.QUERY : .DocumentType = QUERYDATA
1288 Case com.sun.star.sdb.CommandType.COMMAND : .DocumentType = SQLDATA
1289 End Select
1291 .WindowTitle = .WindowName
1292 End If
1293 Case "org.openoffice.comp.dbu.OTableDesign", "org.openoffice.comp.dbu.OQueryDesign" ' Table or Query in Edit mode
1296 Set .Frame = poComponent.Frame
1297 .WindowName = WELCOMESCREEN
1298 Case Else
1300 ' Do not use URL : it contains the TemplateFile when new documents are created from a template
1301 .WindowFileName = poComponent.Location
1302 If Len(.WindowFileName) > 0 Then .WindowName = FSO.GetName(FSO._ConvertFromUrl(.WindowFileName))
1303 If SF_Session.HasUnoProperty(poComponent, "Title") Then .WindowTitle = poComponent.Title
1304 Select Case sIdentifier
1308 .DocumentType = WRITERDOCUMENT
1310 .DocumentType = CALCDOCUMENT
1312 .DocumentType = IMPRESSDOCUMENT
1314 .DocumentType = DRAWDOCUMENT
1316 .DocumentType = MATHDOCUMENT
1317 Case Else
1318 End Select
1319 End If
1320 End Select
1321 If IsNull(.Frame) Then
1322 If Not IsNull(poComponent.CurrentController) Then Set .Frame = poComponent.CurrentController.Frame
1323 End If
1324 End With
1326 Finally:
1327 Set _IdentifyWindow = oWindow
1328 Exit Function
1329 Catch:
1330 GoTo Finally
1331 End Function ' ScriptForge.SF_UI._IdentifyWindow
1333 REM -----------------------------------------------------------------------------
1334 Public Function _PosSize() As Object
1335 ''' Returns the PosSize structure of the active window
1337 Dim vWindow As Window ' A single component
1338 Dim oContainer As Object ' com.sun.star.awt.XWindow
1339 Dim oPosSize As Object ' com.sun.star.awt.Rectangle
1341 Set oPosSize = Nothing
1343 Try:
1344 vWindow = SF_UI._IdentifyWindow(StarDesktop.CurrentComponent)
1345 If Not IsNull(vWindow.Frame) Then
1346 Set oContainer = vWindow.Frame.ContainerWindow
1347 Set oPosSize = oContainer.getPosSize()
1348 End If
1350 Finally:
1351 Set _PosSize = oPosSize
1352 Exit Function
1353 End Function ' ScriptForge.SF_UI._PosSize
1355 REM -----------------------------------------------------------------------------
1356 Private Function _Repr() As String
1357 ''' Convert the UI instance to a readable string, typically for debugging purposes (DebugPrint ...)
1358 ''' Args:
1359 ''' Return:
1364 End Function ' ScriptForge.SF_UI._Repr
1366 REM ============================================ END OF SCRIPTFORGE.SF_UI
1367 </script:module>