| blob | eb39c86e851fab712ddb7015f0633ef044fa1a8e |
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:
149 Dim bClose As Boolean ' Return value
150 Dim oMainForm As Object ' com.sun.star.comp.sdb.Content
151 Dim vFormNames As Variant ' Array of all document form names present in the document
156 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
157 bClose = False
159 Check:
160 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
161 If Not _IsStillAlive() Then GoTo Finally
162 ' Build list of available FormDocuments recursively with _CollectFormDocuments
163 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
164 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
165 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames) Then GoTo Finally
166 End If
167 If Not IsLoaded(FormDocument) Then GoTo Finally
169 Try:
170 Set oMainForm = _FormDocuments.getByHierarchicalName(FormDocument)
171 bClose = oMainForm.close()
173 Finally:
174 CloseFormDocument = bClose
175 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
176 Exit Function
177 Catch:
178 GoTo Finally
179 End Function ' SFDocuments.SF_Base.CloseFormDocument
181 REM -----------------------------------------------------------------------------
182 Public Function FormDocuments() As Variant
183 ''' Return the list of the FormDocuments contained in the Base document
184 ''' Args:
185 ''' Returns:
186 ''' A zero-base array of strings
187 ''' Each entry is the full path name of a form document. The path separator is the slash ("/")
188 ''' Example:
189 ''' Dim myForm As Object, myList As Variant
190 ''' myList = oDoc.FormDocuments()
192 Dim vFormNames As Variant ' Array of all form names present in the document
194 Const cstSubArgs = ""
196 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
198 Check:
199 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
200 If Not _IsStillAlive() Then GoTo Finally
201 End If
203 Try:
204 ' Build list of available FormDocuments recursively with _CollectFormDocuments
205 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
206 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
208 Finally:
209 FormDocuments = vFormNames
210 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
211 Exit Function
212 Catch:
213 GoTo Finally
214 End Function ' SFDocuments.SF_Base.FormDocuments
216 REM -----------------------------------------------------------------------------
217 Public Function Forms(Optional ByVal FormDocument As Variant _
218 , Optional ByVal Form As Variant _
219 ) As Variant
220 ''' Return either
221 ''' - the list of the Forms contained in the form document
222 ''' - a SFDocuments.Form object based on its name or its index
223 ''' Args:
224 ''' FormDocument: a valid document form name as a case-sensitive string
225 ''' Form: a form stored in the Base document given by its name or its index
226 ''' When absent, the list of available forms is returned
228 ''' Returns:
229 ''' A zero-based array of strings if Form is absent
230 ''' An instance of the SF_Form class if Form exists
231 ''' Exceptions:
232 ''' FORMDEADERROR The form is not open
233 ''' BASEFORMNOTFOUNDERROR FormDocument OK but Form not found
234 ''' Example:
235 ''' Dim myForm As Object, myList As Variant
239 Dim oForm As Object ' The new Form class instance
240 Dim oFormDocument As Object ' com.sun.star.comp.sdb.Content
241 Dim oXForm As Object ' com.sun.star.form.XForm
242 Dim vFormDocuments As Variant ' Array of form documents
243 Dim vFormNames As Variant ' Array of form names
244 Dim oForms As Object ' Forms collection
250 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
252 Check:
253 If IsMissing(Form) Or IsEmpty(Form) Then Form = ""
254 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
255 If Not _IsStillAlive() Then GoTo Finally
256 ' Build list of available FormDocuments recursively with _CollectFormDocuments
257 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
258 vFormDocuments = Split(_CollectFormDocuments(_FormDocuments), cstToken)
259 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormDocuments) Then GoTo Finally
260 If Not ScriptForge.SF_Utils._Validate(Form, "Form", Array(V_STRING, ScriptForge.V_NUMERIC)) Then GoTo Finally
261 End If
262 If Not IsLoaded(FormDocument) Then GoTo CatchClosed
264 Try:
265 ' Start from the form document and go down to forms
266 Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
267 Set oForms = oFormDocument.Component.DrawPages(cstDrawPage).Forms
268 vFormNames = oForms.getElementNames()
271 Forms = vFormNames
272 Else
273 If VarType(Form) = V_STRING Then ' Find the form by name
274 If Not ScriptForge.SF_Utils._Validate(Form, "Form", V_STRING, vFormNames) Then GoTo Finally
275 Set oXForm = oForms.getByName(Form)
276 Else ' Find the form by index
278 Set oXForm = oForms.getByIndex(Form)
279 End If
280 ' Create the new Form class instance
281 Set oForm = New SF_Form
282 With oForm
283 ._Name = oXForm.Name
284 Set .[Me] = oForm
285 Set .[_Parent] = [Me]
286 Set ._Component = _Component
287 ._FormDocumentName = FormDocument
288 Set ._FormDocument = oFormDocument
289 ._FormType = ISBASEFORM
290 Set ._Form = oXForm
291 ._Initialize()
292 End With
293 Set Forms = oForm
294 End If
296 Finally:
297 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
298 Exit Function
299 Catch:
300 GoTo Finally
301 CatchClosed:
302 ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
303 CatchNotFound:
304 ScriptForge.SF_Exception.RaiseFatal(BASEFORMNOTFOUNDERROR, Form, FormDocument, _FileIdent())
305 End Function ' SFDocuments.SF_Base.Forms
307 REM -----------------------------------------------------------------------------
308 Public Function GetDatabase(Optional ByVal User As Variant _
309 , Optional ByVal Password As Variant _
310 ) As Object
311 ''' Returns a Database instance (service = SFDatabases.Database) giving access
312 ''' to the execution of SQL commands on the database defined and/or stored in
313 ''' the actual Base document
314 ''' Args:
316 ''' Returns:
317 ''' A SFDatabases.Database instance or Nothing
318 ''' Example:
319 ''' Dim myDb As Object
320 ''' Set myDb = oDoc.GetDatabase()
323 Const cstSubArgs = "[User=""""], [Password=""""]"
325 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
326 Set GetDatabase = Nothing
328 Check:
329 If IsMissing(User) Or IsEmpty(User) Then User = ""
330 If IsMissing(Password) Or IsEmpty(Password) Then Password = ""
331 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
332 If Not _IsStillAlive(True) Then GoTo Finally
334 If Not ScriptForge.SF_Utils._Validate(Password, "Password", V_STRING) Then GoTo Finally
335 End If
337 Try:
339 If IsNull(_DataSource) Then GoTo CatchConnect
340 Set _Database = ScriptForge.SF_Services.CreateScriptService("SFDatabases.DatabaseFromDocument" _
341 , _DataSource, User, Password)
342 If IsNull(_Database) Then GoTo CatchConnect
343 _Database._Location = [_Super]._WindowFileName
344 EndIf
346 Finally:
347 Set GetDatabase = _Database
348 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
349 Exit Function
350 Catch:
351 GoTo Finally
352 CatchConnect:
353 ScriptForge.SF_Exception.RaiseFatal(DBCONNECTERROR, "User", User, "Password", Password, [_Super]._FileIdent())
354 GoTo Finally
355 End Function ' SFDocuments.SF_Base.GetDatabase
357 REM -----------------------------------------------------------------------------
358 Public Function GetProperty(Optional ByVal PropertyName As Variant) As Variant
359 ''' Return the actual value of the given property
360 ''' Args:
361 ''' PropertyName: the name of the property as a string
362 ''' Returns:
363 ''' The actual value of the property
364 ''' Exceptions:
365 ''' ARGUMENTERROR The property does not exist
368 Const cstSubArgs = ""
370 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
371 GetProperty = Null
373 Check:
374 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
375 If Not ScriptForge.SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
376 End If
378 Try:
379 ' Superclass or subclass property ?
380 If ScriptForge.SF_Array.Contains([_Super].Properties(), PropertyName) Then
381 GetProperty = [_Super].GetProperty(PropertyName)
382 Else
383 GetProperty = _PropertyGet(PropertyName)
384 End If
386 Finally:
387 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
388 Exit Function
389 Catch:
390 GoTo Finally
391 End Function ' SFDocuments.SF_Base.GetProperty
393 REM -----------------------------------------------------------------------------
394 Public Function IsLoaded(Optional ByVal FormDocument As Variant) As Boolean
395 ''' Return True if the given FormDocument is open for the user
396 ''' Args:
397 ''' FormDocument: a valid document form name as a case-sensitive string
398 ''' Returns:
399 ''' True if the form document is currently open, otherwise False
400 ''' Exceptions:
401 ''' Form name is invalid
402 ''' Example:
405 Dim bLoaded As Boolean ' Return value
406 Dim vFormNames As Variant ' Array of all document form names present in the document
407 Dim oMainForm As Object ' com.sun.star.comp.sdb.Content
411 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
412 bLoaded = False
414 Check:
415 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
416 If Not _IsStillAlive() Then GoTo Finally
417 ' Build list of available FormDocuments recursively with _CollectFormDocuments
418 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
419 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
420 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames) Then GoTo Finally
421 End If
423 Try:
424 Set oMainForm = _FormDocuments.getByHierarchicalName(FormDocument)
425 ' A document form that has never been opened has no component
426 ' If ever opened and closed afterwards, it keeps the Component but loses its Controller
427 bLoaded = Not IsNull(oMainForm.Component)
428 If bLoaded Then bLoaded = Not IsNull(oMainForm.Component.CurrentController)
430 Finally:
431 IsLoaded = bLoaded
432 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
433 Exit Function
434 Catch:
435 GoTo Finally
436 End Function ' SFDocuments.SF_Base.IsLoaded
438 REM -----------------------------------------------------------------------------
439 Public Function Methods() As Variant
440 ''' Return the list of public methods of the Base class as an array
442 Methods = Array( _
451 )
453 End Function ' SFDocuments.SF_Base.Methods
455 REM -----------------------------------------------------------------------------
456 Public Function OpenFormDocument(Optional ByVal FormDocument As Variant _
457 , Optional ByVal DesignMode As Variant _
458 ) As Boolean
459 ''' Open the FormDocument given by its hierarchical name either in normal or in design mode
460 ''' If the form document is already open, the form document is made active without changing its mode
461 ''' Args:
462 ''' FormDocument: a valid form document name as a case-sensitive string
463 ''' DesignMode: when True the form document is opened in design mode (Default = False)
464 ''' Returns:
465 ''' True if the form document could be opened, otherwise False
466 ''' Exceptions:
467 ''' Form name is invalid
468 ''' Example:
471 Dim bOpen As Boolean ' Return value
472 Dim vFormNames As Variant ' Array of all document form names present in the document
473 Dim oContainer As Object ' com.sun.star.awt.XWindow
474 Dim oNewForm As Object ' Output of loadComponent()
478 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
479 bOpen = False
481 Check:
482 If IsMissing(DesignMode) Or IsEmpty(DesignMode) Then DesignMode = False
483 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
484 If Not _IsStillAlive() Then GoTo Finally
485 ' Build list of available FormDocuments recursively with _CollectFormDocuments
486 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
487 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
488 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames) Then GoTo Finally
489 If Not ScriptForge.SF_Utils._Validate(DesignMode, "DesignMode", ScriptForge.V_BOOLEAN) Then GoTo Finally
490 End If
492 Try:
493 With _Component.CurrentController
494 If Not .IsConnected Then .connect()
495 ' loadComponent activates the form when already loaded
496 Set oNewForm = .loadComponent(com.sun.star.sdb.application.DatabaseObject.FORM, FormDocument, DesignMode)
497 ' When user opened manually the form in design mode and closed it, the next execution in normal mode needs to be confirmed as below
498 With oNewForm.CurrentController
499 If .isFormDesignMode() <> DesignMode Then .setFormDesignMode(DesignMode)
500 End With
501 End With
502 bOpen = True
504 Finally:
505 OpenFormDocument = bOpen
506 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
507 Exit Function
508 Catch:
509 GoTo Finally
510 End Function ' SFDocuments.SF_Base.OpenFormDocument
512 REM -----------------------------------------------------------------------------
513 Public Function OpenQuery(Optional ByVal QueryName As Variant _
514 , Optional ByVal DesignMode As Variant _
515 ) As Object
516 ''' Open the query given by its name either in normal or in design mode
517 ''' If the query is already open, the query datasheet is made active without changing its mode
518 ''' If still open, the datasheet will be closed together with the actual Base document.
519 ''' Args:
520 ''' QueryName: a valid Query name as a case-sensitive string
521 ''' DesignMode: when True the query is opened in design mode (Default = False)
522 ''' Returns:
523 ''' A Datasheet class instance if the query could be opened and DesignMode = False, otherwise False
524 ''' Exceptions:
525 ''' Query name is invalid
526 ''' Example:
529 Dim oOpen As Object ' Return value
530 Dim vQueries As Variant ' Array of query names
531 Dim oNewQuery As Object ' Output of loadComponent()
535 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
536 Set oOpen = Nothing
538 Check:
539 If IsMissing(DesignMode) Or IsEmpty(DesignMode) Then DesignMode = False
540 vQueries = GetDatabase().Queries ' Includes _IsStillAlive()
541 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
542 If Not ScriptForge.SF_Utils._Validate(QueryName, "QueryName", V_STRING, vQueries) Then GoTo Finally
543 If Not ScriptForge.SF_Utils._Validate(DesignMode, "DesignMode", ScriptForge.V_BOOLEAN) Then GoTo Finally
544 End If
546 Try:
547 With _Component.CurrentController
548 ' The connection may have been done previously by a user command. If not, do it now.
549 If Not .IsConnected Then .connect()
550 ' loadComponent activates the query component when already loaded
551 Set oNewQuery = .loadComponent(com.sun.star.sdb.application.DatabaseObject.QUERY, QueryName, DesignMode)
552 End With
553 ' When design mode, the method returns Nothing
554 If Not DesignMode Then Set oOpen = ScriptForge.SF_Services.CreateScriptService("SFDatabases.Datasheet", oNewQuery, [Me])
556 Finally:
557 Set OpenQuery = oOpen
558 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
559 Exit Function
560 Catch:
561 GoTo Finally
562 End Function ' SFDocuments.SF_Base.OpenQuery
564 REM -----------------------------------------------------------------------------
565 Public Function OpenTable(Optional ByVal TableName As Variant _
566 , Optional ByVal DesignMode As Variant _
567 ) As Object
568 ''' Open the table given by its name either in normal or in design mode
569 ''' If the table is already open, the table datasheet is made active without changing its mode
570 ''' If still open, the datasheet will be closed together with the actual Base document.
571 ''' Args:
572 ''' TableName: a valid table name as a case-sensitive string
573 ''' DesignMode: when True the table is opened in design mode (Default = False)
574 ''' Returns:
575 ''' A Datasheet class instance if the table could be opened or was already open, and DesignMode = False.
576 ''' Otherwise Nothing
577 ''' Exceptions:
578 ''' Table name is invalid
579 ''' Example:
582 Dim oOpen As Object ' Return value
583 Dim vTables As Variant ' Array of table names
584 Dim oNewTable As Object ' Output of loadComponent()
588 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
589 Set oOpen = Nothing
591 Check:
592 If IsMissing(DesignMode) Or IsEmpty(DesignMode) Then DesignMode = False
593 vTables = GetDatabase().Tables
594 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
595 If Not ScriptForge.SF_Utils._Validate(TableName, "TableName", V_STRING, vTables) Then GoTo Finally
596 If Not ScriptForge.SF_Utils._Validate(DesignMode, "DesignMode", ScriptForge.V_BOOLEAN) Then GoTo Finally
597 End If
599 Try:
600 With _Component.CurrentController
601 ' The connection may have been done previously by a user command. If not, do it now.
602 If Not .IsConnected Then .connect()
603 ' loadComponent activates the table component when already loaded
604 Set oNewTable = .loadComponent(com.sun.star.sdb.application.DatabaseObject.TABLE, TableName, DesignMode)
605 End With
606 ' When design mode, the method returns Nothing
607 If Not DesignMode Then Set oOpen = ScriptForge.SF_Services.CreateScriptService("SFDatabases.Datasheet", oNewTable, [Me])
609 Finally:
610 Set OpenTable = oOpen
611 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
612 Exit Function
613 Catch:
614 GoTo Finally
615 End Function ' SFDocuments.SF_Base.OpenTable
617 REM -----------------------------------------------------------------------------
618 Public Function PrintOut(Optional ByVal FormDocument As Variant _
619 , Optional ByVal Pages As Variant _
620 , Optional ByVal Copies As Variant _
621 ) As Boolean
622 ''' Send the content of the given form document to the printer.
623 ''' The printer might be defined previously by default, by the user or by the SetPrinter() method
624 ''' The given form document must be open. It is activated by the method.
625 ''' Args:
626 ''' FormDocument: a valid document form name as a case-sensitive string
627 ''' Pages: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages
628 ''' Copies: the number of copies
629 ''' Exceptions:
630 ''' FORMDEADERROR The form is not open
631 ''' Returns:
632 ''' True when successful
633 ''' Examples:
636 Dim bPrint As Boolean ' Return value
637 Dim vFormNames As Variant ' Array of all document form names present in the document
638 Dim oFormDocument As Object ' com.sun.star.comp.sdb.Content
643 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
644 bPrint = False
646 Check:
647 If IsMissing(Pages) Or IsEmpty(Pages) Then Pages = ""
648 If IsMissing(Copies) Or IsEmpty(Copies) Then Copies = 1
650 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
651 If Not _IsStillAlive() Then GoTo Finally
652 ' Build list of available FormDocuments recursively with _CollectFormDocuments
653 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
654 vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
655 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames) Then GoTo Finally
657 If Not ScriptForge.SF_Utils._Validate(Copies, "Copies", ScriptForge.V_NUMERIC) Then GoTo Finally
658 End If
659 If Not IsLoaded(FormDocument) Then GoTo CatchClosed
661 Try:
662 Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
663 bPrint = [_Super].PrintOut(Pages, Copies, oFormDocument.Component)
665 Finally:
666 PrintOut = bPrint
667 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
668 Exit Function
669 Catch:
670 GoTo Finally
671 CatchClosed:
672 ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
673 End Function ' SFDocuments.SF_Base.PrintOut
675 REM -----------------------------------------------------------------------------
676 Public Function Properties() As Variant
677 ''' Return the list or properties of the Base class as an array
679 Properties = Array( _
688 )
690 End Function ' SFDocuments.SF_Base.Properties
692 REM -----------------------------------------------------------------------------
693 Public Function SetPrinter(Optional ByVal FormDocument As Variant _
694 , Optional ByVal Printer As Variant _
695 , Optional ByVal Orientation As Variant _
696 , Optional ByVal PaperFormat As Variant _
697 ) As Boolean
698 ''' Define the printer options for a form document. The form document must be open.
699 ''' Args:
700 ''' FormDocument: a valid document form name as a case-sensitive string
701 ''' Printer: the name of the printer queue where to print to
702 ''' When absent or space, the default printer is set
703 ''' Orientation: either "PORTRAIT" or "LANDSCAPE". Left unchanged when absent
704 ''' PaperFormat: one of next values
705 ''' "A3", "A4", "A5", "B4", "B5", "LETTER", "LEGAL", "TABLOID"
706 ''' Left unchanged when absent
707 ''' Returns:
708 ''' True when successful
709 ''' Examples:
712 Dim bPrinter As Boolean ' Return value
713 Dim vFormDocuments As Variant ' Array of form documents
714 Dim oFormDocument As Object ' com.sun.star.comp.sdb.Content
717 Const cstSubArgs = "FormDocument, [Printer=""""], [Orientation=""PORTRAIT""|""LANDSCAPE""]" _
718 & ", [PaperFormat=""A3""|""A4""|""A5""|""B4""|""B5""|""LETTER""|""LEGAL""|""TABLOID"""
720 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
721 bPrinter = False
723 Check:
724 If IsMissing(Printer) Or IsEmpty(Printer) Then Printer = ""
725 If IsMissing(Orientation) Or IsEmpty(Orientation) Then Orientation = ""
726 If IsMissing(PaperFormat) Or IsEmpty(PaperFormat) Then PaperFormat = ""
728 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
729 If Not _IsStillAlive() Then GoTo Finally
730 ' Build list of available FormDocuments recursively with _CollectFormDocuments
731 If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
732 vFormDocuments = Split(_CollectFormDocuments(_FormDocuments), cstToken)
733 If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormDocuments) Then GoTo Finally
734 End If
735 If Not IsLoaded(FormDocument) Then GoTo CatchClosed
737 Try:
738 Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
739 bPrinter = [_Super].SetPrinter(Printer, Orientation, PaperFormat, oFormDocument.Component)
741 Finally:
742 SetPrinter = bPrinter
743 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
744 Exit Function
745 Catch:
746 GoTo Finally
747 CatchClosed:
748 ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
749 End Function ' SFDocuments.SF_Base.SetPrinter
751 REM -----------------------------------------------------------------------------
752 Public Function SetProperty(Optional ByVal PropertyName As Variant _
753 , Optional ByRef Value As Variant _
754 ) As Boolean
755 ''' Set a new value to the given property
756 ''' Args:
757 ''' PropertyName: the name of the property as a string
758 ''' Value: its new value
759 ''' Exceptions
760 ''' ARGUMENTERROR The property does not exist
765 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
766 SetProperty = False
768 Check:
769 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
770 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
771 End If
773 Try:
774 Select Case UCase(PropertyName)
775 Case Else
776 End Select
778 Finally:
779 SF_Utils._ExitFunction(cstThisSub)
780 Exit Function
781 Catch:
782 GoTo Finally
783 End Function ' SFDocuments.SF_Base.SetProperty
785 REM ======================================================= SUPERCLASS PROPERTIES
787 REM -----------------------------------------------------------------------------
788 'Property Get CustomProperties() As Variant
792 REM -----------------------------------------------------------------------------
793 'Property Let CustomProperties(Optional ByVal pvCustomProperties As Variant)
794 ' [_Super].CustomProperties = pvCustomProperties
797 REM -----------------------------------------------------------------------------
798 'Property Get Description() As Variant
802 REM -----------------------------------------------------------------------------
803 'Property Let Description(Optional ByVal pvDescription As Variant)
804 ' [_Super].Description = pvDescription
807 REM -----------------------------------------------------------------------------
808 'Property Get DocumentProperties() As Variant
812 REM -----------------------------------------------------------------------------
813 Property Get DocumentType() As String
815 End Property ' SFDocuments.SF_Base.DocumentType
817 REM -----------------------------------------------------------------------------
818 Property Get IsBase() As Boolean
820 End Property ' SFDocuments.SF_Base.IsBase
822 REM -----------------------------------------------------------------------------
823 Property Get IsCalc() As Boolean
825 End Property ' SFDocuments.SF_Base.IsCalc
827 REM -----------------------------------------------------------------------------
828 Property Get IsDraw() As Boolean
830 End Property ' SFDocuments.SF_Base.IsDraw
832 REM -----------------------------------------------------------------------------
833 Property Get IsImpress() As Boolean
835 End Property ' SFDocuments.SF_Base.IsImpress
837 REM -----------------------------------------------------------------------------
838 Property Get IsMath() As Boolean
840 End Property ' SFDocuments.SF_Base.IsMath
842 REM -----------------------------------------------------------------------------
843 Property Get IsWriter() As Boolean
845 End Property ' SFDocuments.SF_Base.IsWriter
847 REM -----------------------------------------------------------------------------
848 'Property Get Keywords() As Variant
852 REM -----------------------------------------------------------------------------
853 'Property Let Keywords(Optional ByVal pvKeywords As Variant)
854 ' [_Super].Keywords = pvKeywords
857 REM -----------------------------------------------------------------------------
858 'Property Get Readonly() As Variant
862 REM -----------------------------------------------------------------------------
863 'Property Get Subject() As Variant
867 REM -----------------------------------------------------------------------------
868 'Property Let Subject(Optional ByVal pvSubject As Variant)
869 ' [_Super].Subject = pvSubject
872 REM -----------------------------------------------------------------------------
873 'Property Get Title() As Variant
877 REM -----------------------------------------------------------------------------
878 'Property Let Title(Optional ByVal pvTitle As Variant)
879 ' [_Super].Title = pvTitle
882 REM -----------------------------------------------------------------------------
883 Property Get XComponent() As Variant
885 End Property ' SFDocuments.SF_Base.XComponent
887 REM ========================================================== SUPERCLASS METHODS
889 REM -----------------------------------------------------------------------------
890 Public Function Activate() As Boolean
891 Activate = [_Super].Activate()
892 End Function ' SFDocuments.SF_Base.Activate
894 REM -----------------------------------------------------------------------------
895 Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
896 , Optional ByVal Before As Variant _
897 , Optional ByVal SubmenuChar As Variant _
898 ) As Object
899 Set CreateMenu = [_Super].CreateMenu(MenuHeader, Before, SubmenuChar)
900 End Function ' SFDocuments.SF_Base.CreateMenu
902 REM -----------------------------------------------------------------------------
903 Public Function RemoveMenu(Optional ByVal MenuHeader As Variant) As Boolean
904 RemoveMenu = [_Super].RemoveMenu(MenuHeader)
905 End Function ' SFDocuments.SF_Base.RemoveMenu
907 REM -----------------------------------------------------------------------------
908 Public Sub RunCommand(Optional ByVal Command As Variant _
909 , ParamArray Args As Variant _
910 )
911 [_Super].RunCommand(Command, Args)
912 End Sub ' SFDocuments.SF_Base.RunCommand
914 REM -----------------------------------------------------------------------------
915 Public Function Save() As Boolean
916 Save = [_Super].Save()
917 End Function ' SFDocuments.SF_Base.Save
919 REM -----------------------------------------------------------------------------
920 Public Function SaveAs(Optional ByVal FileName As Variant _
921 , Optional ByVal Overwrite As Variant _
922 , Optional ByVal Password As Variant _
923 , Optional ByVal FilterName As Variant _
924 , Optional ByVal FilterOptions As Variant _
925 ) As Boolean
926 SaveAs = [_Super].SaveAs(FileName, Overwrite, Password, FilterName, FilterOptions)
927 End Function ' SFDocuments.SF_Base.SaveAs
929 REM -----------------------------------------------------------------------------
930 Public Function SaveCopyAs(Optional ByVal FileName As Variant _
931 , Optional ByVal Overwrite As Variant _
932 , Optional ByVal Password As Variant _
933 , Optional ByVal FilterName As Variant _
934 , Optional ByVal FilterOptions As Variant _
935 ) As Boolean
936 SaveCopyAs = [_Super].SaveCopyAs(FileName, Overwrite, Password, FilterName, FilterOptions)
937 End Function ' SFDocuments.SF_Base.SaveCopyAs
939 REM =========================================================== PRIVATE FUNCTIONS
941 REM -----------------------------------------------------------------------------
942 Private Function _CollectFormDocuments(ByRef poContainer As Object) As String
943 ''' Returns a token-separated string of all hierarchical formdocument names
944 ''' depending on the formdocuments container in argument
945 ''' The function traverses recursively the whole tree below the container
946 ''' The initial call starts from the container _Component.getFormDocuments
947 ''' The list contains closed and open forms
949 Dim sCollectNames As String ' Return value
950 Dim oSubItem As Object ' com.sun.star.container.XNameAccess (folder) or com.sun.star.ucb.XContent (form)
951 Dim i As Long
953 ' Identifies forms. Folders have a zero-length content type
955 On Local Error GoTo Finally
957 Try:
958 sCollectNames = ""
959 With poContainer
961 Set oSubItem = .getByIndex(i)
962 If oSubItem.ContentType = cstFormType Then ' Add the form to the list
964 Else
966 End If
967 Next i
968 End With
970 Finally:
972 Exit Function
973 End Function ' SFDocuments.SF_Base._CollectFormDocuments
975 REM -----------------------------------------------------------------------------
976 Private Function _FileIdent() As String
977 ''' Returns a file identification from the information that is currently available
978 ''' Useful e.g. for display in error messages
980 _FileIdent = [_Super]._FileIdent()
982 End Function ' SFDocuments.SF_Base._FileIdent
984 REM -----------------------------------------------------------------------------
985 Private Function _FindByPersistentName(ByRef poContainer As Object _
986 , psPersistent As String _
987 ) As Object
988 ''' The FormDocuments property of a Base component has strangely
989 ''' a getByHierarchical() method but no access to the same com.sun.star.comp.sdb.Content
990 ''' object via its persistent/ODF name
991 ''' This method returns the object having the given persistent name
992 ''' The function traverses recursively the whole tree below the container until found
993 ''' The initial call starts from the container _Component.getFormDocuments
994 ''' The list contains closed and open forms
995 ''' Args:
996 ''' poContainer: the actual top of the free, initially _FormDocuments
998 ''' Returns:
999 ''' A com.sun.star.comp.sdb.Content object (object found, the process stops)
1000 ''' or Nothing (object not found, the process continues)
1002 Dim oMainForm As Object ' Return value
1003 Dim oSubItem As Object ' com.sun.star.container.XNameAccess (folder) or com.sun.star.ucb.XContent (form)
1004 Dim i As Long
1006 ' Identifies forms. Folders have a zero-length content type
1008 On Local Error GoTo Finally
1010 Try:
1011 Set oMainForm = Nothing
1012 With poContainer
1014 Set oSubItem = .getByIndex(i)
1015 If oSubItem.ContentType = cstFormType Then ' Examine its persistent name
1016 If oSubItem.PersistentName = psPersistent Then
1017 Set oMainForm = oSubItem
1018 Exit For
1019 End If
1020 Else
1021 Set oMainForm = _FindByPersistentName(oSubItem, psPersistent)
1022 End If
1023 Next i
1024 End With
1026 Finally:
1027 Set _FindByPersistentName = oMainForm
1028 Exit Function
1029 End Function ' SFDocuments.SF_Base.FindByPersistentName
1031 REM -----------------------------------------------------------------------------
1032 Private Function _IsStillAlive(Optional ByVal pbForUpdate As Boolean _
1033 , Optional ByVal pbError As Boolean _
1034 ) As Boolean
1035 ''' Returns True if the document has not been closed manually or incidentally since the last use
1036 ''' If dead the actual instance is disposed. The execution is cancelled when pbError = True (default)
1037 ''' Args:
1038 ''' pbForUpdate: if True (default = False), check additionally if document is open for editing
1039 ''' pbError: if True (default), raise a fatal error
1041 Dim bAlive As Boolean ' Return value
1043 If IsMissing(pbForUpdate) Then pbForUpdate = False
1044 If IsMissing(pbError) Then pbError = True
1046 Try:
1047 bAlive = [_Super]._IsStillAlive(pbForUpdate, pbError)
1049 Finally:
1050 _IsStillAlive = bAlive
1051 Exit Function
1052 End Function ' SFDocuments.SF_Base._IsStillAlive
1054 REM -----------------------------------------------------------------------------
1055 Private Function _PropertyGet(Optional ByVal psProperty As String _
1056 , Optional ByVal pvArg As Variant _
1057 ) As Variant
1058 ''' Return the value of the named property
1059 ''' Args:
1060 ''' psProperty: the name of the property
1062 Dim oProperties As Object ' Document or Custom properties
1063 Dim vLastCell As Variant ' Coordinates of last used cell in a sheet
1064 Dim oSelect As Object ' Current selection
1065 Dim vRanges As Variant ' List of selected ranges
1066 Dim i As Long
1067 Dim cstThisSub As String
1068 Const cstSubArgs = ""
1070 _PropertyGet = False
1073 ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
1074 If Not _IsStillAlive() Then GoTo Finally
1076 Select Case psProperty
1077 Case Else
1078 _PropertyGet = Null
1079 End Select
1081 Finally:
1082 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
1083 Exit Function
1084 End Function ' SFDocuments.SF_Base._PropertyGet
1086 REM -----------------------------------------------------------------------------
1087 Private Function _Repr() As String
1088 ''' Convert the SF_Base instance to a readable string, typically for debugging purposes (DebugPrint ...)
1089 ''' Args:
1090 ''' Return:
1095 End Function ' SFDocuments.SF_Base._Repr
1097 REM ============================================ END OF SFDOCUMENTS.SF_BASE
1098 </script:module>