| blob | 4639739089d526a5c77780de237b3f91d5482f07 |
3 <script:module xmlns:script="http://openoffice.org/2000/script" script:name="SF_Register" script:language="StarBasic" script:moduleType="normal">REM =======================================================================================================================
4 REM === The ScriptForge library and its associated libraries are part of the LibreOffice project. ===
5 REM === The SFDialogs library is one of the associated libraries. ===
6 REM === Full documentation is available on https://help.libreoffice.org/ ===
7 REM =======================================================================================================================
9 Option Compatible
10 Option Explicit
12 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
13 ''' SF_Register
14 ''' ===========
15 ''' The ScriptForge framework includes
16 ''' the master ScriptForge library
18 ''' any user/contributor extension wanting to fit into the framework
19 '''
20 ''' The main methods in this module allow the current library to cling to ScriptForge
21 ''' - RegisterScriptServices
22 ''' Register the list of services implemented by the current library
23 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
25 REM ================================================================= DEFINITIONS
27 ''' Event management of dialogs requires to being able to rebuild a Dialog object
28 ''' from its com.sun.star.awt.XControl - stardiv.Toolkit.UnoDialogControl UNO instance
29 ''' For that purpose, the started dialogs are buffered in a global array of _DialogCache types
31 Type _DialogCache
32 Terminated As Boolean
33 XUnoDialog As Object
34 BasicDialog As Object
35 End Type
37 REM ================================================================== EXCEPTIONS
41 REM ============================================================== PUBLIC METHODS
43 REM -----------------------------------------------------------------------------
44 Public Sub RegisterScriptServices() As Variant
45 ''' Register into ScriptForge the list of the services implemented by the current library
46 ''' Each library pertaining to the framework must implement its own version of this method
47 '''
48 ''' It consists in successive calls to the RegisterService() and RegisterEventManager() methods
50 ''' ServiceName: the name of the service as a case-insensitive string
51 ''' ServiceReference: the reference as an object
52 ''' If the reference refers to a module, then return the module as an object:
53 ''' GlobalScope.Library.Module
54 ''' If the reference is a class instance, then return a string referring to the method
55 ''' containing the New statement creating the instance
58 With GlobalScope.ScriptForge.SF_Services
59 .RegisterService("Dialog", "SFDialogs.SF_Register._NewDialog") ' Reference to the function initializing the service
60 .RegisterEventManager("DialogEvent", "SFDialogs.SF_Register._EventManager") ' Reference to the events manager
61 .RegisterEventManager("NewDialog", "SFDialogs.SF_Register._NewDialogFromScratch") ' Reference to the function initializing the service
62 End With
64 End Sub ' SFDialogs.SF_Register.RegisterScriptServices
66 REM =========================================================== PRIVATE FUNCTIONS
68 REM -----------------------------------------------------------------------------
69 Private Function _AddDialogToCache(ByRef pvUnoDialog As Object _
70 , ByRef pvBasicDialog As Object _
71 ) As Long
72 ''' Add a new entry in the cache array with the references of the actual dialog
73 ''' If relevant, the last entry of the cache is reused.
74 ''' The cache is located in the global _SF_ variable
75 ''' Args:
76 ''' pvUnoDialog: the com.sun.star.awt.XControl - stardiv.Toolkit.UnoDialogControl of the dialog box
77 ''' pvBasicDialog: its corresponding Basic object
78 ''' Returns:
79 ''' The index of the new or modified entry
81 Dim vCache As New _DialogCache ' Entry to be added
82 Dim lIndex As Long ' UBound of _SF_.SFDialogs
83 Dim vCacheArray As Variant ' Alias of _SF_.SFDialogs
85 Try:
86 vCacheArray = _SF_.SFDialogs
88 If IsEmpty(vCacheArray) Then vCacheArray = Array()
89 lIndex = UBound(vCacheArray)
90 If lIndex < LBound(vCacheArray) Then
92 lIndex = 0
93 ElseIf Not vCacheArray(lIndex).Terminated Then ' Often last entry can be reused
94 lIndex = lIndex + 1
95 ReDim Preserve vCacheArray(0 To lIndex)
96 End If
98 With vCache
99 .Terminated = False
100 Set .XUnoDialog = pvUnoDialog
101 Set .BasicDialog = pvBasicDialog
102 End With
103 vCacheArray(lIndex) = vCache
105 _SF_.SFDialogs = vCacheArray
107 Finally:
108 _AddDialogToCache = lIndex
109 Exit Function
110 End Function ' SFDialogs.SF_Register._AddDialogToCache
112 REM -----------------------------------------------------------------------------
113 Private Sub _CleanCacheEntry(ByVal plIndex As Long)
114 ''' Clean the plIndex-th entry in the dialogs cache
115 ''' Args:
116 ''' plIndex: must fit within the actual boundaries of the cache, otherwise the request is ignored
118 Dim vCache As New _DialogCache ' Cleaned entry
120 With _SF_
121 If Not IsArray(.SFDialogs) Then Exit Sub
124 With vCache
125 .Terminated = True
126 Set .XUnoDialog = Nothing
127 Set .BasicDialog = Nothing
128 End With
129 .SFDialogs(plIndex) = vCache
130 End With
132 Finally:
133 Exit Sub
134 End Sub ' SFDialogs.SF_Register._CleanCacheEntry
136 REM -----------------------------------------------------------------------------
137 Public Function _EventManager(Optional ByRef pvArgs As Variant) As Object
138 ''' Returns a Dialog or DialogControl object corresponding with the Basic dialog
139 ''' which triggered the event in argument
140 ''' This method should be triggered only thru the invocation of CreateScriptService
141 ''' Args:
142 ''' pvEvent: com.sun.star.xxx
143 ''' Returns:
144 ''' the output of a Dialog or DialogControl service or Nothing
145 ''' Example:
146 ''' Sub TriggeredByEvent(ByRef poEvent As Object)
147 ''' Dim oDlg As Object
149 ''' If Not IsNull(oDlg) Then
150 ''' ' ... (a valid dialog or one of its controls has been identified)
151 ''' End Sub
153 Dim oSource As Object ' Return value
154 Dim oEventSource As Object ' Event UNO source
156 Dim sSourceType As String ' Implementation name of event source
157 Dim oDialog As Object ' com.sun.star.awt.XControl - stardiv.Toolkit.UnoDialogControl
158 Dim bControl As Boolean ' True when control event
160 ' Never abort while an event is processed
161 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Finally
162 Set oSource = Nothing
164 Check:
165 If IsMissing(pvArgs) Or IsEmpty(pvArgs) Then pvArgs = Array()
167 If VarType(vEvent) <> ScriptForge.V_OBJECT Then GoTo Finally
170 Try:
171 Set oEventSource = vEvent.Source
172 sSourceType = ScriptForge.SF_Session.UnoObjectType(oEventSource)
174 Set oDialog = Nothing
175 Select Case True
177 ' Search the dialog in the cache
178 Set oDialog = _FindDialogInCache(oEventSource)
179 bControl = False
181 Set oDialog = _FindDialogInCache(oEventSource.Context)
182 bControl = True
183 Case Else
184 End Select
186 If Not IsNull(oDialog) Then
187 If bControl Then Set oSource = oDialog.Controls(oEventSource.Model.Name) Else Set oSource = oDialog
188 End If
190 Finally:
191 Set _EventManager = oSource
192 Exit Function
193 End Function ' SFDialogs.SF_Register._EventManager
195 REM -----------------------------------------------------------------------------
196 Private Function _FindDialogInCache(ByRef poDialog As Object) As Object
197 ''' Find the dialog based on its XUnoDialog
198 ''' The dialog must not be terminated
199 ''' Returns:
200 ''' The corresponding Basic dialog part or Nothing
202 Dim oBasicDialog As Object ' Return value
203 Dim oCache As _DialogCache ' Entry in the cache
205 Set oBasicDialog = Nothing
207 Try:
208 For Each oCache In _SF_.SFDialogs
209 If EqualUnoObjects(poDialog, oCache.XUnoDialog) And Not oCache.Terminated Then
210 Set oBasicDialog = oCache.BasicDialog
211 Exit For
212 End If
213 Next oCache
215 Finally:
216 Set _FindDialogInCache = oBasicDialog
217 Exit Function
218 End Function ' SFDialogs.SF_Register._FindDialogInCache
220 REM -----------------------------------------------------------------------------
221 Public Function _NewDialog(Optional ByVal pvArgs As Variant) As Object
222 ''' Create a new instance of the SF_Dialog class
223 ''' Args:
224 ''' Container: either "GlobalScope" or a WindowName. Default = the active window
225 ''' see the definition of WindowName in the description of the UI service
226 ''' Library: the name of the library hosting the dialog. Default = "Standard"
227 ''' DialogName: The name of the dialog
228 ''' Library and dialog names are case-sensitive
229 ''' Context: When called from Python, the context must be provided : XSCRIPTCONTEXT
230 ''' Returns: the instance or Nothing
232 Dim oDialog As Object ' Return value
236 Dim oLibraries As Object ' com.sun.star.comp.sfx2.DialogLibraryContainer
237 Dim vContext As Variant ' com.sun.star.uno.XComponentContext
238 Dim oDialogProvider As Object ' com.sun.star.io.XInputStreamProvider
239 Dim oEnum As Object ' com.sun.star.container.XEnumeration
240 Dim oComp As Object ' com.sun.star.lang.XComponent
241 Dim oDialogControl As Object ' com.sun.star.awt.XControl - stardiv.Toolkit.UnoDialogControl
242 Dim vWindow As Window ' A single component
244 Dim sURI As String ' URI of the targeted dialog
246 Dim bFound As Boolean ' True if WindowName is found on the desktop
250 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
252 Check:
253 If IsMissing(pvArgs) Or IsEmpty(pvArgs) Then pvArgs = Array()
254 If Not IsArray(pvArgs) Then pvArgs = Array(pvArgs)
258 If UBound(pvArgs) >= 2 Then vDialogName = pvArgs(2) Else vDialogName = Empty ' Use Empty to force mandatory status
260 If Not ScriptForge.SF_Utils._Validate(vContainer, "Container", Array(V_STRING, ScriptForge.V_OBJECT)) Then GoTo Finally
261 If Not ScriptForge.SF_Utils._Validate(vLibrary, "Library", V_STRING) Then GoTo Finally
262 If Not ScriptForge.SF_Utils._Validate(vDialogName, "DialogName", V_STRING) Then GoTo Finally
264 If Not ScriptForge.SF_Utils._Validate(vContext, "Context", ScriptForge.V_OBJECT) Then GoTo Finally
266 Set oDialog = Nothing
268 Try:
269 ' Determine the library container hosting the dialog
271 Set oComp = Nothing
272 If VarType(vContainer) = V_STRING Then
273 bFound = ( UCase(vContainer) = UCase(cstGlobal) )
274 End If
275 If Not bFound Then
276 Select Case VarType(vContainer)
277 Case V_STRING
279 bFound = False
280 Set oEnum = StarDesktop.Components().createEnumeration
281 Do While oEnum.hasMoreElements
282 Set oComp = oEnum.nextElement
283 vWindow = oUi._IdentifyWindow(oComp)
284 With vWindow
285 ' Does the current window match the argument ?
286 If (Len(.WindowFileName) > 0 And .WindowFileName = ScriptForge.SF_FileSystem._ConvertToUrl(vContainer)) _
289 bFound = True
290 Exit Do
291 End If
292 End With
293 Loop
294 Else
295 bFound = True
296 Set oComp = StarDesktop.CurrentComponent
297 vWindow = oUi._IdentifyWindow(oComp)
298 End If
299 Case V_OBJECT ' com.sun.star.lang.XComponent
300 bFound = True
301 vWindow = oUi._IdentifyWindow(vContainer)
302 Set oComp = vContainer
303 End Select
304 If Not bFound Then GoTo CatchNotFound
305 If Len(vWindow.DocumentType) = 0 Then GoTo CatchNotFound
306 End If
308 ' Determine the dialog provider
309 Select Case True
310 Case IsNull(vContext) And IsNull(oComp) ' Basic and GlobalScope
311 Set oDialogProvider = GetProcessServiceManager.createInstance("com.sun.star.awt.DialogProvider")
312 Case IsNull(vContext) And Not IsNull(oComp) ' Basic and Document
313 Set oDialogProvider = GetProcessServiceManager.createInstanceWithArguments("com.sun.star.awt.DialogProvider", Array(oComp))
314 Case Not IsNull(vContext) And IsNull(oComp) ' Python and GlobalScope
315 Set oDialogProvider = vContext.getServiceManager().createInstanceWithContext("com.sun.star.awt.DialogProvider", vContext)
316 Case Not IsNull(vContext) And Not IsNull(oComp) ' Python and Document
317 Set oDialogProvider = vContext.getServiceManager().createInstanceWithArguments("com.sun.star.awt.DialogProvider", Array(oComp))
318 End Select
320 ' Create the graphical interface
322 sURI = "vnd.sun.star.script:" & vLibrary & "." & vDialogName & "?location=" & sScope
323 On Local Error GoTo CatchNotFound
324 Set oDialogControl = oDialogProvider.createDialog(sURI)
326 ' Initialize the basic SF_Dialog instance to return to the user script
327 Set oDialog = New SF_Dialog
328 With oDialog
329 Set .[Me] = oDialog
330 If VarType(vContainer) = V_STRING Then ._Container = vContainer Else ._Container = vWindow.WindowName
331 ._Library = vLibrary
332 ._Name = vDialogName
333 Set ._DialogProvider = oDialogProvider
334 Set ._DialogControl = oDialogControl
335 ._Initialize()
336 End With
338 Finally:
339 Set _NewDialog = oDialog
340 Exit Function
341 Catch:
342 GoTo Finally
343 CatchNotFound:
345 , "Container", vContainer, "Library", vLibrary, "DialogName", vDialogName)
346 GoTo Finally
347 End Function ' SFDialogs.SF_Register._NewDialog
349 REM -----------------------------------------------------------------------------
350 Private Function _NewDialogFromScratch(Optional ByVal pvArgs As Variant) As Object
351 ''' Create a new instance of the SF_Dialog class describing a dynamically defined dialog box
352 ''' Args:
353 ''' DialogName: a symbolic name of the dialog to create, for information only. Not checked for unicity.
354 ''' Place: either
356 ''' - a com.sun.star.awt.Rectangle [X, Y, Width, Height]
358 ''' Context: When called from Python, the context must be provided : XSCRIPTCONTEXT
359 ''' Returns: the instance or Nothing
361 Dim oDialog As Object ' Return value
362 Dim vDialogName As Variant ' The name is for information only
363 Dim vPlace As variant ' com.sun.star.awt.rectangle or array(X, Y, Width, Height)
364 Dim oPlace As Object ' com.sun.star.awt.rectangle
365 Dim oProcessManager As Object ' com.sun.star.lang.XMultiServiceFactory
366 Dim bBuiltInPython As Boolean ' True when context is present
367 Dim oModel As Object ' com.sun.star.awt.UnoControlDialogModel
368 Dim oView As Object ' com.sun.star.awt.UnoControlDialog
369 Dim vContext As Variant ' com.sun.star.uno.XComponentContext
374 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
376 Check:
377 If IsMissing(pvArgs) Or IsEmpty(pvArgs) Then pvArgs = Array()
378 If Not IsArray(pvArgs) Then pvArgs = Array(pvArgs)
380 If UBound(pvArgs) >= 1 Then vPlace = pvArgs(1) Else vPlace = Empty ' Use Empty to force the mandatory status
384 If Not ScriptForge.SF_Utils._Validate(vDialogName, "DialogName", V_STRING) Then GoTo Finally
385 If IsArray(vPlace) Then
386 If Not ScriptForge.SF_Utils._ValidateArray(vPlace, "Place", 1, ScriptForge.V_NUMERIC, True) Then GoTo Finally
387 Else
388 If Not ScriptForge.SF_Utils._Validate(vPlace, "Place", ScriptForge.V_OBJECT) Then GoTo Finally
389 End If
390 If Not ScriptForge.SF_Utils._Validate(vContext, "Context", ScriptForge.V_OBJECT) Then GoTo Finally
392 Set oDialog = Nothing
394 Try:
395 ' Determine the process service manager and create the dialog model
396 If IsNull(vContext) Then ' Basic
397 Set oprocessManager = GetProcessServiceManager()
398 Set oModel = oProcessManager.createInstance(cstDialogModel)
399 bBuiltInPython = False
400 Else ' Python
401 Set oprocessManager = vContext.getServiceManager()
402 Set oModel = oProcessManager.createInstanceWithContext(cstDialogModel, vContext)
403 bBuiltInPython = True
404 End If
406 oModel.Name = vDialogName
408 ' Set dimension and position
409 With oModel
410 If IsArray(vPlace) Then
411 If UBound(vPlace) = 3 Then
412 .PositionX = vPlace(0)
413 .PositionY = vPlace(1)
414 .Width = vPlace(2)
415 .Height = vPlace(3)
416 End If
417 ElseIf ScriptForge.SF_Session.UnoObjectType(vPlace) = "com.sun.star.awt.Rectangle" Then
418 Set oPlace = vPlace
419 .PositionX = oPlace.X
420 .PositionY = oPlace.Y
421 .Width = oPlace.Width
422 .Height = oPlace.Height
423 Else
424 'Leave everything to zero
425 End If
426 End With
428 ' Create the view and associate model and view
429 Set oView = oProcessManager.createInstance(cstDialogView)
430 oView.setModel(oModel)
432 ' Initialize the basic SF_Dialog instance to return to the user script
433 Set oDialog = New SF_Dialog
434 With oDialog
435 Set .[Me] = oDialog
436 ._Container = ""
437 ._Library = ""
438 ._BuiltFromScratch = True
439 ._BuiltInPython = bBuiltInPython
440 ._Name = vDialogName
441 Set ._DialogProvider = Nothing
442 Set ._DialogControl = oView
443 ._Initialize()
444 End With
446 Finally:
447 Set _NewDialogFromScratch = oDialog
448 Exit Function
449 Catch:
450 GoTo Finally
451 End Function ' SFDialogs.SF_Register._NewDialogFromScratch
453 REM ============================================== END OF SFDIALOGS.SF_REGISTER
454 </script:module>