| blob | eded35de9a96e13b829fd20742d3fa05a3508c77 |
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( _
222 )
224 End Function ' SFDocuments.SF_Writer.Methods
226 REM -----------------------------------------------------------------------------
227 Public Function PrintOut(Optional ByVal Pages As Variant _
228 , Optional ByVal Copies As Variant _
229 , Optional ByVal PrintBackground As Variant _
230 , Optional ByVal PrintBlankPages As Variant _
231 , Optional ByVal PrintEvenPages As Variant _
232 , Optional ByVal PrintOddPages As Variant _
233 , Optional ByVal PrintImages As Variant _
234 ) As Boolean
235 ''' Send the content of the document to the printer.
236 ''' The printer might be defined previously by default, by the user or by the SetPrinter() method
237 ''' Args:
238 ''' Pages: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages
239 ''' Copies: the number of copies
240 ''' PrintBackground: print the background image when True (default)
241 ''' PrintBlankPages: when False (default), omit empty pages
242 ''' PrintEvenPages: print the left pages when True (default)
243 ''' PrintOddPages: print the right pages when True (default)
244 ''' PrintImages: print the graphic objects when True (default)
245 ''' Returns:
246 ''' True when successful
247 ''' Examples:
250 Dim bPrint As Boolean ' Return value
251 Dim vPrintOptions As Variant ' com.sun.star.text.DocumentSettings
254 Const cstSubArgs = "[Pages=""""], [Copies=1], [PrintBackground=True], [PrintBlankPages=False], [PrintEvenPages=True]" _
257 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
258 bPrint = False
260 Check:
261 If IsMissing(Pages) Or IsEmpty(Pages) Then Pages = ""
262 If IsMissing(Copies) Or IsEmpty(Copies) Then Copies = 1
263 If IsMissing(PrintBackground) Or IsEmpty(PrintBackground) Then PrintBackground = True
264 If IsMissing(PrintBlankPages) Or IsEmpty(PrintBlankPages) Then PrintBlankPages = False
265 If IsMissing(PrintEvenPages) Or IsEmpty(PrintEvenPages) Then PrintEvenPages = True
266 If IsMissing(PrintOddPages) Or IsEmpty(PrintOddPages) Then PrintOddPages = True
267 If IsMissing(PrintImages) Or IsEmpty(PrintImages) Then PrintImages = True
269 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
270 If Not _IsStillAlive() Then GoTo Finally
272 If Not ScriptForge.SF_Utils._Validate(Copies, "Copies", ScriptForge.V_NUMERIC) Then GoTo Finally
273 If Not ScriptForge.SF_Utils._Validate(PrintBackground, "PrintBackground", ScriptForge.V_BOOLEAN) Then GoTo Finally
274 If Not ScriptForge.SF_Utils._Validate(PrintBlankPages, "PrintBlankPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
275 If Not ScriptForge.SF_Utils._Validate(PrintEvenPages, "PrintEvenPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
276 If Not ScriptForge.SF_Utils._Validate(PrintOddPages, "PrintOddPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
277 If Not ScriptForge.SF_Utils._Validate(PrintImages, "PrintImages", ScriptForge.V_BOOLEAN) Then GoTo Finally
278 End If
280 Try:
282 With vPrintOptions
283 .PrintPageBackground = PrintBackground
284 .PrintEmptyPages = PrintBlankPages
285 .PrintLeftPages = PrintEvenPages
286 .PrintRightPages = PrintOddPages
287 .PrintGraphics = PrintImages
288 .PrintDrawings = PrintImages
289 End With
291 bPrint = [_Super].PrintOut(Pages, Copies, _Component)
293 Finally:
294 PrintOut = bPrint
295 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
296 Exit Function
297 Catch:
298 GoTo Finally
299 End Function ' SFDocuments.SF_Writer.PrintOut
301 REM -----------------------------------------------------------------------------
302 Public Function Properties() As Variant
303 ''' Return the list or properties of the Writer class as an array
305 Properties = Array( _
323 )
325 End Function ' SFDocuments.SF_Writer.Properties
327 REM -----------------------------------------------------------------------------
328 Private Function SetProperty(Optional ByVal psProperty As String _
329 , Optional ByVal pvValue As Variant _
330 ) As Boolean
331 ''' Set the new value of the named property
332 ''' Args:
333 ''' psProperty: the name of the property
334 ''' pvValue: the new value of the given property
335 ''' Returns:
336 ''' True if successful
338 Dim bSet As Boolean ' Return value
339 Static oSession As Object ' Alias of SF_Session
340 Dim cstThisSub As String
343 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
344 bSet = False
347 If IsMissing(pvValue) Then pvValue = Empty
348 'ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) ' Validation done in Property Lets
350 If IsNull(oSession) Then Set oSession = ScriptForge.SF_Services.CreateScriptService("Session")
351 bSet = True
352 Select Case UCase(psProperty)
354 CustomProperties = pvValue
356 Description = pvValue
358 Keywords = pvValue
360 Subject = pvValue
362 Title = pvValue
363 Case Else
364 bSet = False
365 End Select
367 Finally:
368 SetProperty = bSet
369 'ScriptForge.SF_Utils._ExitFunction(cstThisSub)
370 Exit Function
371 Catch:
372 GoTo Finally
373 End Function ' SFDocuments.SF_Writer.SetProperty
375 REM ======================================================= SUPERCLASS PROPERTIES
377 REM -----------------------------------------------------------------------------
378 Property Get CustomProperties() As Variant
380 End Property ' SFDocuments.SF_Writer.CustomProperties
382 REM -----------------------------------------------------------------------------
383 Property Let CustomProperties(Optional ByVal pvCustomProperties As Variant)
384 [_Super].CustomProperties = pvCustomProperties
385 End Property ' SFDocuments.SF_Writer.CustomProperties
387 REM -----------------------------------------------------------------------------
388 Property Get Description() As Variant
390 End Property ' SFDocuments.SF_Writer.Description
392 REM -----------------------------------------------------------------------------
393 Property Let Description(Optional ByVal pvDescription As Variant)
394 [_Super].Description = pvDescription
395 End Property ' SFDocuments.SF_Writer.Description
397 REM -----------------------------------------------------------------------------
398 Property Get DocumentProperties() As Variant
400 End Property ' SFDocuments.SF_Writer.DocumentProperties
402 REM -----------------------------------------------------------------------------
403 Property Get DocumentType() As String
405 End Property ' SFDocuments.SF_Writer.DocumentType
407 REM -----------------------------------------------------------------------------
408 Property Get ExportFilters() As Variant
410 End Property ' SFDocuments.SF_Writer.ExportFilters
412 REM -----------------------------------------------------------------------------
413 Property Get ImportFilters() As Variant
415 End Property ' SFDocuments.SF_Writer.ImportFilters
417 REM -----------------------------------------------------------------------------
418 Property Get IsBase() As Boolean
420 End Property ' SFDocuments.SF_Writer.IsBase
422 REM -----------------------------------------------------------------------------
423 Property Get IsCalc() As Boolean
425 End Property ' SFDocuments.SF_Writer.IsCalc
427 REM -----------------------------------------------------------------------------
428 Property Get IsDraw() As Boolean
430 End Property ' SFDocuments.SF_Writer.IsDraw
432 REM -----------------------------------------------------------------------------
433 Property Get IsImpress() As Boolean
435 End Property ' SFDocuments.SF_Writer.IsImpress
437 REM -----------------------------------------------------------------------------
438 Property Get IsMath() As Boolean
440 End Property ' SFDocuments.SF_Writer.IsMath
442 REM -----------------------------------------------------------------------------
443 Property Get IsWriter() As Boolean
445 End Property ' SFDocuments.SF_Writer.IsWriter
447 REM -----------------------------------------------------------------------------
448 Property Get Keywords() As Variant
450 End Property ' SFDocuments.SF_Writer.Keywords
452 REM -----------------------------------------------------------------------------
453 Property Let Keywords(Optional ByVal pvKeywords As Variant)
454 [_Super].Keywords = pvKeywords
455 End Property ' SFDocuments.SF_Writer.Keywords
457 REM -----------------------------------------------------------------------------
458 Property Get Readonly() As Variant
460 End Property ' SFDocuments.SF_Writer.Readonly
462 REM -----------------------------------------------------------------------------
463 Property Get Subject() As Variant
465 End Property ' SFDocuments.SF_Writer.Subject
467 REM -----------------------------------------------------------------------------
468 Property Let Subject(Optional ByVal pvSubject As Variant)
469 [_Super].Subject = pvSubject
470 End Property ' SFDocuments.SF_Writer.Subject
472 REM -----------------------------------------------------------------------------
473 Property Get Title() As Variant
475 End Property ' SFDocuments.SF_Writer.Title
477 REM -----------------------------------------------------------------------------
478 Property Let Title(Optional ByVal pvTitle As Variant)
479 [_Super].Title = pvTitle
480 End Property ' SFDocuments.SF_Writer.Title
482 REM -----------------------------------------------------------------------------
483 Property Get XComponent() As Variant
485 End Property ' SFDocuments.SF_Writer.XComponent
487 REM ========================================================== SUPERCLASS METHODS
489 REM -----------------------------------------------------------------------------
490 Public Function Activate() As Boolean
491 Activate = [_Super].Activate()
492 End Function ' SFDocuments.SF_Writer.Activate
494 REM -----------------------------------------------------------------------------
495 Public Function CloseDocument(Optional ByVal SaveAsk As Variant) As Boolean
496 CloseDocument = [_Super].CloseDocument(SaveAsk)
497 End Function ' SFDocuments.SF_Writer.CloseDocument
499 REM -----------------------------------------------------------------------------
500 Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
501 , Optional ByVal Before As Variant _
502 , Optional ByVal SubmenuChar As Variant _
503 ) As Object
504 Set CreateMenu = [_Super].CreateMenu(MenuHeader, Before, SubmenuChar)
505 End Function ' SFDocuments.SF_Writer.CreateMenu
507 REM -----------------------------------------------------------------------------
508 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
509 , Optional ByVal Overwrite As Variant _
510 , Optional ByVal Pages As Variant _
511 , Optional ByVal Password As Variant _
512 , Optional ByVal Watermark As Variant _
513 ) As Boolean
514 ExportAsPDF = [_Super].ExportAsPDF(FileName, Overwrite, Pages, Password, Watermark)
515 End Function ' SFDocuments.SF_Writer.ExportAsPDF
517 REM -----------------------------------------------------------------------------
518 Public Function RemoveMenu(Optional ByVal MenuHeader As Variant) As Boolean
519 RemoveMenu = [_Super].RemoveMenu(MenuHeader)
520 End Function ' SFDocuments.SF_Writer.RemoveMenu
522 REM -----------------------------------------------------------------------------
523 Public Sub RunCommand(Optional ByVal Command As Variant _
524 , ParamArray Args As Variant _
525 )
526 [_Super].RunCommand(Command, Args)
527 End Sub ' SFDocuments.SF_Writer.RunCommand
529 REM -----------------------------------------------------------------------------
530 Public Function Save() As Boolean
531 Save = [_Super].Save()
532 End Function ' SFDocuments.SF_Writer.Save
534 REM -----------------------------------------------------------------------------
535 Public Function SaveAs(Optional ByVal FileName As Variant _
536 , Optional ByVal Overwrite As Variant _
537 , Optional ByVal Password As Variant _
538 , Optional ByVal FilterName As Variant _
539 , Optional ByVal FilterOptions As Variant _
540 ) As Boolean
541 SaveAs = [_Super].SaveAs(FileName, Overwrite, Password, FilterName, FilterOptions)
542 End Function ' SFDocuments.SF_Writer.SaveAs
544 REM -----------------------------------------------------------------------------
545 Public Function SaveCopyAs(Optional ByVal FileName As Variant _
546 , Optional ByVal Overwrite As Variant _
547 , Optional ByVal Password As Variant _
548 , Optional ByVal FilterName As Variant _
549 , Optional ByVal FilterOptions As Variant _
550 ) As Boolean
551 SaveCopyAs = [_Super].SaveCopyAs(FileName, Overwrite, Password, FilterName, FilterOptions)
552 End Function ' SFDocuments.SF_Writer.SaveCopyAs
554 REM -----------------------------------------------------------------------------
555 Public Function SetPrinter(Optional ByVal Printer As Variant _
556 , Optional ByVal Orientation As Variant _
557 , Optional ByVal PaperFormat As Variant _
558 ) As Boolean
559 SetPrinter = [_Super].SetPrinter(Printer, Orientation, PaperFormat)
560 End Function ' SFDocuments.SF_Writer.SetPrinter
562 REM =========================================================== PRIVATE FUNCTIONS
564 REM -----------------------------------------------------------------------------
565 Private Function _FileIdent() As String
566 ''' Returns a file identification from the information that is currently available
567 ''' Useful e.g. for display in error messages
569 _FileIdent = [_Super]._FileIdent()
571 End Function ' SFDocuments.SF_Writer._FileIdent
573 REM -----------------------------------------------------------------------------
574 Private Function _IsStillAlive(Optional ByVal pbForUpdate As Boolean _
575 , Optional ByVal pbError As Boolean _
576 ) As Boolean
577 ''' Returns True if the document has not been closed manually or incidentally since the last use
578 ''' If dead the actual instance is disposed. The execution is cancelled when pbError = True (default)
579 ''' Args:
580 ''' pbForUpdate: if True (default = False), check additionally if document is open for editing
581 ''' pbError: if True (default), raise a fatal error
583 Dim bAlive As Boolean ' Return value
585 If IsMissing(pbForUpdate) Then pbForUpdate = False
586 If IsMissing(pbError) Then pbError = True
588 Try:
589 bAlive = [_Super]._IsStillAlive(pbForUpdate, pbError)
591 Finally:
592 _IsStillAlive = bAlive
593 Exit Function
594 End Function ' SFDocuments.SF_Writer._IsStillAlive
596 REM -----------------------------------------------------------------------------
597 Private Function _PropertyGet(Optional ByVal psProperty As String _
598 , Optional ByVal pvArg As Variant _
599 ) As Variant
600 ''' Return the value of the named property
601 ''' Args:
602 ''' psProperty: the name of the property
604 Dim cstThisSub As String
605 Const cstSubArgs = ""
607 _PropertyGet = False
610 ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
611 If Not _IsStillAlive() Then GoTo Finally
613 Select Case psProperty
614 Case Else
615 _PropertyGet = Null
616 End Select
618 Finally:
619 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
620 Exit Function
621 End Function ' SFDocuments.SF_Writer._PropertyGet
623 REM -----------------------------------------------------------------------------
624 Private Function _Repr() As String
625 ''' Convert the SF_Writer instance to a readable string, typically for debugging purposes (DebugPrint ...)
626 ''' Args:
627 ''' Return:
632 End Function ' SFDocuments.SF_Writer._Repr
634 REM ============================================ END OF SFDOCUMENTS.SF_WRITER
635 </script:module>