1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_smarttags_XSmartTagAction_idl__
25#define __com_sun_star_smarttags_XSmartTagAction_idl__
26
27#ifndef __com_sun_star_container_XStringKeyMap_idl__
28#include <com/sun/star/container/XStringKeyMap.idl>
29#endif
30
31#ifndef __com_sun_star_uno_XInitialization_idl__
32#include <com/sun/star/lang/XInitialization.idl>
33#endif
34
35#ifndef __com_sun_star_lang_Locale_idl__
36#include <com/sun/star/lang/Locale.idl>
37#endif
38
39#ifndef __com_sun_star_text_XTextRange_idl__
40#include <com/sun/star/text/XTextRange.idl>
41#endif
42
43#ifndef __com_sun_star_frame_XController_idl__
44#include <com/sun/star/frame/XController.idl>
45#endif
46
47#ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
48#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
49#endif
50
51#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
52#include <com/sun/star/lang/IllegalArgumentException.idl>
53#endif
54
55//=============================================================================
56
57module com {  module sun {  module star {  module smarttags {
58
59//=============================================================================
60
61/** provides access to smart tag actions.
62
63    @since OpenOffice 2.3
64 */
65
66interface XSmartTagAction: com::sun::star::lang::XInitialization
67{
68    //-------------------------------------------------------------------------
69    /** obtains a name that describes this action component.
70
71        @param aLocale
72                Is used for localization of the name.
73
74        @return
75                the name describing the action component.
76    */
77    string getName( [in] ::com::sun::star::lang::Locale aLocale );
78
79
80    //-------------------------------------------------------------------------
81    /** obtains a detailed description of this action component.
82
83        @param aLocale
84                Is used for localization of the description.
85
86        @return
87                the description of the action component.
88    */
89    string getDescription( [in] ::com::sun::star::lang::Locale aLocale );
90
91
92    //-------------------------------------------------------------------------
93    /** the number of smart tag types supported by this action
94        component.
95    */
96    [attribute, readonly] long SmartTagCount;
97
98
99    //-------------------------------------------------------------------------
100    /** obtains the name of one specific smart tag type supported by
101        this action component.
102
103        @param nSmartTagIndex
104                Index of the wanted smart tag type. Value needs to be
105                between 0 and the number of smarttags available
106                (exclusively).
107
108        @return
109                an unique name of the smart tag type. Smart tag  type
110                names are always in the format of namespaceURI#tagname.
111
112        @throws com::sun::star::lang::IndexOutOfBoundsException
113                if nSmartTagIndex is greater than SmartTagCount.
114    */
115    string getSmartTagName( [in] long nSmartTagIndex)
116        raises( com::sun::star::lang::IndexOutOfBoundsException );
117
118
119    //-------------------------------------------------------------------------
120    /** obtains the caption of the smart tag type for using in user
121        interfaces.
122
123        @param nSmartTagIndex
124                Index of the wanted smart tag type. Value needs to be
125                between 0 and the number of smarttags available
126                (exclusively).
127
128        @param aLocale
129                Is used for localization of the caption.
130
131        @return
132                the caption associated with the smart tag type.
133
134        @throws com::sun::star::lang::IndexOutOfBoundsException
135                if nSmartTagIndex is greater than SmartTagCount
136     */
137    string getSmartTagCaption( [in] long nSmartTagIndex,
138                               [in] ::com::sun::star::lang::Locale aLocale)
139        raises( com::sun::star::lang::IndexOutOfBoundsException );
140
141
142    //-------------------------------------------------------------------------
143    /** obtains the number of actions provided for a specifiy smart tag
144        type.
145
146        @param aSmartTagName
147                Name of the wanted smart tag type. This is one of the
148                names obtained by getSmartTagName()
149
150        @param xController
151                The current controller of the document.
152
153        @return
154                the number of actions available for the given smart tag
155                type.
156    */
157    long getActionCount( [in] string aSmartTagName,
158                         [in] com::sun::star::frame::XController xController,
159                         [in] com::sun::star::container::XStringKeyMap xProperties);
160
161    //-------------------------------------------------------------------------
162    /** obtains a unique integer identifier for an action.
163
164        @param aSmartTagName
165                Name of the wanted smart tag type. This is one of the
166                names obtained by getSmartTagName()
167
168        @param nActionIndex
169                The index of the action for the given smart tag type.
170
171        @param xController
172                The current controller of the document.
173
174        @return
175                the unique integer identifier for the requested action.
176
177        @throws com::sun::star::lang::IllegalArgumentException
178                if the specified nActionIndex is greater than the number
179                of available actions for the specified smart tag type.
180    */
181    long getActionID( [in] string aSmartTagName, [in] long nActionIndex,
182                      [in] com::sun::star::frame::XController xController )
183        raises( com::sun::star::lang::IllegalArgumentException );
184
185
186    //-------------------------------------------------------------------------
187    /** obtains a caption for a specified action for use in user
188        interfaces.
189
190        @param nActionID
191                The identifier of the requested action.
192
193        @param aApplicationName
194                A string containing the name of the calling application.
195
196        @param aLocale
197                Is used for localization of the caption.
198
199        @param xProperties
200                Contains additional smart tag properties collected by
201                the smart tag recognizer.
202
203        @param aText
204                The calling application can pass the text of the smart
205                tag to the action component.
206
207        @param aXML
208                A string that is a XML representation of the smart tag.
209
210        @param xController
211                The current controller of the document.
212
213        @param xTarget
214                A text range representing the smart tag in the document.
215
216        @return
217                the caption of the requested action.
218
219        @throws com::sun::star::lang::IllegalArgumentException
220                if the ActionID is not recognized.
221    */
222    string getActionCaptionFromID( [in] long nActionID,
223                                   [in] string aApplicationName,
224                                   [in] ::com::sun::star::lang::Locale aLocale,
225                                   [in] com::sun::star::container::XStringKeyMap xProperties,
226                                   [in] string aText,
227                                   [in] string aXML,
228                                   [in] com::sun::star::frame::XController xController,
229                                   [in] com::sun::star::text::XTextRange xTarget )
230        raises( com::sun::star::lang::IllegalArgumentException );
231
232
233    //-------------------------------------------------------------------------
234    /** obtains a language independent name of an action.
235
236        @param nActionID
237                The identifier of the requested action.
238
239        @param xController
240                The current controller of the document.
241
242        @return
243                the language independent name of the specified action.
244
245        @throws com::sun::star::lang::IllegalArgumentException
246                if the ActionID is not recognized.
247    */
248    string getActionNameFromID( [in] long nActionID,
249                                [in] com::sun::star::frame::XController xController)
250        raises( com::sun::star::lang::IllegalArgumentException );
251
252
253    //-------------------------------------------------------------------------
254    /** invokes an action.
255
256        @param nActionID
257                The identifier of the requested action.
258
259        @param aApplicationName
260                A string containing the name of the calling application.
261
262        @param xController
263                The current controller of the document.
264
265        @param xTarget
266                A text range representing the smart tag in the document.
267
268        @param xProperties
269                Contains the smart tag properties collected by the smart
270                tag recognizer.
271
272        @param aText
273                The calling application can pass the text of the smart
274                tag to the action component.
275
276        @param aXML
277                A string that is a XML representation of the smart tag.
278
279        @param aLocale
280                Is used for localization of the action.
281
282        @throws com::sun::star::lang::IllegalArgumentException
283                if the ActionID is not recognized.
284    */
285    void invokeAction( [in] long nActionID,
286                       [in] string aApplicationName,
287                       [in] com::sun::star::frame::XController xController,
288                       [in] com::sun::star::text::XTextRange xTarget,
289                       [in] com::sun::star::container::XStringKeyMap xProperties,
290                       [in] string aText,
291                       [in] string aXML,
292                       [in] ::com::sun::star::lang::Locale aLocale )
293        raises( com::sun::star::lang::IllegalArgumentException );
294
295
296    //-------------------------------------------------------------------------
297    /** determines whether a caption is dynamic.
298
299        @param nActionID
300                The identifier of the requested action.
301
302        @param aApplicationName
303                A string containing the name of the calling application.
304
305        @param xController
306                The current controller of the document.
307
308        @param aLocale
309                Is used for localization.
310
311        @return
312                a boolean indicating whether the caption is dynamic.
313
314        @throws com::sun::star::lang::IllegalArgumentException
315                if the ActionID is not recognized.
316    */
317    boolean isCaptionDynamic( [in] long nActionID,
318                              [in] string aApplicationName,
319                              [in] com::sun::star::frame::XController xController,
320                              [in] ::com::sun::star::lang::Locale aLocale )
321        raises( com::sun::star::lang::IllegalArgumentException );
322
323
324    //-------------------------------------------------------------------------
325    /** determines whether the smart tag indicator should be visible.
326
327        @param nActionID
328                The identifier of the requested action.
329
330        @param aApplicationName
331                A string containing the name of the calling application.
332
333        @param xController
334                The current controller of the document.
335
336        @param aLocale
337                Is used for localization.
338
339        @return
340                a boolean indicating whether the smart tag indicator
341                should be visible.
342
343        @throws com::sun::star::lang::IllegalArgumentException
344                if the ActionID is not recognized.
345    */
346    boolean isShowSmartTagIndicator( [in] long nActionID,
347                                     [in] string aApplicationName,
348                                     [in] com::sun::star::frame::XController xController,
349                                     [in] ::com::sun::star::lang::Locale aLocale )
350        raises( com::sun::star::lang::IllegalArgumentException );
351};
352
353}; }; }; };
354
355#endif
356