1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
|
<?xml version="1.0" encoding="UTF-8"?>
<helpdocument version="1.0">
<!--
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
-->
<meta>
<topic id="SF_Document" indexer="include" status="PUBLISH">
<title id="tit" xml-lang="en-US">SFDocuments.Document service</title>
<filename>/text/sbasic/shared/03/sf_document.xhp</filename>
</topic>
</meta>
<body>
<section id="SFDocuments-sf_document">
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987">
<bookmark_value>Document service</bookmark_value>
</bookmark>
</section>
<section id="abstract">
<h1 id="hd_id731582733781114" xml-lang="en-US"><variable id="DocumentService"><link href="text/sbasic/shared/03/sf_document.xhp" name="Exception service"><literal>SFDocuments</literal>.<literal>Document</literal> service</link></variable></h1>
<paragraph role="paragraph" id="par_id381589189355849" xml-lang="en-US">The <literal>SFDocuments</literal> library provides methods and properties to facilitate the management and manipulation of LibreOffice documents.</paragraph>
<paragraph role="paragraph" id="par_id591589189364267" xml-lang="en-US">Methods that are applicable for all types of documents (Text Documents, Sheets, Presentations, etc) are provided by the <literal>SFDocuments.Document</literal> service. Some examples are:</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id891589189452545" role="listitem" xml-lang="en-US">Opening, closing and saving documents</paragraph>
</listitem>
<listitem>
<paragraph id="par_id811589189463041" role="listitem" xml-lang="en-US">Accessing standard or custom properties of documents</paragraph>
</listitem>
</list>
</section>
<warning id="par_id301611085807704">The properties, methods or arguments marked with <emph>(*)</emph> are <emph>NOT applicable to Base documents</emph>.</warning>
<paragraph role="paragraph" id="par_id241589189701274" xml-lang="en-US">Methods and properties that are specific to certain LibreOffice components are stored in separate services, such as <literal>SFDocuments.SF_Calc</literal> and <literal>SFDocuments.SF_Base</literal>.</paragraph>
<paragraph role="paragraph" id="par_id641611090052376">Although the Basic language does not offer inheritance between object classes, the latter services may be considered as subclasses of the <literal>SFDocuments.Document</literal> service. Such subclasses can invoke the properties and methods described below.</paragraph>
<h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2>
<paragraph role="paragraph" id="par_id581611090387382">Below are three variants of how the <literal>Document</literal> service can be invoked.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<paragraph role="paragraph" id="par_id181622816732197">Using the <literal>getDocument</literal> method from the <literal>ScriptForge</literal>.<literal>UI</literal> service:</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id371582885621964">Dim ui As Object, oDoc As Object</paragraph>
<paragraph role="bascode" localize="false" id="bas_id201582885621287">Set ui = CreateScriptService("UI")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id561589191748697">Set oDoc = ui.GetDocument("Untitled 1")</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id181622818236233">Alternatively you can use the methods <literal>CreateDocument</literal> and <literal>OpenDocument</literal> from the <literal>UI</literal> service.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id511589191758563">Set oDocA = ui.CreateDocument("Calc")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id331589191766531">Set oDocB = ui.OpenDocument("C:\Documents\MyFile.odt")</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id691622816765571">Directly if the document is already open.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id371589191782045">Dim oDoc As Object</paragraph>
<paragraph role="bascode" localize="false" id="bas_id711589191788959">Set oDoc = CreateScriptService("SFDocuments.Document", "Untitled 1") 'Default = ActiveWindow</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id821622816825012">From a macro triggered by a document event.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id61598109336361">Sub RunEvent(ByRef poEvent As Object)</paragraph>
<paragraph role="bascode" localize="false" id="bas_id31598109342395"> Dim oDoc As Object</paragraph>
<paragraph role="bascode" localize="false" id="bas_id481598109349427"> Set oDoc = CreateScriptService("SFDocuments.DocumentEvent", poEvent)</paragraph>
<paragraph role="bascode" localize="false" id="bas_id401622818141194"> ' (...)</paragraph>
<paragraph role="bascode" localize="false" id="bas_id991622818141557">End Sub</paragraph>
</bascode>
<note id="par_id831622816562430">The <literal>Document</literal> service is closely related to the <literal>UI</literal> and <literal>FileSystem</literal> services.</note>
<paragraph role="paragraph" id="par_id891582733781994" xml-lang="en-US">Except when the document was closed by program with the CloseDocument method (it is then superfluous), it is recommended to free resources after use:</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id61582733781413">Set oDoc = oDoc.Dispose()</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id261622818031652">from scriptforge import CreateScriptService</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id291622818032129">ui = CreateScriptService("UI")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id781622818032358">doc = ui.GetDocument("Untitled 1")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id741622818032551"># (...)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id221622818032804">doc.Dispose()</paragraph>
</pycode>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id421622818033432">docA = ui.CreateDocument("Calc")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id451622818787113">docB = ui.OpenDocument("C:\Documents\MyFile.odt")</paragraph>
</pycode>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id931622818866918">doc = CreateScriptService("SFDocuments.Document", "Untitled 1")</paragraph>
</pycode>
<pycode>
<paragraph role="pycode" id="pyc_id551622819064247">def RunEvent(event)</paragraph>
<paragraph role="pycode" id="pyc_id311622819064554"> doc = CreateScriptService("SFDocuments.DocumentEvent", Event)</paragraph>
<paragraph role="pycode" id="pyc_id221622819064967"> # (...)</paragraph>
</pycode>
<tip id="par_id71611090922315">The use of the prefix "<literal>SFDocuments.</literal>" while calling the service is optional.</tip>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id81611339709014">
<bookmark_value>API;Duration</bookmark_value>
<bookmark_value>API;XComponent</bookmark_value>
<bookmark_value>API;ODatabaseDocument</bookmark_value>
</bookmark>
<h2 id="hd_id351582885195476" xml-lang="en-US">Properties</h2>
<table id="tab_id971582885195582">
<tablerow>
<tablecell>
<paragraph id="par_id41582885195836" role="tablehead" xml-lang="en-US">Name</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id31582885195372" role="tablehead" xml-lang="en-US">Readonly</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id31582885195238" role="tablehead" xml-lang="en-US">Type</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id931582885195131" role="tablehead" xml-lang="en-US" >Description</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id7715828856553" role="tablecontent" xml-lang="en-US" localize="false">CustomProperties (*)</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id861582885655779" role="tablecontent" xml-lang="en-US">No</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id271582885655525" role="tablecontent" xml-lang="en-US" localize="false">Dictionary service</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id581582885655885" role="tablecontent" xml-lang="en-US" >Returns a <literal>ScriptForge.Dictionary</literal> object instance. After update, can be passed again to the property for updating the document.<br />Individual items of the dictionary may be either strings, numbers, (Basic) dates or <link href="https://api.libreoffice.org/docs/idl/ref/structcom_1_1sun_1_1star_1_1util_1_1Duration.html" name="Duration API"><literal>com.sun.star.util.Duration</literal></link> items.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id841582886030384" role="tablecontent" xml-lang="en-US" localize="false">Description (*)</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id441582886030118" role="tablecontent" xml-lang="en-US">No</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131582886030297" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id471582886030489" role="tablecontent" xml-lang="en-US" >Gives access to the Description property of the document (also known as "Comments")</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id231582886791351" role="tablecontent" xml-lang="en-US" localize="false">DocumentProperties (*)</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id971582886791838" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id271582886791111" role="tablecontent" xml-lang="en-US" localize="false">Dictionary service</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id16158288679167" role="tablecontent" xml-lang="en-US" >Returns a <literal>ScriptForge.Dictionary</literal> object containing all the entries. Document statistics are included. Note that they are specific to the type of document. As an example, a Calc document includes a "CellCount" entry. Other documents do not.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id881589194571813" role="tablecontent" xml-lang="en-US" localize="false">DocumentType</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id201589194571955" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id951589194571781" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id941589194571801" role="tablecontent" xml-lang="en-US" >String value with the document type ("Base", "Calc", "Writer", etc)</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id241589194633142" role="tablecontent" xml-lang="en-US" localize="false">IsBase<br />IsCalc<br />IsDraw<br />IsImpress<br />IsMath<br />IsWriter</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id761589194633950" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id741589194633956" role="tablecontent" xml-lang="en-US" localize="false">Boolean</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id611589194633853" role="tablecontent" xml-lang="en-US" >Exactly one of these properties is <literal>True</literal> for a given document.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id311589194910727" role="tablecontent" xml-lang="en-US" localize="false">Keywords (*)</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id231589194910179" role="tablecontent" xml-lang="en-US">No</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id421589194910942" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id311589194910190" role="tablecontent" xml-lang="en-US">Gives access to the Keywords property of the document. Represented as a comma-separated list of keywords</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id911589638614922" role="tablecontent" xml-lang="en-US" localize="false">Readonly (*)</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id921589638614972" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id501589638614132" role="tablecontent" xml-lang="en-US" localize="false">Boolean</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id801589638614518" role="tablecontent" xml-lang="en-US"><literal>True</literal> if the document is actually in read-only mode</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id921589195028191" role="tablecontent" xml-lang="en-US" localize="false">Subject (*)</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id201589195028733" role="tablecontent" xml-lang="en-US">No</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id551589195028724" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id371589195028843" role="tablecontent" xml-lang="en-US">Gives access to the Subject property of the document.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id521589195028736" role="tablecontent" xml-lang="en-US" localize="false">Title (*)</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id451589195028910" role="tablecontent" xml-lang="en-US">No</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id31589195028773" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id771589195028748" role="tablecontent" xml-lang="en-US">Gives access to the Title property of the document.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id97158288519551" role="tablecontent" xml-lang="en-US" localize="false">XComponent</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id221582885195686" role="tablecontent" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id371582885195525" role="tablecontent" xml-lang="en-US">UNO Object</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id881582885195976" role="tablecontent" xml-lang="en-US" >The UNO object <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1lang_1_1XComponent.html" name="XComponent API"><literal>com.sun.star.lang.XComponent</literal></link> or <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1sdb_1_1OfficeDatabaseDocument.html" name="ODatabaseDocument API"><literal>com.sun.star.comp.dba.ODatabaseDocument</literal></link> representing the document</paragraph>
</tablecell>
</tablerow>
</table>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<paragraph role="paragraph" id="par_id861611146581334">The example below prints all the properties of a document. Note that the <literal>oDoc</literal> object returned by the <literal>UI.OpenDocument</literal> method is a <literal>SFDocuments.Document</literal> object.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id391611146834072">Dim ui as Variant : Set ui = CreateScriptService("UI")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id471611146957794">Dim oDoc as Object</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id311611146962193">Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id711611146962784">Dim propDict as Object</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id391611146963409">Set propDict = oDoc.DocumentProperties</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id621611146963920">Dim keys as Variant : propKeys = propDict.Keys</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id21611146964465">Dim k as String, strProp as String</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id681611146965001">For Each k In propKeys</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id191611146965538"> strProp = strProp & k & ": " & propDict.Item(k) & CHR$(10)</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id741611146966256">Next k</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id911611146967874">MsgBox strProp</paragraph>
<paragraph role="bascode" localize="false" id="bas_id681611147290092">oDoc.CloseDocument()</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<paragraph role="paragraph" id="par_id571622826920742">To access document properties in a Python script the user needs to directly access them using their names, as shown below:</paragraph>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id391622827274657">doc = ui.GetDocument(r"C:\Documents\MyFile.ods")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id261622827328471">msg = doc.Title + '\n' + doc.Description + '\n' + doc.Keywords</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id41622827328938">bas = CreateScriptService("Basic")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id71622827329510">bas.MsgBox(msg)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id71622827327225">doc.CloseDocument()</paragraph>
</pycode>
<table id="tab_id901611086279902">
<tablerow>
<tablecell colspan="3"><paragraph id="par_id651606319520519" role="tablehead">List of Methods in the Document Service</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id761611086279902" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_document.xhp#Activate" name="Activate method">Activate</link><br/>
<link href="text/sbasic/shared/03/sf_document.xhp#CloseDocument" name="CloseDocument method">CloseDocument</link><br/>
<link href="text/sbasic/shared/03/sf_document.xhp#Forms" name="Forms method">Forms</link>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id141611086279902" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_document.xhp#RunCommand" name="RunCommand method">RunCommand</link><br/>
<link href="text/sbasic/shared/03/sf_document.xhp#Save" name="Save method">Save</link><br/><br/>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id761611086279903" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_document.xhp#SaveAs" name="SaveAs method">SaveAs</link><br/>
<link href="text/sbasic/shared/03/sf_document.xhp#SaveCopyAs" name="SaveCopyAs">SaveCopyAs</link><br/><br/>
</paragraph>
</tablecell>
</tablerow>
</table>
<section id="Activate">
<comment> Activate -------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883">
<bookmark_value>Document service;Activate</bookmark_value>
</bookmark>
<h2 id="hd_id201589199698251" localize="false">Activate</h2>
<paragraph role="paragraph" id="par_id93158919969864">Returns <literal>True</literal> if the document could be activated. Otherwise, there is no change in the actual user interface. It is equivalent to the <literal>Activate</literal> method of the <literal>UI</literal> service.</paragraph>
<paragraph role="paragraph" id="par_id421611148353046">This method is useful when one needs to give focus for a document that is minimized or hidden.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id181622827609276">
<input>svc.Activate(): bool</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph role="paragraph" id="par_id601611148017930">The example below considers that the file "My_File.ods" is already open but not active.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id41158919969836">Dim oDoc As Object</paragraph>
<paragraph role="bascode" localize="false" id="bas_id881611147617212">Set oDoc = CreateScriptService("Document", "MyFile.ods")</paragraph>
<paragraph role="bascode" localize="false" id="pyc_id571611147618913">oDoc.Activate()</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id411622827715523">doc = CreateScriptService("Document", "MyFile.ods")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id171622827715836">doc.Activate()</paragraph>
</pycode>
<tip id="par_id601611148080503">Keep in mind that you can invoke the <literal>Document</literal> service by passing to <literal>CreateScriptService</literal> either "Document" or "SFDocuments.Document"</tip>
</section>
<section id="CloseDocument">
<comment> CloseDocument ---------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721589200121249">
<bookmark_value>Document service;CloseDocument</bookmark_value>
</bookmark>
<h2 id="hd_id261589200121415" localize="false">CloseDocument</h2>
<paragraph role="paragraph" id="par_id651589200121138">Closes the document. If the document is already closed, regardless of how the document was closed, this method has no effect and returns <literal>False</literal>.</paragraph>
<paragraph role="paragraph" id="par_id341611149562894">The method will also return <literal>False</literal> if the user declines to close it.</paragraph>
<paragraph role="paragraph" id="par_id981611149616934">Returns <literal>True</literal> if the document was successfully closed.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id1001622827822169">
<input>svc.CloseDocument(saveask: bool = True): bool</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id361589200121646"><emph>saveask</emph> : If <literal>True</literal> (default), the user is invited to confirm if the changes should be written on disk. This argument is ignored if the document was not modified.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id891589200121516">If oDoc.CloseDocument(True) Then</paragraph>
<paragraph role="bascode" localize="false" id="bas_id51589200506125"> ' ...</paragraph>
<paragraph role="bascode" id="bas_id751622827903730">End If</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id731622827946898">if doc.CloseDocument(True):</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id221622827947414"> # ...</paragraph>
</pycode>
</section>
<section id="Forms">
<comment> Forms --------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721589200121336">
<bookmark_value>Document service;Forms</bookmark_value>
</bookmark>
<h2 id="hd_id261589200120884" localize="false">Forms</h2>
<paragraph role="paragraph" id="par_id501623063693649">Depending on the parameters provided this method will return:</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id611623063742045" role="listitem">A zero-based Array (or a tuple in Python) with the names of all the forms contained in the document (if the <literal>form</literal> argument is absent)</paragraph>
</listitem>
<listitem>
<paragraph id="par_id641623063744536" role="listitem">A <literal>SFDocuments.Form</literal> service instance representing the form specified as argument.</paragraph>
</listitem>
</list>
<note id="par_id821623076570573">This method is applicable only for Writer documents. Calc and Base documents have their own <literal>Forms</literal> method in the <link href="text/sbasic/shared/03/sf_calc.xhp#Forms" name="Calc_Forms">Calc</link> and <link href="text/sbasic/shared/03/sf_base.xhp#Forms" name="Base_Forms">Base</link> services, respectively.</note>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id371623063588699">
<input>svc.Forms(): str[0..*]</input>
</paragraph>
<paragraph role="paragraph" localize="false" id="par_id471623151738791">
<input>svc.Forms(form: str = ''): svc</input>
</paragraph>
<paragraph role="paragraph" localize="false" id="par_id751623151751397">
<input>svc.Forms(form: int): svc</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id451623063459286"><emph>form</emph>: The name or index corresponding to a form stored in the document. If this argument is absent, the method will return a list with the names of all forms available in the document.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph role="paragraph" id="par_id251623063305557">In the following examples, the first line gets the names of all forms in the document and the second line retrieves the <literal>Form</literal> object of the form named "Form_A".</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" id="bas_id191623063399519">Set FormNames = oDoc.Forms()</paragraph>
<paragraph role="bascode" id="bas_id691623063399711">Set FormA = oDoc.Forms("Form_A")</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" id="pyc_id271623063215023">form_names = doc.Forms()</paragraph>
<paragraph role="pycode" id="pyc_id961623063234990">form_A = doc.Forms("Form_A")</paragraph>
</pycode>
</section>
<section id="RunCommand">
<comment> RunCommand --------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id601589202413561">
<bookmark_value>Document service;RunCommand</bookmark_value>
</bookmark>
<h2 id="hd_id611589202413141" localize="false">RunCommand</h2>
<paragraph role="paragraph" id="par_id991589202413257">Runs a command on a document. The command is executed without arguments.</paragraph>
<paragraph role="paragraph" id="par_id921611152932311">A few typical commands are: Save, SaveAs, ExportToPDF, SetDocumentProperties, Undo, Copy, Paste, etc.</paragraph>
<paragraph role="paragraph" id="par_id261589202778896" xml-lang="en-US">The document itself does not need to be active to be able to run commands.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id521622828226683">
<input>svc.RunCommand(command: str)</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id401589202413575"><emph>command</emph>: Case-sensitive string containing the command in English. The command itself is not checked for correctness. If nothing happens after the command call, then the command is probably wrong.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph role="paragraph" id="par_id721611153068137">The following example runs the "SelectData" command in a Calc sheet named "MyFile.ods", which will result in the selection of the data area based on the currently selected cell.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id401611153339973">Set oDoc = CreateScriptService("Document", "MyFile.ods")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id121589202413630">oDoc.RunCommand("SelectData")</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id821622828361025">doc = CreateScriptService("Document", "MyFile.ods")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id211622828361293">doc.RunCommand("SelectData")</paragraph>
</pycode>
<paragraph role="paragraph" id="par_id751611153375195">The example above actually runs the UNO command <literal>uno:SelectData</literal>. Hence, to use the <literal>RunCommand</literal> method it is necessary to remove the "uno:" substring.</paragraph>
<tip id="par_id191611153511038">Each LibreOffice component has its own set of commands available. One easy way to learn commands is going to <emph>Tools > Customize > Keyboard</emph>. When you position your mouse over a function in the <emph>Function</emph> list, a tooltip will appear with the corresponding UNO command.</tip>
</section>
<section id="Save">
<comment> Save ------------------------------------------------------------------------ </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id691589202925124">
<bookmark_value>Document service;Save</bookmark_value>
</bookmark>
<h2 id="hd_id3615892029256" localize="false">Save</h2>
<paragraph role="paragraph" id="par_id81589202925519">Stores the document to the file location from which it was loaded. The method is ignored if the document was not modified.</paragraph>
<paragraph role="paragraph" id="par_id731611153918907">Returns <literal>False</literal> if the document could not be saved. An error is raised if the file is open as read-only, or if it is a new file that has not been saved yet.</paragraph>
<paragraph role="paragraph" id="par_id211589203690937" xml-lang="en-US">The document itself does not need to be active to run this method.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id711622828457342">
<input>svc.Save(): bool</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id31589202925376">If Not oDoc.Save() Then</paragraph>
<paragraph role="bascode" localize="false" id="bas_id821589203188905"> ' ...</paragraph>
<paragraph role="bascode" localize="false" id="bas_id811622828432150">End If</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id981622828541243">if not doc.Save():</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id781622828542374"> # ...</paragraph>
</pycode>
</section>
<section id="SaveAs">
<comment> SaveAs --------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141589203370367">
<bookmark_value>Document service;SaveAs</bookmark_value>
</bookmark>
<h2 id="hd_id161589203370594" localize="false">SaveAs</h2>
<paragraph role="paragraph" id="par_id121589203370778">Stores the document to the given file location. The new location becomes the new file name on which simple Save method calls will be applied.</paragraph>
<paragraph role="paragraph" id="par_id31611154475602">Returns <literal>False</literal> if the document could not be saved. An error is raised when overwriting the destination is rejected or when the destination has its read-only attribute set.</paragraph>
<paragraph role="paragraph" id="par_id391589203370902" xml-lang="en-US">The document itself does not need to be active to run this method.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id561622828596238">
<input>svc.SaveAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id331589203370950"><emph>filename</emph>: A string containing the file name to be used. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph>
<paragraph role="paragraph" id="par_id631589204010142" xml-lang="en-US"><emph>overwrite</emph>: If <literal>True</literal>, the destination file may be overwritten (default = <literal>False</literal>).</paragraph>
<paragraph role="paragraph" id="par_id811589204084107" xml-lang="en-US"><emph>password</emph> (*): A non-space string to protect the document.</paragraph>
<paragraph role="paragraph" id="par_id451589204163772" xml-lang="en-US"><emph>filtername</emph> (*): The name of a filter that should be used for saving the document. If this argument is passed, then the filter must exist.</paragraph>
<paragraph role="paragraph" id="par_id981589204207800" xml-lang="en-US"><emph>filteroptions</emph> (*): An optional string of options associated with the filter.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id81589203370943">oDoc.SaveAs("C:\Documents\NewCopy.odt", overwrite := True)</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id801622828865363">doc.SaveAs(r"C:\Documents\NewCopy.odt", overwrite = True)</paragraph>
</pycode>
</section>
<section id="SaveCopyAs">
<comment> SaveCopyAs ------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71158920514765">
<bookmark_value>Document service;SaveCopyAs</bookmark_value>
</bookmark>
<h2 id="hd_id811589205147824" localize="false">SaveCopyAs</h2>
<paragraph role="paragraph" id="par_id911589205147502">Stores a copy of or export the document to the given file location. The actual location is unchanged.</paragraph>
<paragraph role="paragraph" id="par_id381611154800685">Returns <literal>False</literal> if the document could not be saved. An error is raised when overwriting the destination is rejected or when the destination has its read-only attribute set.</paragraph>
<paragraph role="paragraph" id="par_id11589205147643" xml-lang="en-US">The document itself does not need to be active to run this method.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id561622828596855">
<input>svc.SaveCopyAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id301589205147697"><emph>filename</emph>: A string containing the file name to be used. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph>
<paragraph role="paragraph" id="par_id851589205147348" xml-lang="en-US"><emph>overwrite</emph>: If <literal>True</literal>, the destination file may be overwritten (default = <literal>False</literal>).</paragraph>
<paragraph role="paragraph" id="par_id821589205147330" xml-lang="en-US"><emph>password</emph> (*): A non-space string to protect the document.</paragraph>
<paragraph role="paragraph" id="par_id67158920514729" xml-lang="en-US"><emph>filtername</emph> (*): The name of a filter that should be used for saving the document. If this argument is passed, then the filter must exist.</paragraph>
<paragraph role="paragraph" id="par_id881589205147911" xml-lang="en-US"><emph>filteroptions</emph> (*): An optional string of options associated with the filter.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id431589205147164">oDoc.SaveCopyAs("C:\Documents\Copy2.odt", Overwrite := True)</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id941622829095519">doc.SaveCopyAs(r"C:\Documents\Copy2.odt", overwrite = True)</paragraph>
</pycode>
</section>
<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/>
<section id="relatedtopics">
<embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/>
<embed href="text/sbasic/shared/03/sf_dictionary.xhp#SFDictionary"/>
</section>
</body>
</helpdocument>
|
