1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27
28#ifndef __com_sun_star_sheet_XFormulaOpCodeMapper_idl__
29#define __com_sun_star_sheet_XFormulaOpCodeMapper_idl__
30
31#ifndef __com_sun_star_sheet_FormulaOpCodeMapEntry_idl__
32#include <com/sun/star/sheet/FormulaOpCodeMapEntry.idl>
33#endif
34
35#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
36#include <com/sun/star/lang/IllegalArgumentException.idl>
37#endif
38
39//=============================================================================
40
41module com {  module sun {  module star {  module sheet {
42
43//=============================================================================
44
45/** gives access to spreadsheet compiler token interns.
46 */
47published interface XFormulaOpCodeMapper
48{
49    //-------------------------------------------------------------------------
50
51    /** OpCode value used for external Add-In functions.
52
53        <p>Needed to be able to identify which of the function names map to an
54        Add-In implementation where this OpCode is used in the returned
55        mapping and the programmatical name is available as additional
56        information.</p>
57     */
58    [attribute, readonly] long OpCodeExternal;
59
60    //-------------------------------------------------------------------------
61
62    /** OpCode value used for unknown functions.
63
64        <p>Used to identify which of the function names queried with
65        <member>getMappings</member> are unknown to the implementation.</p>
66     */
67    [attribute, readonly] long OpCodeUnknown;
68
69    //-------------------------------------------------------------------------
70
71    /** returns a sequence of tokens matching the input sequence of
72        strings in order.
73
74        @param Names
75            Sequence of names to be mapped. These can be function names,
76            operators, separators and other symbols the formula compiler
77            knows.
78
79        @param Language
80            Formula language to be used, one of <type>FormulaLanguage</type>
81            constants. If a constant unknown to the implementation is passed,
82            <type scope="com::sun::star::lang">IllegalArgumentException</type>
83            is thrown.
84
85        @returns
86            a sequence of <type>FormulaToken</type> matching the input
87            sequence in order.
88
89            <p>Each string element in parameter Names according to the formula
90            language in parameter Language is mapped to a <type>FormulaToken
91            </type> containing the internal OpCode used by the spreadsheet
92            application in <member>FormulaToken::OpCode</member> and by
93            contract maybe additional information in <member>
94            FormulaToken::Data</member>.</p>
95
96            <p>The order of the FormulaToken sequence returned matches the
97            input order of the string sequence.</p>
98
99            <p>An unknown Name string gets the OpCode value of <member>
100            OpCodeUnknown</member> assigned.</p>
101
102            <p>Additional information in <member>FormulaToken::Data</member>
103            is returned for:
104            <ul>
105            <li>Add-in names: the programmatical name. The OpCode value used
106            for add-ins can be queried with the <member>OpCodeExternal</member>
107            getter method.</li>
108            </ul></p>
109     */
110    sequence< FormulaToken > getMappings(
111            [in] sequence< string > Names,
112            [in] long Language )
113        raises( com::sun::star::lang::IllegalArgumentException );
114
115    //-------------------------------------------------------------------------
116
117    /** returns a sequence of map entries for all available elements of
118        a given formula language.
119
120        @param Language
121            Formula language to be used, one of <type>FormulaLanguage</type>
122            constants. If a constant unknown to the implementation is passed,
123            <type scope="com::sun::star::lang">IllegalArgumentException</type>
124            is thrown.
125
126        @param Groups
127            Group of mappings to be returned, a bit mask of <type>
128            FormulaMapGroup</type> constants.
129
130        @returns
131            Sequence of <type>FormulaOpCodeMapEntry</type>.
132
133            <p>Each element of the formula language in parameter Language is
134            mapped to a <type>FormulaToken</type> containing the internal
135            OpCode used by the spreadsheet application in <member>
136            FormulaToken::OpCode</member> and by contract maybe additional
137            information in <member>FormulaToken::Data</member>. See <member>
138            getMappings</member> for more details.</p>
139     */
140    sequence< FormulaOpCodeMapEntry > getAvailableMappings(
141            [in] long Language, [in] long Groups )
142        raises( com::sun::star::lang::IllegalArgumentException );
143
144};
145
146//=============================================================================
147
148service FormulaOpCodeMapper : XFormulaOpCodeMapper;
149
150//=============================================================================
151
152}; }; }; };
153
154#endif
155
156