Branch data Line data Source code
1 : : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 : : /*************************************************************************
3 : : *
4 : : * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 : : *
6 : : * Copyright 2000, 2010 Oracle and/or its affiliates.
7 : : *
8 : : * OpenOffice.org - a multi-platform office productivity suite
9 : : *
10 : : * This file is part of OpenOffice.org.
11 : : *
12 : : * OpenOffice.org is free software: you can redistribute it and/or modify
13 : : * it under the terms of the GNU Lesser General Public License version 3
14 : : * only, as published by the Free Software Foundation.
15 : : *
16 : : * OpenOffice.org is distributed in the hope that it will be useful,
17 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 : : * GNU Lesser General Public License version 3 for more details
20 : : * (a copy is included in the LICENSE file that accompanied this code).
21 : : *
22 : : * You should have received a copy of the GNU Lesser General Public License
23 : : * version 3 along with OpenOffice.org. If not, see
24 : : * <http://www.openoffice.org/license.html>
25 : : * for a copy of the LGPLv3 License.
26 : : *
27 : : ************************************************************************/
28 : :
29 : : #ifndef SC_FUNCDESC_HXX
30 : : #define SC_FUNCDESC_HXX
31 : :
32 : : /* Function descriptions for function wizard / autopilot */
33 : :
34 : : #include "scfuncs.hrc"
35 : :
36 : : #include <formula/IFunctionDescription.hxx>
37 : : #include <sal/types.h>
38 : : #include <rtl/ustring.hxx>
39 : :
40 : : #define MAX_FUNCCAT 12 /* maximum number of categories for functions */
41 : : #define LRU_MAX 10 /* maximal number of last recently used functions */
42 : :
43 : : class ScFuncDesc;
44 : : class ScFunctionList;
45 : : class ScFunctionCategory;
46 : : class ScFunctionMgr;
47 : :
48 : : /**
49 : : Stores and generates human readable descriptions for spreadsheet-functions,
50 : : e.g.\ functions used in formulas in calc
51 : : */
52 : : class ScFuncDesc : public formula::IFunctionDescription
53 : : {
54 : : public:
55 : : ScFuncDesc();
56 : : virtual ~ScFuncDesc();
57 : :
58 : : /**
59 : : Clears the object
60 : :
61 : : Deletes all objets referenced by the pointers in the class,
62 : : sets pointers to NULL, and all numerical variables to 0
63 : : */
64 : : void Clear();
65 : :
66 : : /**
67 : : Fills a mapping with indexes for non-suppressed arguments
68 : :
69 : : Fills mapping from visible arguments to real arguments, e.g. if of 4
70 : : parameters the second one is suppressed {0,2,3}. For VAR_ARGS
71 : : parameters only one element is added to the end of the sequence.
72 : :
73 : : @param _rArgumens
74 : : Vector, which the indices are written to
75 : : */
76 : : virtual void fillVisibleArgumentMapping(::std::vector<sal_uInt16>& _rArguments) const ;
77 : :
78 : : /**
79 : : Returns the category of the function
80 : :
81 : : @return the category of the function
82 : : */
83 : : virtual const formula::IFunctionCategory* getCategory() const ;
84 : :
85 : : /**
86 : : Returns the description of the function
87 : :
88 : : @return the description of the function, or an empty OUString if there is no description
89 : : */
90 : : virtual ::rtl::OUString getDescription() const ;
91 : :
92 : : /**
93 : : Returns the function signature with parameters from the passed string array.
94 : :
95 : : @return function signature with parameters
96 : : */
97 : : virtual ::rtl::OUString getFormula(const ::std::vector< ::rtl::OUString >& _aArguments) const ;
98 : :
99 : : /**
100 : : Returns the name of the function
101 : :
102 : : @return the name of the function, or an empty OUString if there is no name
103 : : */
104 : : virtual ::rtl::OUString getFunctionName() const ;
105 : :
106 : : /**
107 : : Returns the help id of the function
108 : :
109 : : @return help id of the function
110 : : */
111 : : virtual ::rtl::OString getHelpId() const ;
112 : :
113 : : /**
114 : : Returns number of arguments
115 : :
116 : : @return help id of the function
117 : : */
118 : : virtual sal_uInt32 getParameterCount() const ;
119 : :
120 : : /**
121 : : Returns description of parameter at given position
122 : :
123 : : @param _nPos
124 : : Position of the parameter
125 : :
126 : : @return OUString description of the parameter
127 : : */
128 : : virtual ::rtl::OUString getParameterDescription(sal_uInt32 _nPos) const ;
129 : :
130 : : /**
131 : : Returns name of parameter at given position
132 : :
133 : : @param _nPos
134 : : Position of the parameter
135 : :
136 : : @return OUString name of the parameter
137 : : */
138 : : virtual ::rtl::OUString getParameterName(sal_uInt32 _nPos) const ;
139 : :
140 : : /**
141 : : Returns list of all parameter names
142 : :
143 : : @return OUString containing separated list of all parameter names
144 : : */
145 : : ::rtl::OUString GetParamList() const;
146 : :
147 : : /**
148 : : Returns the full function signature
149 : :
150 : : @return OUString of the form "FUNCTIONNAME( parameter list )"
151 : : */
152 : : virtual ::rtl::OUString getSignature() const ;
153 : :
154 : : /**
155 : : Returns the number of non-suppressed arguments
156 : :
157 : : In case there are variable arguments the number of fixed non-suppressed
158 : : arguments plus VAR_ARGS, same as for nArgCount (variable arguments can't
159 : : be suppressed). The two functions are equal apart from return type and
160 : : name.
161 : :
162 : : @return number of non-suppressed arguments
163 : : */
164 : : sal_uInt16 GetSuppressedArgCount() const;
165 : : virtual xub_StrLen getSuppressedArgumentCount() const ;
166 : :
167 : : /**
168 : : Requests function data from AddInCollection
169 : :
170 : : Logs error message on failure for debugging purposes
171 : : */
172 : : virtual void initArgumentInfo() const;
173 : :
174 : : /**
175 : : Returns true if parameter at given position is optional
176 : :
177 : : @param _nPos
178 : : Position of the parameter
179 : :
180 : : @return true if optional, false if not optional
181 : : */
182 : : virtual bool isParameterOptional(sal_uInt32 _nPos) const ;
183 : :
184 : : /**
185 : : Compares functions by name, respecting special characters
186 : :
187 : : @param a
188 : : pointer to first function descriptor
189 : :
190 : : @param b
191 : : pointer to second function descriptor
192 : :
193 : : @return "(a < b)"
194 : : */
195 : : static bool compareByName(const ScFuncDesc* a, const ScFuncDesc* b);
196 : :
197 : : /**
198 : : Stores whether a parameter is optional or suppressed
199 : : */
200 : : struct ParameterFlags
201 : : {
202 : : bool bOptional :1; /**< Parameter is optional */
203 : : bool bSuppress :1; /**< Suppress parameter in UI because not implemented yet */
204 : :
205 : 3520 : ParameterFlags() : bOptional(false), bSuppress(false) {}
206 : : };
207 : :
208 : :
209 : :
210 : : ::rtl::OUString *pFuncName; /**< Function name */
211 : : ::rtl::OUString *pFuncDesc; /**< Description of function */
212 : : ::rtl::OUString **ppDefArgNames; /**< Parameter name(s) */
213 : : ::rtl::OUString **ppDefArgDescs; /**< Description(s) of parameter(s) */
214 : : ParameterFlags *pDefArgFlags; /**< Flags for each parameter */
215 : : sal_uInt16 nFIndex; /**< Unique function index */
216 : : sal_uInt16 nCategory; /**< Function category */
217 : : sal_uInt16 nArgCount; /**< All parameter count, suppressed and unsuppressed */
218 : : rtl::OString sHelpId; /**< HelpId of function */
219 : : bool bIncomplete :1; /**< Incomplete argument info (set for add-in info from configuration) */
220 : : bool bHasSuppressedArgs :1; /**< Whether there is any suppressed parameter. */
221 : : };
222 : :
223 : : /**
224 : : List of spreadsheet functions.
225 : : Generated by retrieving functions from resources, AddIns and StarOne AddIns,
226 : : and storing these in one linked list. Functions can be retrieved by index and
227 : : by iterating through the list, starting at the First element, and retrieving
228 : : the Next elements one by one.
229 : :
230 : : The length of the longest function name can be retrieved for easier
231 : : processing (i.e printing a function list).
232 : : */
233 : : class ScFunctionList
234 : : {
235 : : public:
236 : : ScFunctionList();
237 : : ~ScFunctionList();
238 : :
239 : 812 : sal_uInt32 GetCount() const
240 : 812 : { return aFunctionList.size(); }
241 : :
242 : : const ScFuncDesc* First();
243 : :
244 : : const ScFuncDesc* Next();
245 : :
246 : : const ScFuncDesc* GetFunction( sal_uInt32 nIndex ) const;
247 : :
248 : 0 : xub_StrLen GetMaxFuncNameLen() const
249 : 0 : { return nMaxFuncNameLen; }
250 : :
251 : : private:
252 : : ::std::vector<const ScFuncDesc*> aFunctionList; /**< List of functions */
253 : : ::std::vector<const ScFuncDesc*>::iterator aFunctionListIter; /**< position in function list */
254 : : xub_StrLen nMaxFuncNameLen; /**< Length of longest function name */
255 : : };
256 : :
257 : : /**
258 : : Category of spreadsheet functions.
259 : :
260 : : Contains the name, index and function manager of a category,
261 : : as well as a list of functions in the category
262 : : */
263 : : class ScFunctionCategory : public formula::IFunctionCategory
264 : : {
265 : : public:
266 : 33 : ScFunctionCategory(ScFunctionMgr* _pMgr,::std::vector<const ScFuncDesc*>* _pCategory,sal_uInt32 _nCategory)
267 : 33 : : m_pMgr(_pMgr),m_pCategory(_pCategory),m_nCategory(_nCategory){}
268 [ # # ]: 0 : virtual ~ScFunctionCategory(){}
269 : :
270 : : /**
271 : : @return count of functions in this category
272 : : */
273 : : virtual sal_uInt32 getCount() const;
274 : : virtual const formula::IFunctionManager* getFunctionManager() const;
275 : :
276 : : /**
277 : : Gives the _nPos'th function in this category.
278 : :
279 : : @param _nPos
280 : : position of function in this category.
281 : :
282 : : @return function at the _nPos postion in this category, null if _nPos out of bounds.
283 : : */
284 : : virtual const formula::IFunctionDescription* getFunction(sal_uInt32 _nPos) const;
285 : :
286 : : /**
287 : : @return index number of this category.
288 : : */
289 : : virtual sal_uInt32 getNumber() const;
290 : : virtual ::rtl::OUString getName() const;
291 : :
292 : : private:
293 : : ScFunctionMgr* m_pMgr; /**< function manager for this category */
294 : : ::std::vector<const ScFuncDesc*>* m_pCategory; /**< list of functions in this category */
295 : : mutable ::rtl::OUString m_sName; /**< name of this category */
296 : : sal_uInt32 m_nCategory; /**< index number of this category */
297 : : };
298 : :
299 : : #define SC_FUNCGROUP_COUNT ID_FUNCTION_GRP_ADDINS
300 : : /**
301 : : Stores spreadsheet functions in categories, including a cumulative ('All') category and makes them accessible.
302 : : */
303 : : class ScFunctionMgr : public formula::IFunctionManager
304 : : {
305 : : public:
306 : : /**
307 : : Retrieves all calc functions, generates cumulative ('All') category, and the categories.
308 : :
309 : : The function lists of the categories are sorted by (case insensitive) function name
310 : : */
311 : : ScFunctionMgr();
312 : : virtual ~ScFunctionMgr();
313 : :
314 : : /**
315 : : Returns name of category.
316 : :
317 : : @param _nCategoryNumber
318 : : index of category
319 : :
320 : : @return name of the category specified by _nCategoryNumber, empty string if _nCategoryNumber out of bounds
321 : : */
322 : : static ::rtl::OUString GetCategoryName(sal_uInt32 _nCategoryNumber );
323 : :
324 : : /**
325 : : Returns function by name.
326 : :
327 : : Searches for a function with the function name rFName, while ignoring case.
328 : :
329 : : @param rFName
330 : : name of the function
331 : :
332 : : @return pointer to function with the name rFName, null if no such function was found.
333 : : */
334 : : const ScFuncDesc* Get( const ::rtl::OUString& rFName ) const;
335 : :
336 : : /**
337 : : Returns function by index.
338 : :
339 : : Searches for a function with the function index nFIndex.
340 : :
341 : : @param nFIndex
342 : : index of the function
343 : :
344 : : @return pointer to function with the index nFIndex, null if no such function was found.
345 : : */
346 : : const ScFuncDesc* Get( sal_uInt16 nFIndex ) const;
347 : :
348 : : /**
349 : : Returns the first function in category nCategory.
350 : :
351 : : Selects nCategory as current category and returns first element of this.
352 : :
353 : : @param nCategory
354 : : index of requested category
355 : :
356 : : @return pointer to first element in current category, null if nCategory out of bounds
357 : : */
358 : : const ScFuncDesc* First( sal_uInt16 nCategory = 0 ) const;
359 : :
360 : : /**
361 : : Returns the next function of the current category.
362 : :
363 : : @return pointer to the next function in current category, null if current category not set.
364 : : */
365 : : const ScFuncDesc* Next() const;
366 : :
367 : : /**
368 : : @return number of categories, not counting the cumulative category ('All')
369 : : */
370 : : virtual sal_uInt32 getCount() const;
371 : :
372 : : /**
373 : : Returns a category.
374 : :
375 : : Creates an IFunctionCategory object from a category specified by nPos.
376 : :
377 : : @param nPos
378 : : the index of the category, note that 0 maps to the first category not the cumulative ('All') category.
379 : :
380 : : @return pointer to an IFunctionCategory object, null if nPos out of bounds.
381 : : */
382 : : virtual const formula::IFunctionCategory* getCategory(sal_uInt32 nPos) const;
383 : :
384 : : /**
385 : : Appends the last recently used functions.
386 : :
387 : : Takes the last recently used functions, but maximal LRU_MAX, and appends them to the given vector _rLastRUFunctions.
388 : :
389 : : @param _rLastRUFunctions
390 : : a vector of pointer to IFunctionDescription, by reference.
391 : : */
392 : : virtual void fillLastRecentlyUsedFunctions(::std::vector< const formula::IFunctionDescription*>& _rLastRUFunctions) const;
393 : :
394 : : /**
395 : : Implemented because of inheritance \see ScFunctionMgr::Get(const ::rtl::OUString&) const
396 : : */
397 : : virtual const formula::IFunctionDescription* getFunctionByName(const ::rtl::OUString& _sFunctionName) const;
398 : :
399 : : /**
400 : : Maps Etoken to character
401 : :
402 : : Used for retrieving characters for parantheses and separators.
403 : :
404 : : @param _eToken
405 : : token for which, the corresponding character is retrieved
406 : :
407 : : @return character
408 : : */
409 : : virtual sal_Unicode getSingleToken(const formula::IFunctionManager::EToken _eToken) const;
410 : :
411 : : private:
412 : : ScFunctionList* pFuncList; /**< list of all calc functions */
413 : : ::std::vector<const ScFuncDesc*>* aCatLists[MAX_FUNCCAT]; /**< array of all categories, 0 is the cumulative ('All') category */
414 : : mutable ::std::vector<const ScFuncDesc*>::iterator pCurCatListIter; /**< position in current category */
415 : : mutable ::std::vector<const ScFuncDesc*>::iterator pCurCatListEnd; /**< end of current category */
416 : : };
417 : :
418 : : #endif // SC_FUNCDESC_HXX
419 : :
420 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
