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
  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         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     sal_uInt32 GetCount() const
 229                { return aFunctionList.size(); }
 230
 231     const ScFuncDesc* First();
 232
 233     const ScFuncDesc* Next();
 234
 235     const ScFuncDesc* GetFunction( sal_uInt32 nIndex ) const;
 236
 237     sal_Int32 GetMaxFuncNameLen() const
 238                { 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     ScFunctionCategory(ScFunctionMgr* _pMgr,::std::vector<const ScFuncDesc*>* _pCategory,sal_uInt32 _nCategory)
 256             : m_pMgr(_pMgr),m_pCategory(_pCategory),m_nCategory(_nCategory){}
 257     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 position 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 // INCLUDED_SC_INC_FUNCDESC_HXX
 408
 409 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */