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_sheet_XFormulaOpCodeMapper_idl__
25#define __com_sun_star_sheet_XFormulaOpCodeMapper_idl__
26
27#ifndef __com_sun_star_sheet_FormulaOpCodeMapEntry_idl__
28#include <com/sun/star/sheet/FormulaOpCodeMapEntry.idl>
29#endif
30
31#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
32#include <com/sun/star/lang/IllegalArgumentException.idl>
33#endif
34
35//=============================================================================
36
37module com {  module sun {  module star {  module sheet {
38
39//=============================================================================
40
41/** gives access to spreadsheet compiler token interns.
42 */
43published interface XFormulaOpCodeMapper
44{
45    //-------------------------------------------------------------------------
46
47    /** OpCode value used for external Add-In functions.
48
49        <p>Needed to be able to identify which of the function names map to an
50        Add-In implementation where this OpCode is used in the returned
51        mapping and the programmatical name is available as additional
52        information.</p>
53     */
54    [attribute, readonly] long OpCodeExternal;
55
56    //-------------------------------------------------------------------------
57
58    /** OpCode value used for unknown functions.
59
60        <p>Used to identify which of the function names queried with
61        <member>getMappings</member> are unknown to the implementation.</p>
62     */
63    [attribute, readonly] long OpCodeUnknown;
64
65    //-------------------------------------------------------------------------
66
67    /** returns a sequence of tokens matching the input sequence of
68        strings in order.
69
70        @param Names
71            Sequence of names to be mapped. These can be function names,
72            operators, separators and other symbols the formula compiler
73            knows.
74
75        @param Language
76            Formula language to be used, one of <type>FormulaLanguage</type>
77            constants. If a constant unknown to the implementation is passed,
78            <type scope="com::sun::star::lang">IllegalArgumentException</type>
79            is thrown.
80
81        @returns
82            a sequence of <type>FormulaToken</type> matching the input
83            sequence in order.
84
85            <p>Each string element in parameter Names according to the formula
86            language in parameter Language is mapped to a <type>FormulaToken
87            </type> containing the internal OpCode used by the spreadsheet
88            application in <member>FormulaToken::OpCode</member> and by
89            contract maybe additional information in <member>
90            FormulaToken::Data</member>.</p>
91
92            <p>The order of the FormulaToken sequence returned matches the
93            input order of the string sequence.</p>
94
95            <p>An unknown Name string gets the OpCode value of <member>
96            OpCodeUnknown</member> assigned.</p>
97
98            <p>Additional information in <member>FormulaToken::Data</member>
99            is returned for:
100            <ul>
101            <li>Add-in names: the programmatical name. The OpCode value used
102            for add-ins can be queried with the <member>OpCodeExternal</member>
103            getter method.</li>
104            </ul></p>
105     */
106    sequence< FormulaToken > getMappings(
107            [in] sequence< string > Names,
108            [in] long Language )
109        raises( com::sun::star::lang::IllegalArgumentException );
110
111    //-------------------------------------------------------------------------
112
113    /** returns a sequence of map entries for all available elements of
114        a given formula language.
115
116        @param Language
117            Formula language to be used, one of <type>FormulaLanguage</type>
118            constants. If a constant unknown to the implementation is passed,
119            <type scope="com::sun::star::lang">IllegalArgumentException</type>
120            is thrown.
121
122        @param Groups
123            Group of mappings to be returned, a bit mask of <type>
124            FormulaMapGroup</type> constants.
125
126        @returns
127            Sequence of <type>FormulaOpCodeMapEntry</type>.
128
129            <p>Each element of the formula language in parameter Language is
130            mapped to a <type>FormulaToken</type> containing the internal
131            OpCode used by the spreadsheet application in <member>
132            FormulaToken::OpCode</member> and by contract maybe additional
133            information in <member>FormulaToken::Data</member>. See <member>
134            getMappings</member> for more details.</p>
135     */
136    sequence< FormulaOpCodeMapEntry > getAvailableMappings(
137            [in] long Language, [in] long Groups )
138        raises( com::sun::star::lang::IllegalArgumentException );
139
140};
141
142//=============================================================================
143
144}; }; }; };
145
146#endif
147
148