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 SAL_OVERRIDE ;
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 SAL_OVERRIDE ;
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 OUString getDescription() const SAL_OVERRIDE ;
82 :
83 : /**
84 : Returns the function signature with parameters from the passed string array.
85 :
86 : @return function signature with parameters
87 : */
88 : virtual OUString getFormula(const ::std::vector< OUString >& _aArguments) const SAL_OVERRIDE ;
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 OUString getFunctionName() const SAL_OVERRIDE ;
96 :
97 : /**
98 : Returns the help id of the function
99 :
100 : @return help id of the function
101 : */
102 : virtual OString getHelpId() const SAL_OVERRIDE ;
103 :
104 : /**
105 : Returns number of arguments
106 :
107 : @return help id of the function
108 : */
109 : virtual sal_uInt32 getParameterCount() const SAL_OVERRIDE ;
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 OUString getParameterDescription(sal_uInt32 _nPos) const SAL_OVERRIDE ;
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 OUString getParameterName(sal_uInt32 _nPos) const SAL_OVERRIDE ;
130 :
131 : /**
132 : Returns list of all parameter names
133 :
134 : @return OUString containing separated list of all parameter names
135 : */
136 : OUString GetParamList() const;
137 :
138 : /**
139 : Returns the full function signature
140 :
141 : @return OUString of the form "FUNCTIONNAME( parameter list )"
142 : */
143 : virtual OUString getSignature() const SAL_OVERRIDE ;
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 sal_Int32 getSuppressedArgumentCount() const SAL_OVERRIDE ;
157 :
158 : /**
159 : Requests function data from AddInCollection
160 :
161 : Logs error message on failure for debugging purposes
162 : */
163 : virtual void initArgumentInfo() const SAL_OVERRIDE;
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 SAL_OVERRIDE ;
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 0 : ParameterFlags() : bOptional(false), bSuppress(false) {}
197 : };
198 :
199 : OUString *pFuncName; /**< Function name */
200 : OUString *pFuncDesc; /**< Description of function */
201 : std::vector<OUString> maDefArgNames; /**< Parameter name(s) */
202 : std::vector<OUString> maDefArgDescs; /**< Description(s) of parameter(s) */
203 : ParameterFlags *pDefArgFlags; /**< Flags for each parameter */
204 : sal_uInt16 nFIndex; /**< Unique function index */
205 : sal_uInt16 nCategory; /**< Function category */
206 : sal_uInt16 nArgCount; /**< All parameter count, suppressed and unsuppressed */
207 : OString sHelpId; /**< HelpId of function */
208 : bool bIncomplete :1; /**< Incomplete argument info (set for add-in info from configuration) */
209 : bool bHasSuppressedArgs :1; /**< Whether there is any suppressed parameter. */
210 : };
211 :
212 : /**
213 : List of spreadsheet functions.
214 : Generated by retrieving functions from resources, AddIns and StarOne AddIns,
215 : and storing these in one linked list. Functions can be retrieved by index and
216 : by iterating through the list, starting at the First element, and retrieving
217 : the Next elements one by one.
218 :
219 : The length of the longest function name can be retrieved for easier
220 : processing (i.e printing a function list).
221 : */
222 : class ScFunctionList
223 : {
224 : public:
225 : ScFunctionList();
226 : ~ScFunctionList();
227 :
228 0 : sal_uInt32 GetCount() const
229 0 : { return aFunctionList.size(); }
230 :
231 : const ScFuncDesc* First();
232 :
233 : const ScFuncDesc* Next();
234 :
235 : const ScFuncDesc* GetFunction( sal_uInt32 nIndex ) const;
236 :
237 0 : sal_Int32 GetMaxFuncNameLen() const
238 0 : { return nMaxFuncNameLen; }
239 :
240 : private:
241 : ::std::vector<const ScFuncDesc*> aFunctionList; /**< List of functions */
242 : ::std::vector<const ScFuncDesc*>::iterator aFunctionListIter; /**< position in function list */
243 : sal_Int32 nMaxFuncNameLen; /**< Length of longest function name */
244 : };
245 :
246 : /**
247 : Category of spreadsheet functions.
248 :
249 : Contains the name, index and function manager of a category,
250 : as well as a list of functions in the category
251 : */
252 : class ScFunctionCategory : public formula::IFunctionCategory
253 : {
254 : public:
255 0 : ScFunctionCategory(ScFunctionMgr* _pMgr,::std::vector<const ScFuncDesc*>* _pCategory,sal_uInt32 _nCategory)
256 0 : : m_pMgr(_pMgr),m_pCategory(_pCategory),m_nCategory(_nCategory){}
257 0 : virtual ~ScFunctionCategory(){}
258 :
259 : /**
260 : @return count of functions in this category
261 : */
262 : virtual sal_uInt32 getCount() const SAL_OVERRIDE;
263 : virtual const formula::IFunctionManager* getFunctionManager() const SAL_OVERRIDE;
264 :
265 : /**
266 : Gives the _nPos'th function in this category.
267 :
268 : @param _nPos
269 : position of function in this category.
270 :
271 : @return function at the _nPos postion in this category, null if _nPos out of bounds.
272 : */
273 : virtual const formula::IFunctionDescription* getFunction(sal_uInt32 _nPos) const SAL_OVERRIDE;
274 :
275 : /**
276 : @return index number of this category.
277 : */
278 : virtual sal_uInt32 getNumber() const SAL_OVERRIDE;
279 : virtual OUString getName() const SAL_OVERRIDE;
280 :
281 : private:
282 : ScFunctionMgr* m_pMgr; /**< function manager for this category */
283 : ::std::vector<const ScFuncDesc*>* m_pCategory; /**< list of functions in this category */
284 : mutable OUString m_sName; /**< name of this category */
285 : sal_uInt32 m_nCategory; /**< index number of this category */
286 : };
287 :
288 : #define SC_FUNCGROUP_COUNT ID_FUNCTION_GRP_ADDINS
289 : /**
290 : Stores spreadsheet functions in categories, including a cumulative ('All') category and makes them accessible.
291 : */
292 : class ScFunctionMgr : public formula::IFunctionManager
293 : {
294 : public:
295 : /**
296 : Retrieves all calc functions, generates cumulative ('All') category, and the categories.
297 :
298 : The function lists of the categories are sorted by (case insensitive) function name
299 : */
300 : ScFunctionMgr();
301 : virtual ~ScFunctionMgr();
302 :
303 : /**
304 : Returns name of category.
305 :
306 : @param _nCategoryNumber
307 : index of category
308 :
309 : @return name of the category specified by _nCategoryNumber, empty string if _nCategoryNumber out of bounds
310 : */
311 : static OUString GetCategoryName(sal_uInt32 _nCategoryNumber );
312 :
313 : /**
314 : Returns function by name.
315 :
316 : Searches for a function with the function name rFName, while ignoring case.
317 :
318 : @param rFName
319 : name of the function
320 :
321 : @return pointer to function with the name rFName, null if no such function was found.
322 : */
323 : const ScFuncDesc* Get( const OUString& rFName ) const;
324 :
325 : /**
326 : Returns function by index.
327 :
328 : Searches for a function with the function index nFIndex.
329 :
330 : @param nFIndex
331 : index of the function
332 :
333 : @return pointer to function with the index nFIndex, null if no such function was found.
334 : */
335 : const ScFuncDesc* Get( sal_uInt16 nFIndex ) const;
336 :
337 : /**
338 : Returns the first function in category nCategory.
339 :
340 : Selects nCategory as current category and returns first element of this.
341 :
342 : @param nCategory
343 : index of requested category
344 :
345 : @return pointer to first element in current category, null if nCategory out of bounds
346 : */
347 : const ScFuncDesc* First( sal_uInt16 nCategory = 0 ) const;
348 :
349 : /**
350 : Returns the next function of the current category.
351 :
352 : @return pointer to the next function in current category, null if current category not set.
353 : */
354 : const ScFuncDesc* Next() const;
355 :
356 : /**
357 : @return number of categories, not counting the cumulative category ('All')
358 : */
359 : virtual sal_uInt32 getCount() const SAL_OVERRIDE;
360 :
361 : /**
362 : Returns a category.
363 :
364 : Creates an IFunctionCategory object from a category specified by nPos.
365 :
366 : @param nPos
367 : the index of the category, note that 0 maps to the first category not the cumulative ('All') category.
368 :
369 : @return pointer to an IFunctionCategory object, null if nPos out of bounds.
370 : */
371 : virtual const formula::IFunctionCategory* getCategory(sal_uInt32 nPos) const SAL_OVERRIDE;
372 :
373 : /**
374 : Appends the last recently used functions.
375 :
376 : Takes the last recently used functions, but maximal LRU_MAX, and appends them to the given vector _rLastRUFunctions.
377 :
378 : @param _rLastRUFunctions
379 : a vector of pointer to IFunctionDescription, by reference.
380 : */
381 : virtual void fillLastRecentlyUsedFunctions(::std::vector< const formula::IFunctionDescription*>& _rLastRUFunctions) const SAL_OVERRIDE;
382 :
383 : /**
384 : Implemented because of inheritance \see ScFunctionMgr::Get(const OUString&) const
385 : */
386 : virtual const formula::IFunctionDescription* getFunctionByName(const OUString& _sFunctionName) const SAL_OVERRIDE;
387 :
388 : /**
389 : Maps Etoken to character
390 :
391 : Used for retrieving characters for parantheses and separators.
392 :
393 : @param _eToken
394 : token for which, the corresponding character is retrieved
395 :
396 : @return character
397 : */
398 : virtual sal_Unicode getSingleToken(const formula::IFunctionManager::EToken _eToken) const SAL_OVERRIDE;
399 :
400 : private:
401 : ScFunctionList* pFuncList; /**< list of all calc functions */
402 : ::std::vector<const ScFuncDesc*>* aCatLists[MAX_FUNCCAT]; /**< array of all categories, 0 is the cumulative ('All') category */
403 : mutable ::std::vector<const ScFuncDesc*>::iterator pCurCatListIter; /**< position in current category */
404 : mutable ::std::vector<const ScFuncDesc*>::iterator pCurCatListEnd; /**< end of current category */
405 : };
406 :
407 : #endif // SC_FUNCDESC_HXX
408 :
409 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
