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
|
<?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_Services" indexer="include" status="PUBLISH">
<title id="tit" xml-lang="en-US">ScriptForge.Services service</title>
<filename>/text/sbasic/shared/03/sf_services.xhp</filename>
</topic>
</meta>
<body>
<section id="abstract">
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id751582710853363">
<bookmark_value>Services service</bookmark_value>
</bookmark>
<h1 id="hd_id471582710868716" xml-lang="en-US"><variable id="ScriptForgeServices"><link href="text/sbasic/shared/03/sf_services.xhp" name="Services service"><literal>ScriptForge</literal>.<literal>Services</literal> service</link></variable></h1>
<paragraph role="paragraph" xml-lang="en-US" id="par_id351582710868545">
The ScriptForge library is built upon an extensible collection of so-called "Services".
<br />This collection is implemented as categories of Basic libraries or Python modules:
</paragraph>
<list type="ordered" format="a">
<listitem>
<paragraph id="par_id751582711417284" role="listitem" xml-lang="en-US">the standard <literal>ScriptForge</literal> library shipped with %PRODUCTNAME</paragraph>
</listitem>
<listitem>
<paragraph id="par_id711582711434921" role="listitem" xml-lang="en-US">a number of "associated" libraries shipped with %PRODUCTNAME as well</paragraph>
</listitem>
<listitem>
<paragraph id="par_id11582711444725" role="listitem" xml-lang="en-US">any user/contributor LibreOffice extension wanting to fit into the same framework</paragraph>
</listitem>
</list>
</section>
<paragraph role="paragraph" id="par_id211596296017810" xml-lang="en-US">A <emph>service</emph> is a collection of properties or methods which implement the service.</paragraph>
<tip id="par_id301596296901387" xml-lang="en-US">For the author of a user script, a service may be either a <emph>module</emph> within a library, or an <emph>instance</emph> of a class module.</tip>
<paragraph role="paragraph" id="par_id411596296395830" xml-lang="en-US">An <emph>event manager</emph> is a script contained in a library which binds an event triggering a macro - usually defined by the <menuitem>Tools - Customize</menuitem> menu - to the concerned service instance.</paragraph>
<tip id="par_id771596296933669" xml-lang="en-US">As an example, if several documents trigger the same macro when they are loaded, it might be useful to know which document triggered the macro this time. That's where an event manager plays its role.</tip>
<paragraph role="paragraph" id="par_id191582711902530" xml-lang="en-US">The following methods make up the kernel of the <literal>ScriptForge</literal> framework:</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id641582712034899" role="listitem" xml-lang="en-US" localize="false"><emph>RegisterScriptServices</emph></paragraph>
<paragraph role="paragraph" id="par_id351582712098824" xml-lang="en-US">Called internally by <literal>ScriptForge</literal> to register for a library the list of services it implements.
<br />Each library associated to <literal>Scriptforge</literal> or extending it must implement its own <literal>RegisterScriptServices</literal> method.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id961595847982832" role="listitem" xml-lang="en-US" localize="false"><emph>RegisterService</emph></paragraph>
<paragraph role="paragraph" id="par_id671595847982308" xml-lang="en-US">Called - as many times as there are services to register in the library - by <literal>RegisterScriptServices</literal>.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id201596294275926" role="listitem" xml-lang="en-US" localize="false"><emph>RegisterEventManager</emph></paragraph>
<paragraph role="paragraph" id="par_id241596294275434" xml-lang="en-US">Called to register a library event manager by <literal>RegisterScriptServices</literal>.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id281582712132230" role="listitem" xml-lang="en-US" localize="false"><emph>CreateScriptService</emph></paragraph>
<paragraph role="paragraph" id="par_id741582712156448" xml-lang="en-US">Called by user scripts to get an object giving access to the service given as argument.
<br />All services should be invoked thru the <literal>CreateScriptService</literal> method.</paragraph>
</listitem>
</list>
<tip id="par_id651582712806415" xml-lang="en-US">Conventionally, the <literal>String</literal>, <literal>Array</literal> and <literal>Exception</literal> services may be invoked directly respectively as <literal>SF_String</literal>, <literal>SF_Array</literal> and <literal>SF_Exception</literal>.</tip>
<table id="tab_id501611613601554">
<tablerow>
<tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the Services Service</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id891611613601556" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_services.xhp#CreateScriptService" name="CreateScriptService method">CreateScriptService</link>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id541611613601554" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_services.xhp#RegisterScriptServices" name="RegisterScriptServices method">RegisterScriptServices</link><br/>
<link href="text/sbasic/shared/03/sf_services.xhp#RegisterService" name="RegisterService method">RegisterService</link>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id701611613601554" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_services.xhp#RegisterEventManager" name="RegisterEventManager method">RegisterEventManager</link>
</paragraph>
</tablecell>
</tablerow>
</table>
<section id="CreateScriptService">
<comment> CreateScriptService -------------------------------------------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id861582714020042">
<bookmark_value>Services service;CreateScriptService</bookmark_value>
</bookmark>
<h2 id="hd_id751582714020043" localize="false">CreateScriptService</h2>
<paragraph role="paragraph" id="par_id871582714020043">
Gain access to one of the services of a library for the benefit of a user script.
<br /> The returned value is a Basic object or <literal>Nothing</literal> if an error occurred.
</paragraph>
<paragraph role="paragraph" id="par_id101582714266656" xml-lang="en-US">
A service can be understood as either:
</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id531582714337820" role="listitem" xml-lang="en-US">as a set of methods gathered in a Basic standard module</paragraph>
</listitem>
<listitem>
<paragraph id="par_id291582714347134" role="listitem" xml-lang="en-US">or a set of methods and properties gathered in a Basic class module.</paragraph>
</listitem>
</list>
<h3 id="hd_id431582714020044"><embedvar href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id901582714020044">CreateScriptService(Service As String, [arg0, ...] As Variant) As Variant</paragraph>
</bascode>
<h3 id="hd_id251582714020044"><embedvar href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
<paragraph role="paragraph" id="par_id971582714020045"><emph>Service</emph>: The name of the service identified as "library.service".
<br />The library is a Basic library that must exist in the <link href="text/sbasic/shared/03131900.xhp" name="GlobalScope">GlobalScope</link>. The default value is "ScriptForge".
<br />The service is one of the services registered by the library via the <literal>RegisterScriptServices()</literal> method.</paragraph>
<paragraph role="paragraph" id="par_id391582714020045"><emph>arg0, ...</emph>: A list of arguments required by the invoked service.
<br />If the first argument refers to an event manager, then arg0 is mandatory and must be the UNO object representing the event provided as argument to the user macro.</paragraph>
<h3 id="hd_id91582714020046"><embedvar href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id581582898149266">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph>
<paragraph role="bascode" id="bas_id981582898174133">' To be done once</paragraph>
<paragraph role="bascode" localize="false" id="bas_id281582898567582">Dim svc As Object</paragraph>
<paragraph role="bascode" localize="false" id="bas_id571582714020046">Set svc = CreateScriptService("Array")</paragraph>
<paragraph role="bascode" id="bas_id311582715700844">' Refers to the "ScriptForge.Array" service or SF_Array</paragraph>
<paragraph role="bascode" localize="false" id="bas_id671582715735064">Set svc = CreateScriptService("ScriptForge.Dictionary")</paragraph>
<paragraph role="bascode" id="bas_id61582715759468">' Returns a new empty dictionary class instance; "ScriptForge." is optional</paragraph>
<paragraph role="bascode" localize="false" id="bas_id231582715781789">Set svc = CreateScriptService("SFDocuments.Calc")</paragraph>
<paragraph role="bascode" id="bas_id901582715797722">' Refers to the Calc service, implemented in the associated SFDocuments library</paragraph>
<paragraph role="bascode" localize="false" id="bas_id841582715829454">Set svc = CreateScriptService("Timer", True)</paragraph>
<paragraph role="bascode" id="bas_id361582715845747">' Returns a Timer class instance starting immediately</paragraph>
<paragraph role="bascode" localize="false" id="bas_id11596298688112">Set svc = CreateScriptService("SFDocuments.DocumentEvent", oEvent)</paragraph>
<paragraph role="bascode" id="bas_id571596298708062">' Refers to the DocumentEvent service implemented in the associated SFDocuments library</paragraph>
<paragraph role="bascode" id="bas_id121613492254532">' Returns the instance of the Document class that fired the event</paragraph>
</bascode>
</section>
<section id="RegisterScriptServices">
<comment> RegisterScriptServices ------------------------------------------------------------------------------------------------------------------------ </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id221582722979917">
<bookmark_value>Services service;RegisterScriptServices</bookmark_value>
</bookmark>
<h2 id="hd_id11582722979426" localize="false">RegisterScriptServices</h2>
<paragraph role="paragraph" id="par_id1315827229793">
By executing a series of invocations of <literal>RegisterService()</literal> and <literal>RegisterEventManager()</literal>, the <literal>RegisterScriptServices()</literal> method incorporates a library into the <literal>ScriptForge</literal> framework.
<br/>Each library pertaining to the framework must implement its own version of this method.
</paragraph>
<warning id="par_id411582723190195" xml-lang="en-US">The method has to be stored in a <emph>standard</emph> Basic module as opposed to a class module.</warning>
<paragraph role="paragraph" id="par_id351582724127926">A service is either:</paragraph>
<section id="ServiceIdentifier">
<list type="unordered">
<listitem>
<paragraph id="par_id171582722979820" role="listitem" xml-lang="en-US">a Basic standard module passed as a Basic object.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id121582722979649" role="listitem" xml-lang="en-US">or a string designating the function to execute to get an instance of the service. It is in fact the function containing the <literal>New</literal> keyword of a <link href="text/sbasic/shared/03103700.xhp" name="Set statement">Set</link> statement creating the instance.</paragraph>
</listitem>
</list>
<bascode>
<paragraph role="bascode" xml-lang="en-US" id="par_id771582725815107"> GlobalScope.LibraryName.ModuleName ' Object</paragraph>
<paragraph role="bascode" xml-lang="en-US" id="bas_id721582724496873"> "LibraryName.ModuleName.FunctionName" ' String</paragraph>
</bascode>
</section>
<h3 id="hd_id351582722979618"><embedvar href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id761582722979924">Public Sub RegisterScriptServices()</paragraph>
<paragraph role="bascode" localize="false" id="bas_id771582727350871">' To be stored in library = myLibrary</paragraph>
<paragraph role="bascode" localize="false" id="bas_id541582722979219"> With GlobalScope.ScriptForge.SF_Services</paragraph>
<paragraph role="bascode" localize="false" id="bas_id731582725340888"> .RegisterService("myService1", GlobalScope.myLibrary.myModule)</paragraph>
<paragraph role="bascode" id="bas_id11582725353585"> ' Refer to a Basic standard module implementing the service as a set of methods</paragraph>
<paragraph role="bascode" localize="false" id="bas_id451582725361588"> .RegisterService("myService2", "myLibrary.someModule.someFunction")</paragraph>
<paragraph role="bascode" id="bas_id341582725374064"> ' The function should return an instance of a Basic object class implementing the service</paragraph>
<paragraph role="bascode" localize="false" id="bas_id881582725383456"> ' ...</paragraph>
<paragraph role="bascode" localize="false" id="bas_id851582725392009"> End With</paragraph>
<paragraph role="bascode" localize="false" id="bas_id371582725476589">End Sub</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id741582727674249" xml-lang="en-US">When a user script contains a statement such as:</paragraph>
<bascode><paragraph role="bascode" localize="false" id="bas_id301582727687068">Set myServ = CreateScriptService("myLibrary.myService1")</paragraph></bascode>
<paragraph role="paragraph" id="par_id611582727701061" xml-lang="en-US"><br /><literal>ScriptForge</literal> performs these tasks:</paragraph>
<list type="ordered" format="i">
<listitem>
<paragraph id="par_id511582728914523" role="listitem" xml-lang="en-US">load the library <literal>myLibrary</literal> when necessary</paragraph>
</listitem>
<listitem>
<paragraph id="par_id441582728492537" role="listitem" xml-lang="en-US">invoke the <literal>RegisterScriptServices</literal> method to load the list of services of <literal>myLibrary</literal> in memory</paragraph>
</listitem>
<listitem>
<paragraph id="par_id531582728511341" role="listitem" xml-lang="en-US">initialize the variable <literal>myServ</literal> with the given service</paragraph>
</listitem>
</list>
</section>
<section id="RegisterService">
<comment> RegisterService ------------------------------------------------------------------------------------------------------------------------ </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231595857355626">
<bookmark_value>Services service;RegisterService</bookmark_value>
</bookmark>
<h2 id="hd_id501595857355859" localize="false">RegisterService</h2>
<paragraph role="paragraph" id="par_id331595857355789" xml-lang="en-US">
The method returns <literal>True</literal> if the name-value pair given as argument could be registered successfully.
</paragraph>
<h3 id="hd_id701595857355894"><embedvar href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id441595857355915">GlobalScope.ScriptForge.SF_Services.RegisterService(ServiceName As String, ServiceReference As Variant) As Boolean</paragraph>
</bascode>
<h3 id="hd_id1159585735573"><embedvar href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
<paragraph role="paragraph" id="par_id721595857355929"><emph>ServiceName</emph>: The name of the service as a case-insensitive string. The name must be unique.</paragraph>
<paragraph role="paragraph" id="par_id271595857355756" xml-lang="en-US"><emph>ServiceReference</emph>: A service reference is either:</paragraph>
<embed href="text/sbasic/shared/03/sf_services.xhp#ServiceIdentifier"/>
<h3 id="hd_id481595857355966"><embedvar href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id11595857355578"> With GlobalScope.ScriptForge.SF_Services</paragraph>
<paragraph role="bascode" localize="false" id="bas_id571595857355831"> .RegisterService("myService1", GlobalScope.myLibrary.myModule)</paragraph>
<paragraph role="bascode" xml-lang="en-US" id="bas_id101595857355820"> ' Refer to a Basic standard module implementing the service as a set of methods</paragraph>
<paragraph role="bascode" localize="false" id="bas_id771595857355646"> .RegisterService("myService2", "myLibrary.someModule.someFunction")</paragraph>
<paragraph role="bascode" xml-lang="en-US" id="bas_id951595857355198"> ' The function should return an instance of a Basic object class implementing the service</paragraph>
<paragraph role="bascode" localize="false" id="bas_id56159585735558"> ' ...</paragraph>
<paragraph role="bascode" localize="false" id="bas_id461595857355534"> End With</paragraph>
</bascode>
</section>
<section id="RegisterEventManager">
<comment> RegisterEventManager ------------------------------------------------------------------------------------------------------------------------ </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id241596299279341">
<bookmark_value>Services service;RegisterEventManager</bookmark_value>
</bookmark>
<h2 id="hd_id981596299279692" localize="false">RegisterEventManager</h2>
<paragraph role="paragraph" id="par_id701596299279876" xml-lang="en-US">
The method returns <literal>True</literal> if the name-value pair given as argument could be registered successfully.
</paragraph>
<h3 id="hd_id151596299279417"><embedvar href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id201596299279643">GlobalScope.ScriptForge.SF_Services.RegisterEventManager(ServiceName As String, ServiceReference As String) As Boolean</paragraph>
</bascode>
<h3 id="hd_id421596299279275"><embedvar href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
<paragraph role="paragraph" id="par_id331596299279165"><emph>ServiceName</emph>: The name of the service as a case-insensitive string. The name must be unique.</paragraph>
<paragraph role="paragraph" id="par_id92159629927929" xml-lang="en-US"><emph>ServiceReference</emph>: A string designating the function to execute to get an instance of the service. It is in fact the function containing the <literal>New</literal> keyword of a <link href="text/sbasic/shared/03103700.xhp" name="Set statement">Set</link> statement creating the instance.:</paragraph>
<bascode><paragraph role="bascode" localize="false" id="bas_id661596299279598"> "LibraryName.ModuleName.FunctionName" ' String</paragraph></bascode>
<h3 id="hd_id631596299279349"><embedvar href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id89159629927920"> With GlobalScope.ScriptForge.SF_Services</paragraph>
<paragraph role="bascode" localize="false" id="bas_id531596299279547"> .RegisterEventManager("myEventMgr", "myLibrary.someModule.someFunction")</paragraph>
<paragraph role="bascode" id="bas_id521596299279373"> ' The function should return an instance of a Basic object class implementing the service</paragraph>
<paragraph role="bascode" localize="false" id="bas_id641596299279251"> ' ...</paragraph>
<paragraph role="bascode" localize="false" id="bas_id801596299279792"> End With</paragraph>
</bascode>
</section>
<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/>
<section id="relatedtopics">
<embed href="text/sbasic/shared/03103700.xhp#Set_h1"/>
<embed href="text/sbasic/shared/03131900.xhp#GlobalScope_h1"/>
</section>
</body>
</helpdocument>
|
