| blob | 5c0feaec5c6333413ebb3808a63623530186cb55 |
3 <script:module xmlns:script="http://openoffice.org/2000/script" script:name="SF_Base" 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 SFDocuments 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 ClassModule
12 Option Explicit
14 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
15 ''' SF_Base
16 ''' =======
17 '''
18 ''' The SFDocuments library gathers a number of methods and properties making easy
19 ''' the management and several manipulations of LibreOffice documents
20 '''
21 ''' Some methods are generic for all types of documents: they are combined in the SF_Document module.
22 ''' Specific properties and methods are implemented in the concerned subclass(es) SF_Calc, SF_Writer, ...
23 '''
24 ''' To workaround the absence of class inheritance in LibreOffice Basic, some redundancy is necessary
25 ''' Each subclass MUST implement also the generic methods and properties, even if they only call
26 ''' the parent methods and properties.
27 ''' They should also duplicate some generic private members as a subset of their own set of members
28 '''
29 ''' The SF_Base module is provided mainly to block parent properties that are NOT applicable to Base documents
30 ''' In addition, it provides methods to identify form documents and access their internal forms
31 ''' (read more elsewhere (the "SFDocuments.Form" service) about this subject)
32 '''
33 ''' The current module is closely related to the "UI" service of the ScriptForge library
34 '''
35 ''' Service invocation examples:
37 ''' Dim ui As Object, oDoc As Object
42 ''' Dim oDoc As Object
43 ''' Set oDoc = CreateScriptService("SFDocuments.Base", "MyFile.odb")
45 '''
46 ''' Detailed user documentation:
47 ''' https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/sf_base.html?DbPAR=BASIC
48 '''
49 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
51 REM ================================================================== EXCEPTIONS
57 REM ============================================================= PRIVATE MEMBERS
59 Private [Me] As Object
60 Private [_Parent] As Object
61 Private [_Super] As Object ' Document superclass, which the current instance is a subclass of
62 Private ObjectType As String ' Must be BASE
63 Private ServiceName As String
65 ' UNO references
66 Private _Component As Object ' com.sun.star.comp.dba.ODatabaseDocument
67 Private _DataSource As Object ' com.sun.star.comp.dba.ODatabaseSource
68 Private _Database As Object ' SFDatabases.Database service instance
69 Private _FormDocuments As Object
71 REM ============================================================ MODULE CONSTANTS
76 REM ====================================================== CONSTRUCTOR/DESTRUCTOR
78 REM -----------------------------------------------------------------------------
79 Private Sub Class_Initialize()
80 Set [Me] = Nothing
81 Set [_Parent] = Nothing
82 Set [_Super] = Nothing
85 Set _Component = Nothing
86 Set _DataSource = Nothing
87 Set _Database = Nothing
88 Set _FormDocuments = Nothing
89 End Sub ' SFDocuments.SF_Base Constructor
91 REM -----------------------------------------------------------------------------
92 Private Sub Class_Terminate()
93 Call Class_Initialize()
94 End Sub ' SFDocuments.SF_Base Destructor
96 REM -----------------------------------------------------------------------------
97 Public Function Dispose() As Variant
98 If Not IsNull([_Super]) Then Set [_Super] = [_Super].Dispose()
99 Call Class_Terminate()
100 Set Dispose = Nothing
101 End Function ' SFDocuments.SF_Base Explicit Destructor
103 REM ================================================================== PROPERTIES
105 REM ===================================================================== METHODS
107 REM -----------------------------------------------------------------------------
108 Public Function CloseDocument(Optional ByVal SaveAsk As Variant) As Boolean
109 ''' The closure of a Base document requires the closures of
117 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
119 Check:
120 If IsMissing(SaveAsk) Or IsEmpty(SaveAsk) Then SaveAsk = True
121 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
122 If Not _IsStillAlive(True) Then GoTo Finally
123 If Not ScriptForge.SF_Utils._Validate(SaveAsk, "SaveAsk", ScriptForge.V_BOOLEAN) Then GoTo Finally
124 End If
126 Try:
127 If Not IsNull(_Database) Then _Database.CloseDatabase()
128 If Not IsNull(_DataSource) Then _DataSource.dispose()
129 CloseDocument = [_Super].CloseDocument(SaveAsk)
131 Finally:
132 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
133 Exit Function
134 Catch:
135 GoTo Finally
136 End Function ' SFDocuments.SF_Base.CloseDocument
138 REM -----------------------------------------------------------------------------
139 Public Function CloseFormDocument(Optional ByVal FormDocument As Variant) As Boolean
140 ''' Close the given form document
141 ''' Nothing happens if the form document is not open
142 ''' Args:
143 ''' FormDocument: a valid document form name as a case-sensitive string
144 ''' Returns:
145 ''' True if closure is successful
146 ''' Example:
148 ''' DEPRECATED - Use preferably the CloseDocument() method of the FormDocument service
150 Dim bClose As Boolean ' Return value
151 Dim oMainForm As Object ' com.sun.star.comp.sdb.Content
152 Dim vFormNames As Variant ' Array of all document form names present in the document
157 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
158 bClose = False
160 Check:
161 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
162 If Not _IsStillAlive() Then GoTo Finally
163 ' Build list of available FormDocuments recursively with _CollectFormDocuments
164 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
165 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
166 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames, True) Then GoTo Finally
167 End If
168 If Not IsLoaded(FormDocument) Then GoTo Finally
170 Try:
171 Set oMainForm = _FormDocuments.getByHierarchicalName(FormDocument)
172 bClose = oMainForm.close()
174 Finally:
175 CloseFormDocument = bClose
176 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
177 Exit Function
178 Catch:
179 GoTo Finally
180 End Function ' SFDocuments.SF_Base.CloseFormDocument
182 REM -----------------------------------------------------------------------------
183 Public Function FormDocuments() As Variant
184 ''' Return the list of the FormDocuments contained in the Base document
185 ''' Args:
186 ''' Returns:
187 ''' A zero-base array of strings
188 ''' Each entry is the full path name of a form document. The path separator is the slash ("/")
189 ''' Example:
190 ''' Dim myForm As Object, myList As Variant
191 ''' myList = oDoc.FormDocuments()
193 Dim vFormNames As Variant ' Array of all form names present in the document
195 Const cstSubArgs = ""
197 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
199 Check:
200 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
201 If Not _IsStillAlive() Then GoTo Finally
202 End If
204 Try:
205 ' Build list of available FormDocuments recursively with _CollectFormDocuments
206 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
207 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
209 Finally:
210 FormDocuments = vFormNames
211 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
212 Exit Function
213 Catch:
214 GoTo Finally
215 End Function ' SFDocuments.SF_Base.FormDocuments
217 REM -----------------------------------------------------------------------------
218 Public Function Forms(Optional ByVal FormDocument As Variant _
219 , Optional ByVal Form As Variant _
220 ) As Variant
221 ''' Return either
222 ''' - the list of the Forms contained in the form document
223 ''' - a SFDocuments.Form object based on its name or its index
224 ''' Args:
225 ''' FormDocument: a valid document form name as a case-sensitive string
226 ''' Form: a form stored in the Base document given by its name or its index
227 ''' When absent, the list of available forms is returned
229 ''' Returns:
230 ''' A zero-based array of strings if Form is absent
231 ''' An instance of the SF_Form class if Form exists
232 ''' Exceptions:
233 ''' FORMDEADERROR The form is not open
234 ''' BASEFORMNOTFOUNDERROR FormDocument OK but Form not found
235 ''' Example:
236 ''' Dim myForm As Object, myList As Variant
239 ''' DEPRECATED - Use preferably the Forms() method of the FormDocument service
241 Dim oForm As Object ' The new Form class instance
242 Dim oFormDocument As Object ' com.sun.star.comp.sdb.Content
243 Dim oXForm As Object ' com.sun.star.form.XForm
244 Dim vFormDocuments As Variant ' Array of form documents
245 Dim vFormNames As Variant ' Array of form names
246 Dim oForms As Object ' Forms collection
252 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
254 Check:
255 If IsMissing(Form) Or IsEmpty(Form) Then Form = ""
256 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
257 If Not _IsStillAlive() Then GoTo Finally
258 ' Build list of available FormDocuments recursively with _CollectFormDocuments
259 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
260 vFormDocuments = Split(_CollectFormDocuments(_FormDocuments), cstToken)
261 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormDocuments, True) Then GoTo Finally
262 If Not ScriptForge.SF_Utils._Validate(Form, "Form", Array(V_STRING, ScriptForge.V_NUMERIC)) Then GoTo Finally
263 End If
264 If Not IsLoaded(FormDocument) Then GoTo CatchClosed
266 Try:
267 ' Start from the form document and go down to forms
268 Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
269 Set oForms = oFormDocument.Component.DrawPages(cstDrawPage).Forms
270 vFormNames = oForms.getElementNames()
273 Forms = vFormNames
274 Else
275 If VarType(Form) = V_STRING Then ' Find the form by name
276 If Not ScriptForge.SF_Utils._Validate(Form, "Form", V_STRING, vFormNames, True) Then GoTo Finally
277 Set oXForm = oForms.getByName(Form)
278 Else ' Find the form by index
280 Set oXForm = oForms.getByIndex(Form)
281 End If
282 ' Create the new Form class instance
283 Set oForm = New SF_Form
284 With oForm
285 ._Name = oXForm.Name
286 Set .[Me] = oForm
287 Set .[_Parent] = [Me]
288 Set ._Component = oFormDocument.Component
289 Set ._BaseComponent = _Component
290 ._FormDocumentName = FormDocument
291 Set ._FormDocument = oFormDocument
292 ._FormType = ISBASEFORM
293 Set ._Form = oXForm
294 ._Initialize()
295 End With
296 Set Forms = oForm
297 End If
299 Finally:
300 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
301 Exit Function
302 Catch:
303 GoTo Finally
304 CatchClosed:
305 ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
306 CatchNotFound:
307 ScriptForge.SF_Exception.RaiseFatal(BASEFORMNOTFOUNDERROR, Form, FormDocument, _FileIdent())
308 End Function ' SFDocuments.SF_Base.Forms
310 REM -----------------------------------------------------------------------------
311 Public Function GetDatabase(Optional ByVal User As Variant _
312 , Optional ByVal Password As Variant _
313 ) As Object
314 ''' Returns a Database instance (service = SFDatabases.Database) giving access
315 ''' to the execution of SQL commands on the database defined and/or stored in
316 ''' the actual Base document
317 ''' Args:
319 ''' Returns:
320 ''' A SFDatabases.Database instance or Nothing
321 ''' Example:
322 ''' Dim myDb As Object
323 ''' Set myDb = oDoc.GetDatabase()
326 Const cstSubArgs = "[User=""""], [Password=""""]"
328 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
329 Set GetDatabase = Nothing
331 Check:
332 If IsMissing(User) Or IsEmpty(User) Then User = ""
333 If IsMissing(Password) Or IsEmpty(Password) Then Password = ""
334 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
335 If Not _IsStillAlive(True) Then GoTo Finally
337 If Not ScriptForge.SF_Utils._Validate(Password, "Password", V_STRING) Then GoTo Finally
338 End If
340 Try:
342 If IsNull(_DataSource) Then GoTo CatchConnect
343 Set _Database = ScriptForge.SF_Services.CreateScriptService("SFDatabases.DatabaseFromDocument" _
344 , _DataSource, User, Password)
345 If IsNull(_Database) Then GoTo CatchConnect
346 _Database._Location = [_Super]._WindowFileName
347 EndIf
349 Finally:
350 Set GetDatabase = _Database
351 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
352 Exit Function
353 Catch:
354 GoTo Finally
355 CatchConnect:
356 ScriptForge.SF_Exception.RaiseFatal(DBCONNECTERROR, "User", User, "Password", Password, [_Super]._FileIdent())
357 GoTo Finally
358 End Function ' SFDocuments.SF_Base.GetDatabase
360 REM -----------------------------------------------------------------------------
361 Public Function GetProperty(Optional ByVal PropertyName As Variant) As Variant
362 ''' Return the actual value of the given property
363 ''' Args:
364 ''' PropertyName: the name of the property as a string
365 ''' Returns:
366 ''' The actual value of the property
367 ''' Exceptions:
368 ''' ARGUMENTERROR The property does not exist
371 Const cstSubArgs = ""
373 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
374 GetProperty = Null
376 Check:
377 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
378 If Not ScriptForge.SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
379 End If
381 Try:
382 ' Superclass or subclass property ?
383 If ScriptForge.SF_Array.Contains([_Super].Properties(), PropertyName) Then
384 GetProperty = [_Super].GetProperty(PropertyName)
385 Else
386 GetProperty = _PropertyGet(PropertyName)
387 End If
389 Finally:
390 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
391 Exit Function
392 Catch:
393 GoTo Finally
394 End Function ' SFDocuments.SF_Base.GetProperty
396 REM -----------------------------------------------------------------------------
397 Public Function IsLoaded(Optional ByVal FormDocument As Variant) As Boolean
398 ''' Return True if the given FormDocument is open for the user
399 ''' Args:
400 ''' FormDocument: a valid document form name as a case-sensitive string
401 ''' Returns:
402 ''' True if the form document is currently open, otherwise False
403 ''' Exceptions:
404 ''' Form name is invalid
405 ''' Example:
408 Dim bLoaded As Boolean ' Return value
409 Dim vFormNames As Variant ' Array of all document form names present in the document
410 Dim oMainForm As Object ' com.sun.star.comp.sdb.Content
414 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
415 bLoaded = False
417 Check:
418 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
419 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
420 If Not _IsStillAlive() Then GoTo Finally
421 ' Build list of available FormDocuments recursively with _CollectFormDocuments
422 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
423 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames, True) Then GoTo Finally
424 End If
426 Try:
427 Set oMainForm = _FormDocuments.getByHierarchicalName(FormDocument)
428 ' A document form that has never been opened has no component
429 ' If ever opened and closed afterwards, it keeps the Component but loses its Controller
430 bLoaded = Not IsNull(oMainForm.Component)
431 If bLoaded Then bLoaded = Not IsNull(oMainForm.Component.CurrentController)
433 Finally:
434 IsLoaded = bLoaded
435 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
436 Exit Function
437 Catch:
438 GoTo Finally
439 End Function ' SFDocuments.SF_Base.IsLoaded
441 REM -----------------------------------------------------------------------------
442 Public Function Methods() As Variant
443 ''' Return the list of public methods of the Base class as an array
445 Methods = Array( _
454 )
456 End Function ' SFDocuments.SF_Base.Methods
458 REM -----------------------------------------------------------------------------
459 Public Function OpenFormDocument(Optional ByVal FormDocument As Variant _
460 , Optional ByVal DesignMode As Variant _
461 ) As Object
462 ''' Open the FormDocument given by its hierarchical name either in normal or in design mode
463 ''' If the form document is already open, the form document is made active without changing its mode
464 ''' Args:
465 ''' FormDocument: a valid form document name as a case-sensitive string
466 ''' When hierarchical, the hierarchy must be rendered with forward slashes ("/")
467 ''' DesignMode: when True the form document is opened in design mode (Default = False)
468 ''' Returns:
469 ''' A FormDocument instance or Nothing
470 ''' Exceptions:
471 ''' Form name is invalid
472 ''' Example:
475 Dim oOpen As Object ' Return value
476 Dim vFormNames As Variant ' Array of all document form names present in the document
477 Dim oNewForm As Object ' Output of loadComponent()
481 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
482 Set oOpen = Nothing
484 Check:
485 If IsMissing(DesignMode) Or IsEmpty(DesignMode) Then DesignMode = False
486 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
487 If Not _IsStillAlive() Then GoTo Finally
488 ' Build list of available FormDocuments recursively with _CollectFormDocuments
489 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
490 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
491 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames, True) Then GoTo Finally
492 If Not ScriptForge.SF_Utils._Validate(DesignMode, "DesignMode", ScriptForge.V_BOOLEAN) Then GoTo Finally
493 End If
495 Try:
496 With _Component.CurrentController
497 If Not .IsConnected Then .connect()
498 ' loadComponent activates the form when already loaded
499 Set oNewForm = .loadComponent(com.sun.star.sdb.application.DatabaseObject.FORM, FormDocument, DesignMode)
500 ' When user opened manually the form in design mode and closed it, the next execution in normal mode needs to be confirmed as below
501 With oNewForm.CurrentController
502 If .isFormDesignMode() <> DesignMode Then .setFormDesignMode(DesignMode)
503 End With
504 End With
506 Set oOpen = ScriptForge.SF_Services.CreateScriptService("SFDocuments.FormDocument", oNewForm)
508 ' Prevent desynchronization when using .last(), .next() etc immediately after component loading. Bug #156836
509 Wait 1
511 Finally:
512 Set OpenFormDocument = oOpen
513 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
514 Exit Function
515 Catch:
516 GoTo Finally
517 End Function ' SFDocuments.SF_Base.OpenFormDocument
519 REM -----------------------------------------------------------------------------
520 Public Function OpenQuery(Optional ByVal QueryName As Variant _
521 , Optional ByVal DesignMode As Variant _
522 ) As Object
523 ''' Open the query given by its name either in normal or in design mode
524 ''' If the query is already open, the query datasheet is made active without changing its mode
525 ''' If still open, the datasheet will be closed together with the actual Base document.
526 ''' Args:
527 ''' QueryName: a valid Query name as a case-sensitive string
528 ''' DesignMode: when True the query is opened in design mode (Default = False)
529 ''' Returns:
530 ''' A Datasheet class instance if the query could be opened and DesignMode = False, otherwise Nothing
531 ''' Exceptions:
532 ''' Query name is invalid
533 ''' Example:
536 Dim oOpen As Object ' Return value
537 Dim vQueries As Variant ' Array of query names
538 Dim oNewQuery As Object ' Output of loadComponent()
542 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
543 Set oOpen = Nothing
545 Check:
546 If IsMissing(DesignMode) Or IsEmpty(DesignMode) Then DesignMode = False
547 vQueries = GetDatabase().Queries ' Includes _IsStillAlive()
548 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
549 If Not ScriptForge.SF_Utils._Validate(QueryName, "QueryName", V_STRING, vQueries, True) Then GoTo Finally
550 If Not ScriptForge.SF_Utils._Validate(DesignMode, "DesignMode", ScriptForge.V_BOOLEAN) Then GoTo Finally
551 End If
553 Try:
554 With _Component.CurrentController
555 ' The connection may have been done previously by a user command. If not, do it now.
556 If Not .IsConnected Then .connect()
557 ' loadComponent activates the query component when already loaded
558 Set oNewQuery = .loadComponent(com.sun.star.sdb.application.DatabaseObject.QUERY, QueryName, DesignMode)
559 End With
560 ' When design mode, the method returns Nothing
561 If Not DesignMode Then Set oOpen = ScriptForge.SF_Services.CreateScriptService("SFDatabases.Datasheet", oNewQuery, [Me])
563 Finally:
564 Set OpenQuery = oOpen
565 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
566 Exit Function
567 Catch:
568 GoTo Finally
569 End Function ' SFDocuments.SF_Base.OpenQuery
571 REM -----------------------------------------------------------------------------
572 Public Function OpenTable(Optional ByVal TableName As Variant _
573 , Optional ByVal DesignMode As Variant _
574 ) As Object
575 ''' Open the table given by its name either in normal or in design mode
576 ''' If the table is already open, the table datasheet is made active without changing its mode
577 ''' If still open, the datasheet will be closed together with the actual Base document.
578 ''' Args:
579 ''' TableName: a valid table name as a case-sensitive string
580 ''' DesignMode: when True the table is opened in design mode (Default = False)
581 ''' Returns:
582 ''' A Datasheet class instance if the table could be opened or was already open, and DesignMode = False.
583 ''' Otherwise Nothing
584 ''' Exceptions:
585 ''' Table name is invalid
586 ''' Example:
589 Dim oOpen As Object ' Return value
590 Dim vTables As Variant ' Array of table names
591 Dim oNewTable As Object ' Output of loadComponent()
595 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
596 Set oOpen = Nothing
598 Check:
599 If IsMissing(DesignMode) Or IsEmpty(DesignMode) Then DesignMode = False
600 vTables = GetDatabase().Tables
601 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
602 If Not ScriptForge.SF_Utils._Validate(TableName, "TableName", V_STRING, vTables, True) Then GoTo Finally
603 If Not ScriptForge.SF_Utils._Validate(DesignMode, "DesignMode", ScriptForge.V_BOOLEAN) Then GoTo Finally
604 End If
606 Try:
607 With _Component.CurrentController
608 ' The connection may have been done previously by a user command. If not, do it now.
609 If Not .IsConnected Then .connect()
610 ' loadComponent activates the table component when already loaded
611 Set oNewTable = .loadComponent(com.sun.star.sdb.application.DatabaseObject.TABLE, TableName, DesignMode)
612 End With
613 ' When design mode, the method returns Nothing
614 If Not DesignMode Then Set oOpen = ScriptForge.SF_Services.CreateScriptService("SFDatabases.Datasheet", oNewTable, [Me])
616 Finally:
617 Set OpenTable = oOpen
618 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
619 Exit Function
620 Catch:
621 GoTo Finally
622 End Function ' SFDocuments.SF_Base.OpenTable
624 REM -----------------------------------------------------------------------------
625 Public Function PrintOut(Optional ByVal FormDocument As Variant _
626 , Optional ByVal Pages As Variant _
627 , Optional ByVal Copies As Variant _
628 ) As Boolean
629 ''' Send the content of the given form document to the printer.
630 ''' The printer might be defined previously by default, by the user or by the SetPrinter() method
631 ''' The given form document must be open. It is activated by the method.
632 ''' Args:
633 ''' FormDocument: a valid document form name as a case-sensitive string
634 ''' Pages: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages
635 ''' Copies: the number of copies
636 ''' Exceptions:
637 ''' FORMDEADERROR The form is not open
638 ''' Returns:
639 ''' True when successful
640 ''' Examples:
642 ''' DEPRECATED - Use preferably the PrintOut() method of the FormDocument service
644 Dim bPrint As Boolean ' Return value
645 Dim vFormNames As Variant ' Array of all document form names present in the document
646 Dim oFormDocument As Object ' com.sun.star.comp.sdb.Content
651 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
652 bPrint = False
654 Check:
655 If IsMissing(Pages) Or IsEmpty(Pages) Then Pages = ""
656 If IsMissing(Copies) Or IsEmpty(Copies) Then Copies = 1
658 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
659 If Not _IsStillAlive() Then GoTo Finally
660 ' Build list of available FormDocuments recursively with _CollectFormDocuments
661 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
662 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
663 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames, True) Then GoTo Finally
665 If Not ScriptForge.SF_Utils._Validate(Copies, "Copies", ScriptForge.V_NUMERIC) Then GoTo Finally
666 End If
667 If Not IsLoaded(FormDocument) Then GoTo CatchClosed
669 Try:
670 Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
671 bPrint = [_Super].PrintOut(Pages, Copies, oFormDocument.Component)
673 Finally:
674 PrintOut = bPrint
675 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
676 Exit Function
677 Catch:
678 GoTo Finally
679 CatchClosed:
680 ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
681 End Function ' SFDocuments.SF_Base.PrintOut
683 REM -----------------------------------------------------------------------------
684 Public Function Properties() As Variant
685 ''' Return the list or properties of the Base class as an array
687 Properties = Array( _
699 )
701 End Function ' SFDocuments.SF_Base.Properties
703 REM -----------------------------------------------------------------------------
704 Public Function SetPrinter(Optional ByVal FormDocument As Variant _
705 , Optional ByVal Printer As Variant _
706 , Optional ByVal Orientation As Variant _
707 , Optional ByVal PaperFormat As Variant _
708 ) As Boolean
709 ''' Define the printer options for a form document. The form document must be open.
710 ''' Args:
711 ''' FormDocument: a valid document form name as a case-sensitive string
712 ''' Printer: the name of the printer queue where to print to
713 ''' When absent or space, the default printer is set
714 ''' Orientation: either "PORTRAIT" or "LANDSCAPE". Left unchanged when absent
715 ''' PaperFormat: one of next values
716 ''' "A3", "A4", "A5", "B4", "B5", "LETTER", "LEGAL", "TABLOID"
717 ''' Left unchanged when absent
718 ''' Returns:
719 ''' True when successful
720 ''' Examples:
722 ''' DEPRECATED - Use preferably the SetPrinter() method of the FormDocument service
724 Dim bPrinter As Boolean ' Return value
725 Dim vFormDocuments As Variant ' Array of form documents
726 Dim oFormDocument As Object ' com.sun.star.comp.sdb.Content
729 Const cstSubArgs = "FormDocument, [Printer=""""], [Orientation=""PORTRAIT""|""LANDSCAPE""]" _
730 & ", [PaperFormat=""A3""|""A4""|""A5""|""B4""|""B5""|""LETTER""|""LEGAL""|""TABLOID"""
732 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
733 bPrinter = False
735 Check:
736 If IsMissing(Printer) Or IsEmpty(Printer) Then Printer = ""
737 If IsMissing(Orientation) Or IsEmpty(Orientation) Then Orientation = ""
738 If IsMissing(PaperFormat) Or IsEmpty(PaperFormat) Then PaperFormat = ""
740 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
741 If Not _IsStillAlive() Then GoTo Finally
742 ' Build list of available FormDocuments recursively with _CollectFormDocuments
743 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
744 vFormDocuments = Split(_CollectFormDocuments(_FormDocuments), cstToken)
745 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormDocuments, True) Then GoTo Finally
746 End If
747 If Not IsLoaded(FormDocument) Then GoTo CatchClosed
749 Try:
750 Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
751 bPrinter = [_Super].SetPrinter(Printer, Orientation, PaperFormat, oFormDocument.Component)
753 Finally:
754 SetPrinter = bPrinter
755 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
756 Exit Function
757 Catch:
758 GoTo Finally
759 CatchClosed:
760 ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
761 End Function ' SFDocuments.SF_Base.SetPrinter
763 REM -----------------------------------------------------------------------------
764 Public Function SetProperty(Optional ByVal PropertyName As Variant _
765 , Optional ByRef Value As Variant _
766 ) As Boolean
767 ''' Set a new value to the given property
768 ''' Args:
769 ''' PropertyName: the name of the property as a string
770 ''' Value: its new value
771 ''' Exceptions
772 ''' ARGUMENTERROR The property does not exist
777 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
778 SetProperty = False
780 Check:
781 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
782 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
783 End If
785 Try:
786 Select Case UCase(PropertyName)
787 Case Else
788 End Select
790 Finally:
791 SF_Utils._ExitFunction(cstThisSub)
792 Exit Function
793 Catch:
794 GoTo Finally
795 End Function ' SFDocuments.SF_Base.SetProperty
797 REM ======================================================= SUPERCLASS PROPERTIES
799 REM -----------------------------------------------------------------------------
800 'Property Get CustomProperties() As Variant
804 REM -----------------------------------------------------------------------------
805 'Property Let CustomProperties(Optional ByVal pvCustomProperties As Variant)
806 ' [_Super].CustomProperties = pvCustomProperties
809 REM -----------------------------------------------------------------------------
810 'Property Get Description() As Variant
814 REM -----------------------------------------------------------------------------
815 'Property Let Description(Optional ByVal pvDescription As Variant)
816 ' [_Super].Description = pvDescription
819 REM -----------------------------------------------------------------------------
820 'Property Get DocumentProperties() As Variant
824 REM -----------------------------------------------------------------------------
825 Property Get DocumentType() As String
827 End Property ' SFDocuments.SF_Base.DocumentType
829 REM -----------------------------------------------------------------------------
830 Property Get FileSystem() As String
832 End Property ' SFDocuments.SF_Base.FileSystem
834 REM -----------------------------------------------------------------------------
835 Property Get IsAlive() As Boolean
837 End Property ' SFDocuments.SF_Base.IsAlive
839 REM -----------------------------------------------------------------------------
840 Property Get IsBase() As Boolean
842 End Property ' SFDocuments.SF_Base.IsBase
844 REM -----------------------------------------------------------------------------
845 Property Get IsCalc() As Boolean
847 End Property ' SFDocuments.SF_Base.IsCalc
849 REM -----------------------------------------------------------------------------
850 Property Get IsDraw() As Boolean
852 End Property ' SFDocuments.SF_Base.IsDraw
854 REM -----------------------------------------------------------------------------
855 Property Get IsFormDocument() As Boolean
857 End Property ' SFDocuments.SF_Writer.IsFormDocument
859 REM -----------------------------------------------------------------------------
860 Property Get IsImpress() As Boolean
862 End Property ' SFDocuments.SF_Base.IsImpress
864 REM -----------------------------------------------------------------------------
865 Property Get IsMath() As Boolean
867 End Property ' SFDocuments.SF_Base.IsMath
869 REM -----------------------------------------------------------------------------
870 Property Get IsWriter() As Boolean
872 End Property ' SFDocuments.SF_Base.IsWriter
874 REM -----------------------------------------------------------------------------
875 'Property Get Keywords() As Variant
879 REM -----------------------------------------------------------------------------
880 'Property Let Keywords(Optional ByVal pvKeywords As Variant)
881 ' [_Super].Keywords = pvKeywords
884 REM -----------------------------------------------------------------------------
885 'Property Get Readonly() As Variant
889 REM -----------------------------------------------------------------------------
890 'Property Get Subject() As Variant
894 REM -----------------------------------------------------------------------------
895 'Property Let Subject(Optional ByVal pvSubject As Variant)
896 ' [_Super].Subject = pvSubject
899 REM -----------------------------------------------------------------------------
900 'Property Get Title() As Variant
904 REM -----------------------------------------------------------------------------
905 'Property Let Title(Optional ByVal pvTitle As Variant)
906 ' [_Super].Title = pvTitle
909 REM -----------------------------------------------------------------------------
910 Property Get XComponent() As Variant
912 End Property ' SFDocuments.SF_Base.XComponent
914 REM ========================================================== SUPERCLASS METHODS
916 REM -----------------------------------------------------------------------------
917 Public Function Activate() As Boolean
918 Activate = [_Super].Activate()
919 End Function ' SFDocuments.SF_Base.Activate
921 REM -----------------------------------------------------------------------------
922 Public Function ContextMenus(Optional ByVal ContextMenuName As Variant _
923 , Optional ByVal SubmenuChar As Variant _
924 ) As Variant
925 ContextMenus = [_Super].ContextMenus(ContextMenuName, SubmenuChar)
926 End Function ' SFDocuments.SF_Base.ContextMenus
928 REM -----------------------------------------------------------------------------
929 Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
930 , Optional ByVal Before As Variant _
931 , Optional ByVal SubmenuChar As Variant _
932 ) As Object
933 Set CreateMenu = [_Super].CreateMenu(MenuHeader, Before, SubmenuChar)
934 End Function ' SFDocuments.SF_Base.CreateMenu
936 REM -----------------------------------------------------------------------------
937 Public Function RemoveMenu(Optional ByVal MenuHeader As Variant) As Boolean
938 RemoveMenu = [_Super].RemoveMenu(MenuHeader)
939 End Function ' SFDocuments.SF_Base.RemoveMenu
941 REM -----------------------------------------------------------------------------
942 Public Sub RunCommand(Optional ByVal Command As Variant _
943 , ParamArray Args As Variant _
944 )
945 [_Super].RunCommand(Command, Args)
946 End Sub ' SFDocuments.SF_Base.RunCommand
948 REM -----------------------------------------------------------------------------
949 Public Function Save() As Boolean
950 Save = [_Super].Save()
951 End Function ' SFDocuments.SF_Base.Save
953 REM -----------------------------------------------------------------------------
954 Public Function SaveAs(Optional ByVal FileName As Variant _
955 , Optional ByVal Overwrite As Variant _
956 , Optional ByVal Password As Variant _
957 , Optional ByVal FilterName As Variant _
958 , Optional ByVal FilterOptions As Variant _
959 ) As Boolean
960 SaveAs = [_Super].SaveAs(FileName, Overwrite, Password, FilterName, FilterOptions)
961 End Function ' SFDocuments.SF_Base.SaveAs
963 REM -----------------------------------------------------------------------------
964 Public Function SaveCopyAs(Optional ByVal FileName As Variant _
965 , Optional ByVal Overwrite As Variant _
966 , Optional ByVal Password As Variant _
967 , Optional ByVal FilterName As Variant _
968 , Optional ByVal FilterOptions As Variant _
969 ) As Boolean
970 SaveCopyAs = [_Super].SaveCopyAs(FileName, Overwrite, Password, FilterName, FilterOptions)
971 End Function ' SFDocuments.SF_Base.SaveCopyAs
973 REM -----------------------------------------------------------------------------
974 Public Function Toolbars(Optional ByVal ToolbarName As Variant) As Variant
975 Toolbars = [_Super].Toolbars(ToolbarName)
976 End Function ' SFDocuments.SF_Base.Toolbars
978 REM =========================================================== PRIVATE FUNCTIONS
980 REM -----------------------------------------------------------------------------
981 Private Function _CollectFormDocuments(ByRef poContainer As Object) As String
982 ''' Returns a token-separated string of all hierarchical formdocument names
983 ''' depending on the formdocuments container in argument
984 ''' The function traverses recursively the whole tree below the container
985 ''' The initial call starts from the container _Component.getFormDocuments
986 ''' The list contains closed and open forms
988 Dim sCollectNames As String ' Return value
989 Dim oSubItem As Object ' com.sun.star.container.XNameAccess (folder) or com.sun.star.ucb.XContent (form)
990 Dim i As Long
992 ' Identifies forms. Folders have a zero-length content type
994 On Local Error GoTo Finally
996 Try:
997 sCollectNames = ""
998 With poContainer
1000 Set oSubItem = .getByIndex(i)
1001 If oSubItem.ContentType = cstFormType Then ' Add the form to the list
1003 Else
1005 End If
1006 Next i
1007 End With
1009 Finally:
1012 Else
1013 _CollectFormDocuments = ""
1014 End If
1015 Exit Function
1016 End Function ' SFDocuments.SF_Base._CollectFormDocuments
1018 REM -----------------------------------------------------------------------------
1019 Private Function _FileIdent() As String
1020 ''' Returns a file identification from the information that is currently available
1021 ''' Useful e.g. for display in error messages
1023 _FileIdent = [_Super]._FileIdent()
1025 End Function ' SFDocuments.SF_Base._FileIdent
1027 REM -----------------------------------------------------------------------------
1028 Private Function _FindByPersistentName(ByRef poContainer As Object _
1029 , psPersistent As String _
1030 ) As Object
1031 ''' The FormDocuments property of a Base component has strangely
1032 ''' a getByHierarchical() method but no access to the same com.sun.star.comp.sdb.Content
1033 ''' object via its persistent/ODF name
1034 ''' This method returns the object having the given persistent name
1035 ''' The function traverses recursively the whole tree below the container until found
1036 ''' The initial call starts from the container _Component.getFormDocuments
1037 ''' The list contains closed and open forms
1038 ''' Args:
1039 ''' poContainer: the actual top of the free, initially _FormDocuments
1041 ''' Returns:
1042 ''' A com.sun.star.comp.sdb.Content object (object found, the process stops)
1043 ''' or Nothing (object not found, the process continues)
1045 Dim oMainForm As Object ' Return value
1046 Dim oSubItem As Object ' com.sun.star.container.XNameAccess (folder) or com.sun.star.ucb.XContent (form)
1047 Dim i As Long
1049 ' Identifies forms. Folders have a zero-length content type
1051 On Local Error GoTo Finally
1053 Try:
1054 Set oMainForm = Nothing
1055 With poContainer
1057 Set oSubItem = .getByIndex(i)
1058 If oSubItem.ContentType = cstFormType Then ' Examine its persistent name
1059 If oSubItem.PersistentName = psPersistent Then
1060 Set oMainForm = oSubItem
1061 Exit For
1062 End If
1063 Else
1064 Set oMainForm = _FindByPersistentName(oSubItem, psPersistent)
1065 End If
1066 Next i
1067 End With
1069 Finally:
1070 Set _FindByPersistentName = oMainForm
1071 Exit Function
1072 End Function ' SFDocuments.SF_Base.FindByPersistentName
1074 REM -----------------------------------------------------------------------------
1075 Private Function _IsStillAlive(Optional ByVal pbForUpdate As Boolean _
1076 , Optional ByVal pbError As Boolean _
1077 ) As Boolean
1078 ''' Returns True if the document has not been closed manually or incidentally since the last use
1079 ''' If dead the actual instance is disposed. The execution is cancelled when pbError = True (default)
1080 ''' Args:
1081 ''' pbForUpdate: if True (default = False), check additionally if document is open for editing
1082 ''' pbError: if True (default), raise a fatal error
1084 Dim bAlive As Boolean ' Return value
1086 If IsMissing(pbForUpdate) Then pbForUpdate = False
1087 If IsMissing(pbError) Then pbError = True
1089 Try:
1090 bAlive = [_Super]._IsStillAlive(pbForUpdate, pbError)
1092 Finally:
1093 _IsStillAlive = bAlive
1094 Exit Function
1095 End Function ' SFDocuments.SF_Base._IsStillAlive
1097 REM -----------------------------------------------------------------------------
1098 Private Function _PropertyGet(Optional ByVal psProperty As String _
1099 , Optional ByVal pvArg As Variant _
1100 ) As Variant
1101 ''' Return the value of the named property
1102 ''' Args:
1103 ''' psProperty: the name of the property
1105 Dim oProperties As Object ' Document or Custom properties
1106 Dim vLastCell As Variant ' Coordinates of last used cell in a sheet
1107 Dim oSelect As Object ' Current selection
1108 Dim vRanges As Variant ' List of selected ranges
1109 Dim i As Long
1110 Dim cstThisSub As String
1111 Const cstSubArgs = ""
1113 _PropertyGet = False
1116 ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
1117 If Not _IsStillAlive() Then GoTo Finally
1119 Select Case psProperty
1120 Case Else
1121 _PropertyGet = Null
1122 End Select
1124 Finally:
1125 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
1126 Exit Function
1127 End Function ' SFDocuments.SF_Base._PropertyGet
1129 REM -----------------------------------------------------------------------------
1130 Private Function _Repr() As String
1131 ''' Convert the SF_Base instance to a readable string, typically for debugging purposes (DebugPrint ...)
1132 ''' Args:
1133 ''' Return:
1138 End Function ' SFDocuments.SF_Base._Repr
1140 REM ============================================ END OF SFDOCUMENTS.SF_BASE
1141 </script:module>