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