| blob | 4acdd5c750f02632e105e29bfd53580c82d9f68d |
3 <script:module xmlns:script="http://openoffice.org/2000/script" script:name="SF_Writer" 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_Writer
16 ''' =========
17 '''
18 ''' The SFDocuments library gathers a number of methods and properties making easy
19 ''' managing and manipulating 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, SF_Base, ...
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_Writer module is focused on :
30 ''' TBD
31 '''
32 ''' The current module is closely related to the "UI" service of the ScriptForge library
33 '''
34 ''' Service invocation examples:
36 ''' Dim ui As Object, oDoc As Object
41 ''' Dim oDoc As Object
42 ''' Set oDoc = CreateScriptService("SFDocuments.Writer", "Untitled 1") ' Default = ActiveWindow
43 ''' ' or Set oDoc = CreateScriptService("SFDocuments.Writer", "Untitled 1") ' Untitled 1 is presumed a Writer document
45 '''
46 ''' Definitions:
47 ''' TBD
48 '''
49 ''' Detailed user documentation:
50 ''' https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/SF_Writer.html?DbPAR=BASIC
51 '''
52 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
54 REM ================================================================== EXCEPTIONS
58 REM ============================================================= PRIVATE MEMBERS
60 Private [Me] As Object
61 Private [_Parent] As Object
62 Private [_Super] As Object ' Document superclass, which the current instance is a subclass of
63 Private ObjectType As String ' Must be WRITER
64 Private ServiceName As String
66 ' Window component
67 Private _Component As Object ' com.sun.star.lang.XComponent
69 REM ============================================================ MODULE CONSTANTS
71 REM ====================================================== CONSTRUCTOR/DESTRUCTOR
73 REM -----------------------------------------------------------------------------
74 Private Sub Class_Initialize()
75 Set [Me] = Nothing
76 Set [_Parent] = Nothing
77 Set [_Super] = Nothing
80 Set _Component = Nothing
81 End Sub ' SFDocuments.SF_Writer Constructor
83 REM -----------------------------------------------------------------------------
84 Private Sub Class_Terminate()
85 Call Class_Initialize()
86 End Sub ' SFDocuments.SF_Writer Destructor
88 REM -----------------------------------------------------------------------------
89 Public Function Dispose() As Variant
90 If Not IsNull([_Super]) Then Set [_Super] = [_Super].Dispose()
91 Call Class_Terminate()
92 Set Dispose = Nothing
93 End Function ' SFDocuments.SF_Writer Explicit Destructor
95 REM ================================================================== PROPERTIES
97 REM ===================================================================== METHODS
99 REM -----------------------------------------------------------------------------
100 Public Function Forms(Optional ByVal Form As Variant) As Variant
101 ''' Return either
102 ''' - the list of the Forms contained in the form document
103 ''' - a SFDocuments.Form object based on its name or its index
104 ''' Args:
105 ''' Form: a form stored in the document given by its name or its index
106 ''' When absent, the list of available forms is returned
108 ''' Exceptions:
109 ''' WRITERFORMNOTFOUNDERROR Form not found
110 ''' Returns:
111 ''' A zero-based array of strings if Form is absent
112 ''' An instance of the SF_Form class if Form exists
113 ''' Example:
114 ''' Dim myForm As Object, myList As Variant
115 ''' myList = oDoc.Forms()
118 Dim oForm As Object ' The new Form class instance
119 Dim oMainForm As Object ' com.sun.star.comp.sdb.Content
120 Dim oXForm As Object ' com.sun.star.form.XForm
121 Dim vFormNames As Variant ' Array of form names
122 Dim oForms As Object ' Forms collection
128 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
130 Check:
131 If IsMissing(Form) Or IsEmpty(Form) Then Form = ""
132 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
133 If Not _IsStillAlive() Then GoTo Finally
134 If Not ScriptForge.SF_Utils._Validate(Form, "Form", Array(V_STRING, ScriptForge.V_NUMERIC)) Then GoTo Finally
135 End If
137 Try:
138 ' Start from the document component and go down to forms
139 Set oForms = _Component.DrawPages(cstDrawPage).Forms
140 vFormNames = oForms.getElementNames()
143 Forms = vFormNames
144 Else
145 If VarType(Form) = V_STRING Then ' Find the form by name
146 If Not ScriptForge.SF_Array.Contains(vFormNames, Form, CaseSensitive := True) Then GoTo CatchNotFound
147 Set oXForm = oForms.getByName(Form)
148 Else ' Find the form by index
150 Set oXForm = oForms.getByIndex(Form)
151 End If
152 ' Create the new Form class instance
153 Set oForm = SF_Register._NewForm(oXForm)
154 With oForm
155 Set .[_Parent] = [Me]
156 ._FormType = ISDOCFORM
157 Set ._Component = _Component
158 ._Initialize()
159 End With
160 Set Forms = oForm
161 End If
163 Finally:
164 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
165 Exit Function
166 Catch:
167 GoTo Finally
168 CatchNotFound:
169 ScriptForge.SF_Exception.RaiseFatal(WRITERFORMNOTFOUNDERROR, Form, _FileIdent())
170 End Function ' SFDocuments.SF_Writer.Forms
172 REM -----------------------------------------------------------------------------
173 Public Function GetProperty(Optional ByVal PropertyName As Variant _
174 , Optional ObjectName As Variant _
175 ) As Variant
176 ''' Return the actual value of the given property
177 ''' Args:
178 ''' PropertyName: the name of the property as a string
179 ''' ObjectName: a sheet or range name
180 ''' Returns:
181 ''' The actual value of the property
182 ''' Exceptions:
183 ''' ARGUMENTERROR The property does not exist
186 Const cstSubArgs = ""
188 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
189 GetProperty = Null
191 Check:
192 If IsMissing(ObjectName) Or IsEmpty(ObjectName) Then ObjectName = ""
193 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
194 If Not ScriptForge.SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
195 If Not ScriptForge.SF_Utils._Validate(ObjectName, "ObjectName", V_STRING) Then GoTo Catch
196 End If
198 Try:
199 ' Superclass or subclass property ?
200 If ScriptForge.SF_Array.Contains([_Super].Properties(), PropertyName) Then
201 GetProperty = [_Super].GetProperty(PropertyName)
202 ElseIf Len(ObjectName) = 0 Then
203 GetProperty = _PropertyGet(PropertyName)
204 Else
205 GetProperty = _PropertyGet(PropertyName, ObjectName)
206 End If
208 Finally:
209 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
210 Exit Function
211 Catch:
212 GoTo Finally
213 End Function ' SFDocuments.SF_Writer.GetProperty
215 REM -----------------------------------------------------------------------------
216 Public Function Methods() As Variant
217 ''' Return the list of public methods of the Writer service as an array
219 Methods = Array( _
230 )
232 End Function ' SFDocuments.SF_Writer.Methods
234 REM -----------------------------------------------------------------------------
235 Public Function PrintOut(Optional ByVal Pages As Variant _
236 , Optional ByVal Copies As Variant _
237 , Optional ByVal PrintBackground As Variant _
238 , Optional ByVal PrintBlankPages As Variant _
239 , Optional ByVal PrintEvenPages As Variant _
240 , Optional ByVal PrintOddPages As Variant _
241 , Optional ByVal PrintImages As Variant _
242 ) As Boolean
243 ''' Send the content of the document to the printer.
244 ''' The printer might be defined previously by default, by the user or by the SetPrinter() method
245 ''' Args:
246 ''' Pages: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages
247 ''' Copies: the number of copies
248 ''' PrintBackground: print the background image when True (default)
249 ''' PrintBlankPages: when False (default), omit empty pages
250 ''' PrintEvenPages: print the left pages when True (default)
251 ''' PrintOddPages: print the right pages when True (default)
252 ''' PrintImages: print the graphic objects when True (default)
253 ''' Returns:
254 ''' True when successful
255 ''' Examples:
258 Dim bPrint As Boolean ' Return value
259 Dim vPrintOptions As Variant ' com.sun.star.text.DocumentSettings
262 Const cstSubArgs = "[Pages=""""], [Copies=1], [PrintBackground=True], [PrintBlankPages=False], [PrintEvenPages=True]" _
265 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
266 bPrint = False
268 Check:
269 If IsMissing(Pages) Or IsEmpty(Pages) Then Pages = ""
270 If IsMissing(Copies) Or IsEmpty(Copies) Then Copies = 1
271 If IsMissing(PrintBackground) Or IsEmpty(PrintBackground) Then PrintBackground = True
272 If IsMissing(PrintBlankPages) Or IsEmpty(PrintBlankPages) Then PrintBlankPages = False
273 If IsMissing(PrintEvenPages) Or IsEmpty(PrintEvenPages) Then PrintEvenPages = True
274 If IsMissing(PrintOddPages) Or IsEmpty(PrintOddPages) Then PrintOddPages = True
275 If IsMissing(PrintImages) Or IsEmpty(PrintImages) Then PrintImages = True
277 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
278 If Not _IsStillAlive() Then GoTo Finally
280 If Not ScriptForge.SF_Utils._Validate(Copies, "Copies", ScriptForge.V_NUMERIC) Then GoTo Finally
281 If Not ScriptForge.SF_Utils._Validate(PrintBackground, "PrintBackground", ScriptForge.V_BOOLEAN) Then GoTo Finally
282 If Not ScriptForge.SF_Utils._Validate(PrintBlankPages, "PrintBlankPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
283 If Not ScriptForge.SF_Utils._Validate(PrintEvenPages, "PrintEvenPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
284 If Not ScriptForge.SF_Utils._Validate(PrintOddPages, "PrintOddPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
285 If Not ScriptForge.SF_Utils._Validate(PrintImages, "PrintImages", ScriptForge.V_BOOLEAN) Then GoTo Finally
286 End If
288 Try:
290 With vPrintOptions
291 .PrintPageBackground = PrintBackground
292 .PrintEmptyPages = PrintBlankPages
293 .PrintLeftPages = PrintEvenPages
294 .PrintRightPages = PrintOddPages
295 .PrintGraphics = PrintImages
296 .PrintDrawings = PrintImages
297 End With
299 bPrint = [_Super].PrintOut(Pages, Copies, _Component)
301 Finally:
302 PrintOut = bPrint
303 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
304 Exit Function
305 Catch:
306 GoTo Finally
307 End Function ' SFDocuments.SF_Writer.PrintOut
309 REM -----------------------------------------------------------------------------
310 Public Function Properties() As Variant
311 ''' Return the list or properties of the Writer class as an array
313 Properties = Array( _
329 )
331 End Function ' SFDocuments.SF_Writer.Properties
333 REM -----------------------------------------------------------------------------
334 Private Function SetProperty(Optional ByVal psProperty As String _
335 , Optional ByVal pvValue As Variant _
336 ) As Boolean
337 ''' Set the new value of the named property
338 ''' Args:
339 ''' psProperty: the name of the property
340 ''' pvValue: the new value of the given property
341 ''' Returns:
342 ''' True if successful
344 Dim bSet As Boolean ' Return value
345 Static oSession As Object ' Alias of SF_Session
346 Dim cstThisSub As String
349 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
350 bSet = False
353 If IsMissing(pvValue) Then pvValue = Empty
354 'ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) ' Validation done in Property Lets
356 If IsNull(oSession) Then Set oSession = ScriptForge.SF_Services.CreateScriptService("Session")
357 bSet = True
358 Select Case UCase(psProperty)
360 CustomProperties = pvValue
362 Description = pvValue
364 Keywords = pvValue
366 Subject = pvValue
368 Title = pvValue
369 Case Else
370 bSet = False
371 End Select
373 Finally:
374 SetProperty = bSet
375 'ScriptForge.SF_Utils._ExitFunction(cstThisSub)
376 Exit Function
377 Catch:
378 GoTo Finally
379 End Function ' SFDocuments.SF_Writer.SetProperty
381 REM ======================================================= SUPERCLASS PROPERTIES
383 REM -----------------------------------------------------------------------------
384 Property Get CustomProperties() As Variant
386 End Property ' SFDocuments.SF_Writer.CustomProperties
388 REM -----------------------------------------------------------------------------
389 Property Let CustomProperties(Optional ByVal pvCustomProperties As Variant)
390 [_Super].CustomProperties = pvCustomProperties
391 End Property ' SFDocuments.SF_Writer.CustomProperties
393 REM -----------------------------------------------------------------------------
394 Property Get Description() As Variant
396 End Property ' SFDocuments.SF_Writer.Description
398 REM -----------------------------------------------------------------------------
399 Property Let Description(Optional ByVal pvDescription As Variant)
400 [_Super].Description = pvDescription
401 End Property ' SFDocuments.SF_Writer.Description
403 REM -----------------------------------------------------------------------------
404 Property Get DocumentProperties() As Variant
406 End Property ' SFDocuments.SF_Writer.DocumentProperties
408 REM -----------------------------------------------------------------------------
409 Property Get DocumentType() As String
411 End Property ' SFDocuments.SF_Writer.DocumentType
413 REM -----------------------------------------------------------------------------
414 Property Get IsBase() As Boolean
416 End Property ' SFDocuments.SF_Writer.IsBase
418 REM -----------------------------------------------------------------------------
419 Property Get IsCalc() As Boolean
421 End Property ' SFDocuments.SF_Writer.IsCalc
423 REM -----------------------------------------------------------------------------
424 Property Get IsDraw() As Boolean
426 End Property ' SFDocuments.SF_Writer.IsDraw
428 REM -----------------------------------------------------------------------------
429 Property Get IsImpress() As Boolean
431 End Property ' SFDocuments.SF_Writer.IsImpress
433 REM -----------------------------------------------------------------------------
434 Property Get IsMath() As Boolean
436 End Property ' SFDocuments.SF_Writer.IsMath
438 REM -----------------------------------------------------------------------------
439 Property Get IsWriter() As Boolean
441 End Property ' SFDocuments.SF_Writer.IsWriter
443 REM -----------------------------------------------------------------------------
444 Property Get Keywords() As Variant
446 End Property ' SFDocuments.SF_Writer.Keywords
448 REM -----------------------------------------------------------------------------
449 Property Let Keywords(Optional ByVal pvKeywords As Variant)
450 [_Super].Keywords = pvKeywords
451 End Property ' SFDocuments.SF_Writer.Keywords
453 REM -----------------------------------------------------------------------------
454 Property Get Readonly() As Variant
456 End Property ' SFDocuments.SF_Writer.Readonly
458 REM -----------------------------------------------------------------------------
459 Property Get Subject() As Variant
461 End Property ' SFDocuments.SF_Writer.Subject
463 REM -----------------------------------------------------------------------------
464 Property Let Subject(Optional ByVal pvSubject As Variant)
465 [_Super].Subject = pvSubject
466 End Property ' SFDocuments.SF_Writer.Subject
468 REM -----------------------------------------------------------------------------
469 Property Get Title() As Variant
471 End Property ' SFDocuments.SF_Writer.Title
473 REM -----------------------------------------------------------------------------
474 Property Let Title(Optional ByVal pvTitle As Variant)
475 [_Super].Title = pvTitle
476 End Property ' SFDocuments.SF_Writer.Title
478 REM -----------------------------------------------------------------------------
479 Property Get XComponent() As Variant
481 End Property ' SFDocuments.SF_Writer.XComponent
483 REM ========================================================== SUPERCLASS METHODS
485 REM -----------------------------------------------------------------------------
486 Public Function Activate() As Boolean
487 Activate = [_Super].Activate()
488 End Function ' SFDocuments.SF_Writer.Activate
490 REM -----------------------------------------------------------------------------
491 Public Function CloseDocument(Optional ByVal SaveAsk As Variant) As Boolean
492 CloseDocument = [_Super].CloseDocument(SaveAsk)
493 End Function ' SFDocuments.SF_Writer.CloseDocument
495 REM -----------------------------------------------------------------------------
496 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
497 , Optional ByVal Overwrite As Variant _
498 , Optional ByVal Pages As Variant _
499 , Optional ByVal Password As Variant _
500 , Optional ByVal Watermark As Variant _
501 ) As Boolean
502 ExportAsPDF = [_Super].ExportAsPDF(FileName, Overwrite, Pages, Password, Watermark)
503 End Function ' SFDocuments.SF_Writer.ExportAsPDF
505 REM -----------------------------------------------------------------------------
506 Public Sub RunCommand(Optional ByVal Command As Variant)
507 [_Super].RunCommand(Command)
508 End Sub ' SFDocuments.SF_Writer.RunCommand
510 REM -----------------------------------------------------------------------------
511 Public Function Save() As Boolean
512 Save = [_Super].Save()
513 End Function ' SFDocuments.SF_Writer.Save
515 REM -----------------------------------------------------------------------------
516 Public Function SaveAs(Optional ByVal FileName As Variant _
517 , Optional ByVal Overwrite As Variant _
518 , Optional ByVal Password As Variant _
519 , Optional ByVal FilterName As Variant _
520 , Optional ByVal FilterOptions As Variant _
521 ) As Boolean
522 SaveAs = [_Super].SaveAs(FileName, Overwrite, Password, FilterName, FilterOptions)
523 End Function ' SFDocuments.SF_Writer.SaveAs
525 REM -----------------------------------------------------------------------------
526 Public Function SaveCopyAs(Optional ByVal FileName As Variant _
527 , Optional ByVal Overwrite As Variant _
528 , Optional ByVal Password As Variant _
529 , Optional ByVal FilterName As Variant _
530 , Optional ByVal FilterOptions As Variant _
531 ) As Boolean
532 SaveCopyAs = [_Super].SaveCopyAs(FileName, Overwrite, Password, FilterName, FilterOptions)
533 End Function ' SFDocuments.SF_Writer.SaveCopyAs
535 REM -----------------------------------------------------------------------------
536 Public Function SetPrinter(Optional ByVal Printer As Variant _
537 , Optional ByVal Orientation As Variant _
538 , Optional ByVal PaperFormat As Variant _
539 ) As Boolean
540 SetPrinter = [_Super].SetPrinter(Printer, Orientation, PaperFormat)
541 End Function ' SFDocuments.SF_Writer.SetPrinter
543 REM =========================================================== PRIVATE FUNCTIONS
545 REM -----------------------------------------------------------------------------
546 Private Function _FileIdent() As String
547 ''' Returns a file identification from the information that is currently available
548 ''' Useful e.g. for display in error messages
550 _FileIdent = [_Super]._FileIdent()
552 End Function ' SFDocuments.SF_Writer._FileIdent
554 REM -----------------------------------------------------------------------------
555 Private Function _IsStillAlive(Optional ByVal pbForUpdate As Boolean _
556 , Optional ByVal pbError As Boolean _
557 ) As Boolean
558 ''' Returns True if the document has not been closed manually or incidentally since the last use
559 ''' If dead the actual instance is disposed. The execution is cancelled when pbError = True (default)
560 ''' Args:
561 ''' pbForUpdate: if True (default = False), check additionally if document is open for editing
562 ''' pbError: if True (default), raise a fatal error
564 Dim bAlive As Boolean ' Return value
566 If IsMissing(pbForUpdate) Then pbForUpdate = False
567 If IsMissing(pbError) Then pbError = True
569 Try:
570 bAlive = [_Super]._IsStillAlive(pbForUpdate, pbError)
572 Finally:
573 _IsStillAlive = bAlive
574 Exit Function
575 End Function ' SFDocuments.SF_Writer._IsStillAlive
577 REM -----------------------------------------------------------------------------
578 Private Function _PropertyGet(Optional ByVal psProperty As String _
579 , Optional ByVal pvArg As Variant _
580 ) As Variant
581 ''' Return the value of the named property
582 ''' Args:
583 ''' psProperty: the name of the property
585 Dim cstThisSub As String
586 Const cstSubArgs = ""
588 _PropertyGet = False
591 ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
592 If Not _IsStillAlive() Then GoTo Finally
594 Select Case psProperty
595 Case Else
596 _PropertyGet = Null
597 End Select
599 Finally:
600 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
601 Exit Function
602 End Function ' SFDocuments.SF_Writer._PropertyGet
604 REM -----------------------------------------------------------------------------
605 Private Function _Repr() As String
606 ''' Convert the SF_Writer instance to a readable string, typically for debugging purposes (DebugPrint ...)
607 ''' Args:
608 ''' Return:
613 End Function ' SFDocuments.SF_Writer._Repr
615 REM ============================================ END OF SFDOCUMENTS.SF_WRITER
616 </script:module>