sc/inc/funcdesc.hxx

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