| blob | b7662b7341cdd7a969c988fb2a466efbf48e9495 |
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) 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) 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) 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) 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) 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 desynchonization 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) 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) 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) 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( _
697 )
699 End Function ' SFDocuments.SF_Base.Properties
701 REM -----------------------------------------------------------------------------
702 Public Function SetPrinter(Optional ByVal FormDocument As Variant _
703 , Optional ByVal Printer As Variant _
704 , Optional ByVal Orientation As Variant _
705 , Optional ByVal PaperFormat As Variant _
706 ) As Boolean
707 ''' Define the printer options for a form document. The form document must be open.
708 ''' Args:
709 ''' FormDocument: a valid document form name as a case-sensitive string
710 ''' Printer: the name of the printer queue where to print to
711 ''' When absent or space, the default printer is set
712 ''' Orientation: either "PORTRAIT" or "LANDSCAPE". Left unchanged when absent
713 ''' PaperFormat: one of next values
714 ''' "A3", "A4", "A5", "B4", "B5", "LETTER", "LEGAL", "TABLOID"
715 ''' Left unchanged when absent
716 ''' Returns:
717 ''' True when successful
718 ''' Examples:
720 ''' DEPRECATED - Use preferably the SetPrinter() method of the FormDocument service
722 Dim bPrinter As Boolean ' Return value
723 Dim vFormDocuments As Variant ' Array of form documents
724 Dim oFormDocument As Object ' com.sun.star.comp.sdb.Content
727 Const cstSubArgs = "FormDocument, [Printer=""""], [Orientation=""PORTRAIT""|""LANDSCAPE""]" _
728 & ", [PaperFormat=""A3""|""A4""|""A5""|""B4""|""B5""|""LETTER""|""LEGAL""|""TABLOID"""
730 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
731 bPrinter = False
733 Check:
734 If IsMissing(Printer) Or IsEmpty(Printer) Then Printer = ""
735 If IsMissing(Orientation) Or IsEmpty(Orientation) Then Orientation = ""
736 If IsMissing(PaperFormat) Or IsEmpty(PaperFormat) Then PaperFormat = ""
738 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
739 If Not _IsStillAlive() Then GoTo Finally
740 ' Build list of available FormDocuments recursively with _CollectFormDocuments
741 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
742 vFormDocuments = Split(_CollectFormDocuments(_FormDocuments), cstToken)
743 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormDocuments) Then GoTo Finally
744 End If
745 If Not IsLoaded(FormDocument) Then GoTo CatchClosed
747 Try:
748 Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
749 bPrinter = [_Super].SetPrinter(Printer, Orientation, PaperFormat, oFormDocument.Component)
751 Finally:
752 SetPrinter = bPrinter
753 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
754 Exit Function
755 Catch:
756 GoTo Finally
757 CatchClosed:
758 ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
759 End Function ' SFDocuments.SF_Base.SetPrinter
761 REM -----------------------------------------------------------------------------
762 Public Function SetProperty(Optional ByVal PropertyName As Variant _
763 , Optional ByRef Value As Variant _
764 ) As Boolean
765 ''' Set a new value to the given property
766 ''' Args:
767 ''' PropertyName: the name of the property as a string
768 ''' Value: its new value
769 ''' Exceptions
770 ''' ARGUMENTERROR The property does not exist
775 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
776 SetProperty = False
778 Check:
779 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
780 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
781 End If
783 Try:
784 Select Case UCase(PropertyName)
785 Case Else
786 End Select
788 Finally:
789 SF_Utils._ExitFunction(cstThisSub)
790 Exit Function
791 Catch:
792 GoTo Finally
793 End Function ' SFDocuments.SF_Base.SetProperty
795 REM ======================================================= SUPERCLASS PROPERTIES
797 REM -----------------------------------------------------------------------------
798 'Property Get CustomProperties() As Variant
802 REM -----------------------------------------------------------------------------
803 'Property Let CustomProperties(Optional ByVal pvCustomProperties As Variant)
804 ' [_Super].CustomProperties = pvCustomProperties
807 REM -----------------------------------------------------------------------------
808 'Property Get Description() As Variant
812 REM -----------------------------------------------------------------------------
813 'Property Let Description(Optional ByVal pvDescription As Variant)
814 ' [_Super].Description = pvDescription
817 REM -----------------------------------------------------------------------------
818 'Property Get DocumentProperties() As Variant
822 REM -----------------------------------------------------------------------------
823 Property Get DocumentType() As String
825 End Property ' SFDocuments.SF_Base.DocumentType
827 REM -----------------------------------------------------------------------------
828 Property Get IsBase() As Boolean
830 End Property ' SFDocuments.SF_Base.IsBase
832 REM -----------------------------------------------------------------------------
833 Property Get IsCalc() As Boolean
835 End Property ' SFDocuments.SF_Base.IsCalc
837 REM -----------------------------------------------------------------------------
838 Property Get IsDraw() As Boolean
840 End Property ' SFDocuments.SF_Base.IsDraw
842 REM -----------------------------------------------------------------------------
843 Property Get IsFormDocument() As Boolean
845 End Property ' SFDocuments.SF_Writer.IsFormDocument
847 REM -----------------------------------------------------------------------------
848 Property Get IsImpress() As Boolean
850 End Property ' SFDocuments.SF_Base.IsImpress
852 REM -----------------------------------------------------------------------------
853 Property Get IsMath() As Boolean
855 End Property ' SFDocuments.SF_Base.IsMath
857 REM -----------------------------------------------------------------------------
858 Property Get IsWriter() As Boolean
860 End Property ' SFDocuments.SF_Base.IsWriter
862 REM -----------------------------------------------------------------------------
863 'Property Get Keywords() As Variant
867 REM -----------------------------------------------------------------------------
868 'Property Let Keywords(Optional ByVal pvKeywords As Variant)
869 ' [_Super].Keywords = pvKeywords
872 REM -----------------------------------------------------------------------------
873 'Property Get Readonly() As Variant
877 REM -----------------------------------------------------------------------------
878 'Property Get Subject() As Variant
882 REM -----------------------------------------------------------------------------
883 'Property Let Subject(Optional ByVal pvSubject As Variant)
884 ' [_Super].Subject = pvSubject
887 REM -----------------------------------------------------------------------------
888 'Property Get Title() As Variant
892 REM -----------------------------------------------------------------------------
893 'Property Let Title(Optional ByVal pvTitle As Variant)
894 ' [_Super].Title = pvTitle
897 REM -----------------------------------------------------------------------------
898 Property Get XComponent() As Variant
900 End Property ' SFDocuments.SF_Base.XComponent
902 REM ========================================================== SUPERCLASS METHODS
904 REM -----------------------------------------------------------------------------
905 Public Function Activate() As Boolean
906 Activate = [_Super].Activate()
907 End Function ' SFDocuments.SF_Base.Activate
909 REM -----------------------------------------------------------------------------
910 Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
911 , Optional ByVal Before As Variant _
912 , Optional ByVal SubmenuChar As Variant _
913 ) As Object
914 Set CreateMenu = [_Super].CreateMenu(MenuHeader, Before, SubmenuChar)
915 End Function ' SFDocuments.SF_Base.CreateMenu
917 REM -----------------------------------------------------------------------------
918 Public Function RemoveMenu(Optional ByVal MenuHeader As Variant) As Boolean
919 RemoveMenu = [_Super].RemoveMenu(MenuHeader)
920 End Function ' SFDocuments.SF_Base.RemoveMenu
922 REM -----------------------------------------------------------------------------
923 Public Sub RunCommand(Optional ByVal Command As Variant _
924 , ParamArray Args As Variant _
925 )
926 [_Super].RunCommand(Command, Args)
927 End Sub ' SFDocuments.SF_Base.RunCommand
929 REM -----------------------------------------------------------------------------
930 Public Function Save() As Boolean
931 Save = [_Super].Save()
932 End Function ' SFDocuments.SF_Base.Save
934 REM -----------------------------------------------------------------------------
935 Public Function SaveAs(Optional ByVal FileName As Variant _
936 , Optional ByVal Overwrite As Variant _
937 , Optional ByVal Password As Variant _
938 , Optional ByVal FilterName As Variant _
939 , Optional ByVal FilterOptions As Variant _
940 ) As Boolean
941 SaveAs = [_Super].SaveAs(FileName, Overwrite, Password, FilterName, FilterOptions)
942 End Function ' SFDocuments.SF_Base.SaveAs
944 REM -----------------------------------------------------------------------------
945 Public Function SaveCopyAs(Optional ByVal FileName As Variant _
946 , Optional ByVal Overwrite As Variant _
947 , Optional ByVal Password As Variant _
948 , Optional ByVal FilterName As Variant _
949 , Optional ByVal FilterOptions As Variant _
950 ) As Boolean
951 SaveCopyAs = [_Super].SaveCopyAs(FileName, Overwrite, Password, FilterName, FilterOptions)
952 End Function ' SFDocuments.SF_Base.SaveCopyAs
954 REM -----------------------------------------------------------------------------
955 Public Function Toolbars(Optional ByVal ToolbarName As Variant) As Variant
956 Toolbars = [_Super].Toolbars(ToolbarName)
957 End Function ' SFDocuments.SF_Base.Toolbars
959 REM =========================================================== PRIVATE FUNCTIONS
961 REM -----------------------------------------------------------------------------
962 Private Function _CollectFormDocuments(ByRef poContainer As Object) As String
963 ''' Returns a token-separated string of all hierarchical formdocument names
964 ''' depending on the formdocuments container in argument
965 ''' The function traverses recursively the whole tree below the container
966 ''' The initial call starts from the container _Component.getFormDocuments
967 ''' The list contains closed and open forms
969 Dim sCollectNames As String ' Return value
970 Dim oSubItem As Object ' com.sun.star.container.XNameAccess (folder) or com.sun.star.ucb.XContent (form)
971 Dim i As Long
973 ' Identifies forms. Folders have a zero-length content type
975 On Local Error GoTo Finally
977 Try:
978 sCollectNames = ""
979 With poContainer
981 Set oSubItem = .getByIndex(i)
982 If oSubItem.ContentType = cstFormType Then ' Add the form to the list
984 Else
986 End If
987 Next i
988 End With
990 Finally:
993 Else
994 _CollectFormDocuments = ""
995 End If
996 Exit Function
997 End Function ' SFDocuments.SF_Base._CollectFormDocuments
999 REM -----------------------------------------------------------------------------
1000 Private Function _FileIdent() As String
1001 ''' Returns a file identification from the information that is currently available
1002 ''' Useful e.g. for display in error messages
1004 _FileIdent = [_Super]._FileIdent()
1006 End Function ' SFDocuments.SF_Base._FileIdent
1008 REM -----------------------------------------------------------------------------
1009 Private Function _FindByPersistentName(ByRef poContainer As Object _
1010 , psPersistent As String _
1011 ) As Object
1012 ''' The FormDocuments property of a Base component has strangely
1013 ''' a getByHierarchical() method but no access to the same com.sun.star.comp.sdb.Content
1014 ''' object via its persistent/ODF name
1015 ''' This method returns the object having the given persistent name
1016 ''' The function traverses recursively the whole tree below the container until found
1017 ''' The initial call starts from the container _Component.getFormDocuments
1018 ''' The list contains closed and open forms
1019 ''' Args:
1020 ''' poContainer: the actual top of the free, initially _FormDocuments
1022 ''' Returns:
1023 ''' A com.sun.star.comp.sdb.Content object (object found, the process stops)
1024 ''' or Nothing (object not found, the process continues)
1026 Dim oMainForm As Object ' Return value
1027 Dim oSubItem As Object ' com.sun.star.container.XNameAccess (folder) or com.sun.star.ucb.XContent (form)
1028 Dim i As Long
1030 ' Identifies forms. Folders have a zero-length content type
1032 On Local Error GoTo Finally
1034 Try:
1035 Set oMainForm = Nothing
1036 With poContainer
1038 Set oSubItem = .getByIndex(i)
1039 If oSubItem.ContentType = cstFormType Then ' Examine its persistent name
1040 If oSubItem.PersistentName = psPersistent Then
1041 Set oMainForm = oSubItem
1042 Exit For
1043 End If
1044 Else
1045 Set oMainForm = _FindByPersistentName(oSubItem, psPersistent)
1046 End If
1047 Next i
1048 End With
1050 Finally:
1051 Set _FindByPersistentName = oMainForm
1052 Exit Function
1053 End Function ' SFDocuments.SF_Base.FindByPersistentName
1055 REM -----------------------------------------------------------------------------
1056 Private Function _IsStillAlive(Optional ByVal pbForUpdate As Boolean _
1057 , Optional ByVal pbError As Boolean _
1058 ) As Boolean
1059 ''' Returns True if the document has not been closed manually or incidentally since the last use
1060 ''' If dead the actual instance is disposed. The execution is cancelled when pbError = True (default)
1061 ''' Args:
1062 ''' pbForUpdate: if True (default = False), check additionally if document is open for editing
1063 ''' pbError: if True (default), raise a fatal error
1065 Dim bAlive As Boolean ' Return value
1067 If IsMissing(pbForUpdate) Then pbForUpdate = False
1068 If IsMissing(pbError) Then pbError = True
1070 Try:
1071 bAlive = [_Super]._IsStillAlive(pbForUpdate, pbError)
1073 Finally:
1074 _IsStillAlive = bAlive
1075 Exit Function
1076 End Function ' SFDocuments.SF_Base._IsStillAlive
1078 REM -----------------------------------------------------------------------------
1079 Private Function _PropertyGet(Optional ByVal psProperty As String _
1080 , Optional ByVal pvArg As Variant _
1081 ) As Variant
1082 ''' Return the value of the named property
1083 ''' Args:
1084 ''' psProperty: the name of the property
1086 Dim oProperties As Object ' Document or Custom properties
1087 Dim vLastCell As Variant ' Coordinates of last used cell in a sheet
1088 Dim oSelect As Object ' Current selection
1089 Dim vRanges As Variant ' List of selected ranges
1090 Dim i As Long
1091 Dim cstThisSub As String
1092 Const cstSubArgs = ""
1094 _PropertyGet = False
1097 ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
1098 If Not _IsStillAlive() Then GoTo Finally
1100 Select Case psProperty
1101 Case Else
1102 _PropertyGet = Null
1103 End Select
1105 Finally:
1106 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
1107 Exit Function
1108 End Function ' SFDocuments.SF_Base._PropertyGet
1110 REM -----------------------------------------------------------------------------
1111 Private Function _Repr() As String
1112 ''' Convert the SF_Base instance to a readable string, typically for debugging purposes (DebugPrint ...)
1113 ''' Args:
1114 ''' Return:
1119 End Function ' SFDocuments.SF_Base._Repr
1121 REM ============================================ END OF SFDOCUMENTS.SF_BASE
1122 </script:module>