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
|
<?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/.
*
* This file incorporates work covered by the following license notice:
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed
* with this work for additional information regarding copyright
* ownership. The ASF licenses this file to you under the Apache
* License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.apache.org/licenses/LICENSE-2.0 .
-->
<meta>
<topic id="textsbasicshared01040000xml" indexer="include" status="PUBLISH">
<title xml-lang="en-US" id="tit">Document Event-Driven Macros</title>
<filename>/text/sbasic/shared/01040000.xhp</filename>
</topic>
</meta>
<body>
<section id="eventmacros">
<bookmark xml-lang="en-US" branch="index" id="bm_id3154581">
<bookmark_value>deleting; macro assignments to events</bookmark_value>
<bookmark_value>macros; assigning to events</bookmark_value>
<bookmark_value>assigning macros to events</bookmark_value>
<bookmark_value>documents; events</bookmark_value>
<bookmark_value>events; assigning macros</bookmark_value>
<bookmark_value>events; in documents</bookmark_value>
<bookmark_value>API; XDocumentEventListener</bookmark_value>
</bookmark>
<h1 id="hd_id3147348"><link href="text/sbasic/shared/01040000.xhp" name="Event-Driven Macros">Document Event-Driven Macros</link></h1>
<paragraph id="par_id3146120" role="paragraph">This section describes how to assign scripts to application, document or form events.</paragraph>
</section>
<paragraph id="par_id3149263" role="paragraph">You can automatically execute a macro when a specified software event occurs by assigning the desired macro to the event. The following table provides an overview of document events and at what point an assigned macro is executed.</paragraph>
<table id="tbl_id3148646">
<tablerow>
<tablecell><paragraph id="par_id3148455" role="tablehead">Event</paragraph></tablecell>
<tablecell><paragraph id="par_id3145799" role="tablehead">An assigned macro is executed...</paragraph></tablecell>
<tablecell><paragraph id="par_id3145809" role="tablehead">routine</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3149379" role="tablecontent">Start Application</paragraph></tablecell>
<tablecell><paragraph id="par_id3150715" role="tablecontent">...after a $[officename] application is started.</paragraph></tablecell>
<tablecell><paragraph id="par_id721599830885588" role="tablecontent" localize="false"><literal>OnStartApp</literal></paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3146914" role="tablecontent">Close Application</paragraph></tablecell>
<tablecell><paragraph id="par_id3153765" role="tablecontent">...before a $[officename] application is terminated.</paragraph></tablecell>
<tablecell><paragraph id="par_id91599830927709" role="tablecontent" localize="false"><literal>OnCloseApp</literal></paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id151599831705811" role="tablecontent">Document created</paragraph></tablecell>
<tablecell><paragraph id="par_id501599831822339" role="tablecontent">...New document created with <emph>File - New</emph> or with the <emph>New</emph> icon. Note that this event also fires when Basic IDE opens.</paragraph></tablecell>
<tablecell><paragraph id="par_id361599832753891" role="tablecontent" localize="false"><literal>OnCreate</literal></paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3145150" role="tablecontent">New Document</paragraph></tablecell>
<tablecell><paragraph id="par_id3163808" role="tablecontent">...after a new document is created with <emph>File - New</emph> or with the <emph>New</emph> icon.</paragraph></tablecell>
<tablecell><paragraph id="par_id1001599831631397" role="tablecontent" localize="false">OnNew</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id161599836960401" role="tablecontent">Document loading finished</paragraph></tablecell>
<tablecell><paragraph id="par_id721599836993145" role="tablecontent">...before a document is opened with <emph>File - Open</emph> or with the <emph>Open</emph> icon.</paragraph></tablecell>
<tablecell><paragraph id="par_id861599836995091" role="tablecontent" localize="false"><literal>OnLoadFinished</literal></paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3145790" role="tablecontent">Open Document</paragraph></tablecell>
<tablecell><paragraph id="par_id3154572" role="tablecontent">...after a document is opened with <emph>File - Open</emph> or with the <emph>Open</emph> icon.</paragraph></tablecell>
<tablecell><paragraph id="par_id561599837106931" role="tablecontent" localize="false">OnLoad</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3159171" role="tablecontent">Document is going to be closed</paragraph></tablecell>
<tablecell><paragraph id="par_id3146868" role="tablecontent">...before a document is closed.</paragraph></tablecell>
<tablecell><paragraph id="par_id991599837325474" role="tablecontent" localize="false">OnPrepareUnload</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3159097" role="tablecontent">Document closed</paragraph></tablecell>
<tablecell><paragraph id="par_id3148606" role="tablecontent">...after a document was closed. Note that the "Save Document" event may also occur when the document is saved before closing.</paragraph></tablecell>
<tablecell><paragraph id="par_id1001599837386243" role="tablecontent" localize="false">OnUnload</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id391600157320922" role="tablecontent">-no UI-</paragraph></tablecell>
<tablecell></tablecell>
<tablecell><paragraph id="par_id81600157323361" role="tablecontent" localize="false">OnLayoutFinished</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id981599837681979" role="tablecontent">View created</paragraph></tablecell>
<tablecell><paragraph id="par_id281599838210270" role="tablecontent">Document is displayed. Note that this event also happens when a document is duplicated.</paragraph></tablecell>
<tablecell><paragraph id="par_id221599838211428" role="tablecontent" localize="false">OnViewCreated</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id511599837683562" role="tablecontent">View is going to be closed</paragraph></tablecell>
<tablecell><paragraph id="par_id331599838046012" role="tablecontent">Document layout is getting removed.</paragraph></tablecell>
<tablecell><paragraph localize="false" id="par_id851599838047612" role="tablecontent">OnPrepareViewClosing</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id951599837684882" role="tablecontent">View closed</paragraph></tablecell>
<tablecell><paragraph id="par_id51599837816122" role="tablecontent">Document layout is cleared prior to the document closure.</paragraph></tablecell>
<tablecell><paragraph id="par_id131599837818052" role="tablecontent" localize="false">OnViewClosed</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3144772" role="tablecontent">Activate Document</paragraph></tablecell>
<tablecell><paragraph id="par_id3149442" role="tablecontent">...after a document is brought to the foreground.</paragraph></tablecell>
<tablecell><paragraph id="par_id401599838521395" role="tablecontent" localize="false">OnFocus</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3150888" role="tablecontent">Deactivate Document</paragraph></tablecell>
<tablecell><paragraph id="par_id3154060" role="tablecontent">...after another document is brought to the foreground.</paragraph></tablecell>
<tablecell><paragraph id="par_id311599838560117" role="tablecontent" localize="false">OnUnfocus</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3150519" role="tablecontent">Save Document</paragraph></tablecell>
<tablecell><paragraph id="par_id3155529" role="tablecontent">...before a document is saved with <emph>File - Save</emph> or the <emph>Save</emph> icon, provided that a document name has already been specified.</paragraph></tablecell>
<tablecell><paragraph id="par_id541599838897948" role="tablecontent" localize="false">OnSaveAs</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3149404" role="tablecontent">Document has been saved</paragraph></tablecell>
<tablecell><paragraph id="par_id3151332" role="tablecontent">...after a document is saved with <emph>File - Save</emph> or the <emph>Save</emph> icon, provided that a document name has already been specified.</paragraph></tablecell>
<tablecell><paragraph id="par_id931599838938268" role="tablecontent" localize="false">OnSaveDone</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id161599838976700" role="tablecontent">Saving of document failed</paragraph></tablecell>
<tablecell><paragraph id="par_id391599838979652" role="tablecontent">Document could not be saved.</paragraph></tablecell>
<tablecell><paragraph id="par_id21599838980580" role="tablecontent" localize="false">OnSaveFailed</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3153266" role="tablecontent">Save Document As</paragraph></tablecell>
<tablecell><paragraph id="par_id3150208" role="tablecontent">...before a document is saved under a specified name (with <emph>File - Save As</emph>, or with <emph>File - Save</emph> or the <emph>Save</emph> icon, if a document name has not yet been specified).</paragraph></tablecell>
<tablecell><paragraph id="par_id11599840125398" role="tablecontent" localize="false">OnSaveAs</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3158215" role="tablecontent">Document has been saved as</paragraph></tablecell>
<tablecell><paragraph id="par_id3150980" role="tablecontent">... after a document was saved under a specified name (with <emph>File - Save As</emph>, or with <emph>File - Save</emph> or with the <emph>Save</emph> icon, if a document name has not yet been specified).</paragraph></tablecell>
<tablecell><paragraph id="par_id811599840174261" role="tablecontent" localize="false">OnSaveAsDone</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id561599839702598" role="tablecontent">'Save As' has failed</paragraph></tablecell>
<tablecell><paragraph id="par_id951599840240048" role="tablecontent">Document could not be saved.</paragraph></tablecell>
<tablecell><paragraph id="par_id131599840241061" role="tablecontent" localize="false">OnSaveAsFailed</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id851599839190548" role="tablecontent">-no UI-</paragraph></tablecell>
<tablecell><paragraph id="par_id961599839198859" role="tablecontent">When the document disk location has changed, for example after a <emph>File - Save As</emph> action.</paragraph></tablecell>
<tablecell><paragraph id="par_id651599839199901" role="tablecontent" localize="false">OnStorageChanged</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id501600150804809" role="tablecontent">Storing or exporting copy of document</paragraph></tablecell>
<tablecell><paragraph id="par_id471610080505705" role="tablecontent">...before a document is saved with <menuitem>File - Save a Copy</menuitem>, <menuitem>File - Export</menuitem>, <menuitem>File - Export as PDF</menuitem> or the <menuitem>Save</menuitem> icons.</paragraph></tablecell>
<tablecell><paragraph id="par_id781617239899601" role="tablecontent" localize="false">OnCopyTo</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id502600180504809" role="tablecontent">Document copy has been created</paragraph></tablecell>
<tablecell><paragraph id="par_id471601180505705" role="tablecontent">...after a document is saved with <menuitem>File - Save a Copy</menuitem>, <menuitem>File - Export</menuitem>, <menuitem>File - Export as PDF</menuitem> or the <menuitem>Save</menuitem> icons.</paragraph></tablecell>
<tablecell><paragraph id="par_id781614179899601" role="tablecontent" localize="false">OnCopyToDone</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id501006180504809" role="tablecontent">Creating of document copy failed</paragraph></tablecell>
<tablecell><paragraph id="par_id471600081505705" role="tablecontent">Document could not be copied or exported.</paragraph></tablecell>
<tablecell><paragraph id="par_id781613179998601" role="tablecontent" localize="false">OnCopyToFailed</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id501600180504809" role="tablecontent">Print document</paragraph></tablecell>
<tablecell><paragraph id="par_id471600180505705" role="tablecontent">...after the Print dialog is closed, but before the actual print process begins. This event occurs for each copy printed.</paragraph></tablecell>
<tablecell><paragraph id="par_id781613179899601" role="tablecontent" localize="false">OnPrint</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id371600180345993" role="tablecontent">-no UI-</paragraph></tablecell>
<tablecell><paragraph id="par_id851600180346872" role="tablecontent">...after document security settings have changed.</paragraph></tablecell>
<tablecell><paragraph id="par_id785600179899601" role="tablecontent" localize="false">OnModeChanged</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id921600180238854" role="tablecontent">'Modified' status was changed</paragraph></tablecell>
<tablecell><paragraph id="par_id321600180239944" role="tablecontent">Modified state of a document has changed.</paragraph></tablecell>
<tablecell><paragraph id="par_id781600179899601" role="tablecontent" localize="false">OnModifyChanged</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id741600180121445" role="tablecontent">Document title changed</paragraph></tablecell>
<tablecell><paragraph id="par_id801600180122852" role="tablecontent">When the document title gets updated.</paragraph></tablecell>
<tablecell><paragraph id="par_id841600179842448" role="tablecontent" localize="false">OnTitleChanged</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id641600180121445" role="tablecontent">Loaded a sub component</paragraph></tablecell>
<tablecell><paragraph id="par_id701600180122852" role="tablecontent">...after a database form has been opened.</paragraph></tablecell>
<tablecell><paragraph id="par_id741600179842448" role="tablecontent" localize="false"><literal>OnSubComponentOpened</literal></paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id641700180131445" role="tablecontent">Closed a sub component</paragraph></tablecell>
<tablecell><paragraph id="par_id701600290122852" role="tablecontent">...after a database form has been closed.</paragraph></tablecell>
<tablecell><paragraph id="par_id751610179842448" role="tablecontent" localize="false"><literal>OnSubComponentClosed</literal></paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id421600097736759" role="tablecontent">Printing of form letters started</paragraph></tablecell>
<tablecell><paragraph id="par_id411600097854273" role="tablecontent">...before printing form letters using <emph>File - Print</emph> or <emph>Tools - Mail Merge Wizard</emph> menus.</paragraph></tablecell>
<tablecell><paragraph id="par_id421600097855346" role="tablecontent" localize="false">OnMailMerge</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id41600097737991" role="tablecontent">Printing of form letters finished</paragraph></tablecell>
<tablecell><paragraph id="par_id451600097862282" role="tablecontent">...after printing of form letters using <emph>File - Print</emph> or <emph>Tools - Mail Merge Wizard</emph> menus.</paragraph></tablecell>
<tablecell><paragraph id="par_id231600097863331" role="tablecontent" localize="false">OnMailMergeFinished</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id641600160655602" role="tablecontent">Printing of form fields started</paragraph></tablecell>
<tablecell><paragraph id="par_id331600160656617" role="tablecontent">...before printing form fields.</paragraph></tablecell>
<tablecell><paragraph id="par_id81600160657657" role="tablecontent" localize="false">OnFieldMerge</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id801600160725659" role="tablecontent">Printing of form fields finished</paragraph></tablecell>
<tablecell><paragraph id="par_id961600160726645" role="tablecontent">...after printing form fields.</paragraph></tablecell>
<tablecell><paragraph id="par_id551600160727188" role="tablecontent" localize="false">OnFieldMergeFinished</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell><paragraph id="par_id3156366" role="tablecontent">Change of the page count</paragraph></tablecell>
<tablecell><paragraph id="par_id3154627" role="tablecontent">When the page count changes.</paragraph></tablecell>
<tablecell><paragraph id="par_id931600098241318" role="tablecontent" localize="false">OnPageCountChanged</paragraph></tablecell>
</tablerow>
</table>
<note id="par_id131600158369191">Most events relate to documents, except <literal>OnStartApp</literal>, <literal>OnCloseApp</literal>, <literal>OnCreate</literal> and <literal>OnLoadFinished</literal> that occur at application level. <literal>OnSubComponentOpened</literal>, and <literal>OnSubComponentClosed</literal> events are fired by database's forms.</note>
<tip id="par_id321600158566782">Writer documents are triggering those specific events: <literal>OnLayoutFinished</literal>, <literal>OnMailMerge</literal>, <literal>OnMailMergeFinished</literal>, <literal>OnFieldMerge</literal>, <literal>OnFieldMergeFinished</literal> and <literal>OnPageCountChanged</literal>.</tip>
<h2 id="hd_id3153299">Assigning a Macro to an Event</h2>
<list type="ordered">
<listitem><paragraph id="par_id3147244" role="listitem">Choose <emph>Tools - Customize</emph> and click the <emph>Events</emph> tab.</paragraph></listitem>
<listitem><paragraph id="par_id3146098" role="listitem">Select whether you want the assignment to be globally valid or just valid in the current document in the <emph>Save In</emph> listbox.</paragraph></listitem>
<listitem><paragraph id="par_id3150431" role="listitem">Select the event from the <emph>Event</emph> list.</paragraph></listitem>
<listitem><paragraph id="par_id3148742" role="listitem">Click <emph>Macro</emph> and select the macro to be assigned to the selected event.</paragraph></listitem>
<listitem><paragraph id="par_id3146321" role="listitem">Click <emph>OK</emph> to assign the macro.</paragraph></listitem>
<listitem><paragraph id="par_id3147414" role="listitem">Click <emph>OK</emph> to close the dialog.</paragraph></listitem>
</list>
<h2 id="hd_id3154581">Removing the Assignment of a Macro to an Event</h2>
<list type="ordered">
<listitem><paragraph id="par_id3146883" role="listitem">Choose <emph>Tools - Customize</emph> and click the <emph>Events</emph> tab.</paragraph></listitem>
<listitem><paragraph id="par_id3155909" role="listitem">Select whether you want to remove a global assignment or an assignment that is just valid in the current document by selecting the option in the <emph>Save In</emph> listbox.</paragraph></listitem>
<listitem><paragraph id="par_id3159129" role="listitem">Select the event that contains the assignment to be removed from the <emph>Event</emph> list.</paragraph></listitem>
<listitem><paragraph id="par_id3149143" role="listitem">Click <emph>Remove</emph>.</paragraph></listitem>
<listitem><paragraph id="par_id3149351" role="listitem">Click <emph>OK</emph> to close the dialog.</paragraph></listitem>
</list>
<section id="relatedtopics">
<paragraph role="paragraph" id="par_id341600162682135">In addition to assigning macros to events, one can <link href="text/sbasic/python/python_document_events.xhp" name="Monitor events">monitor events</link> triggered in %PRODUCTNAME documents.</paragraph>
</section>
</body>
</helpdocument>
|
