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 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 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 OUString getFormula(const ::std::vector< 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 OUString getFunctionName() const ;
  96
  97     /**
  98       Returns the help id of the function
  99
 100       @return   help id of the function
 101     */
 102     virtual 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 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 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     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 ;
 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         ParameterFlags() : bOptional(false), bSuppress(false) {}
 197     };
 198
 199
 200
 201     OUString      *pFuncName;              /**< Function name */
 202     OUString      *pFuncDesc;              /**< Description of function */
 203     OUString     **ppDefArgNames;          /**< Parameter name(s) */
 204     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     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     sal_uInt32 GetCount() const
 231                { return aFunctionList.size(); }
 232
 233     const ScFuncDesc* First();
 234
 235     const ScFuncDesc* Next();
 236
 237     const ScFuncDesc* GetFunction( sal_uInt32 nIndex ) const;
 238
 239     xub_StrLen GetMaxFuncNameLen() const
 240                { 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     ScFunctionCategory(ScFunctionMgr* _pMgr,::std::vector<const ScFuncDesc*>* _pCategory,sal_uInt32 _nCategory)
 258             : m_pMgr(_pMgr),m_pCategory(_pCategory),m_nCategory(_nCategory){}
 259     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 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 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 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 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 OUString&) const
 387     */
 388     virtual const formula::IFunctionDescription* getFunctionByName(const 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: */