include/unotools/historyoptions.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 #ifndef INCLUDED_UNOTOOLS_HISTORYOPTIONS_HXX
  20 #define INCLUDED_UNOTOOLS_HISTORYOPTIONS_HXX
  21
  22 #include <unotools/unotoolsdllapi.h>
  23 #include <sal/types.h>
  24 #include <osl/mutex.hxx>
  25 #include <com/sun/star/uno/Sequence.h>
  26 #include <com/sun/star/beans/PropertyValue.hpp>
  27 #include <rtl/ustring.hxx>
  28 #include <unotools/options.hxx>
  29
  30 /*-************************************************************************************************************//**
  31     @descr          The method GetList() returns a list of property values.
  32                     Use follow defines to separate values by names.
  33 *//*-*************************************************************************************************************/
  34
  35 #define HISTORY_PROPERTYNAME_URL            OUString("URL")
  36 #define HISTORY_PROPERTYNAME_FILTER         OUString("Filter")
  37 #define HISTORY_PROPERTYNAME_TITLE          OUString("Title")
  38 #define HISTORY_PROPERTYNAME_PASSWORD       OUString("Password")
  39
  40 /*-************************************************************************************************************//**
  41     @descr          You can use these enum values to specify right history if you call ouer interface methods.
  42 *//*-*************************************************************************************************************/
  43
  44 enum EHistoryType
  45 {
  46     ePICKLIST       = 0,
  47     eHISTORY        = 1,
  48     eHELPBOOKMARKS  = 2
  49 };
  50
  51 /*-************************************************************************************************************//**
  52     @short          forward declaration to our private date container implementation
  53     @descr          We use these class as internal member to support small memory requirements.
  54                     You can create the container if it is neccessary. The class which use these mechanism
  55                     is faster and smaller then a complete implementation!
  56 *//*-*************************************************************************************************************/
  57
  58 class SvtHistoryOptions_Impl;
  59
  60 /*-************************************************************************************************************//**
  61     @short          collect information about history features
  62     @descr          -
  63
  64     @implements     -
  65     @base           -
  66
  67     @devstatus      ready to use
  68 *//*-*************************************************************************************************************/
  69
  70 class UNOTOOLS_DLLPUBLIC SAL_WARN_UNUSED SvtHistoryOptions : public utl::detail::Options
  71 {
  72     public:
  73         /*-****************************************************************************************************//**
  74             @short      standard constructor and destructor
  75             @descr      This will initialize an instance with default values.
  76                         We implement these class with a refcount mechanism! Every instance of this class increase it
  77                         at create and decrease it at delete time - but all instances use the same data container!
  78                         He is implemented as a static member ...
  79
  80             @seealso    member m_nRefCount
  81             @seealso    member m_pDataContainer
  82
  83             @param      -
  84             @return     -
  85
  86             @onerror    -
  87         *//*-*****************************************************************************************************/
  88
  89          SvtHistoryOptions();
  90         virtual ~SvtHistoryOptions();
  91
  92         /*-****************************************************************************************************//**
  93             @short      interface methods to get and set value of config key "org.openoffice.Office.Common/History/..."
  94             @descr      key "PickList"  : The last used documents displayed in the file menu.
  95                         key "History"   : The last opened documents general.
  96         *//*-*****************************************************************************************************/
  97
  98         /*-****************************************************************************************************//**
  99             @short      set/get max size of specified history
 100             @descr      Call this methods to get information about max. size of specified list.
 101                         These value lay down the max count of items in these history. If a new one
 102                         is add to it the oldest one is deleted automaticly!
 103
 104             @seealso    -
 105
 106             @param      "eHistory" select right history.
 107             @param      "nSize" is the new max size of specified list. If new size smaller then the old one
 108                         some oldest entries will be destroyed automaticly!
 109             @return     Current max size of specified list.
 110
 111             @onerror    -
 112         *//*-*****************************************************************************************************/
 113
 114         sal_uInt32  GetSize( EHistoryType eHistory                      ) const ;
 115
 116         /*-****************************************************************************************************//**
 117             @short      clear complete sepcified list
 118             @descr      Call this methods to clear the whole list. After that GetItemCount() will return 0 ...
 119                         but GetSize() will return the old value!
 120
 121             @seealso    -
 122
 123             @param      "eHistory" select right history.
 124             @return     -
 125
 126             @onerror    -
 127         *//*-*****************************************************************************************************/
 128
 129         void Clear( EHistoryType eHistory );
 130
 131         /*-****************************************************************************************************//**
 132             @short      return complete sepcified list
 133             @descr      If you will show the whole list call this method to get it completely.
 134
 135             @seealso    -
 136
 137             @param      "eHistory" select right history.
 138             @return     A list of history items is returned.
 139
 140             @onerror    -
 141         *//*-*****************************************************************************************************/
 142
 143         ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue > > GetList( EHistoryType eHistory ) const ;
 144
 145         /*-****************************************************************************************************//**
 146             @short      append a new item to specified list
 147             @descr      You can append items to a list only - removing isn't allowed for a special item!
 148                         The oldest entry is deleted automaticly if max size arrived or you can call Clear() ...
 149                         It exist two different overload methods to do this.
 150                         One for user which have an complete history item and another one for uncompletly data sets!
 151
 152             @seealso    method SetSize()
 153             @seealso    method Clear()
 154
 155             @param      "eHistory" select right history.
 156             @param      "sURL" URL to save in history
 157             @param      "sFilter" filter name to save in history
 158             @param      "sTitle" document title to save in history
 159             @param      "sPassword" password to save in history
 160             @return     -
 161
 162             @onerror    -
 163         *//*-*****************************************************************************************************/
 164
 165         void AppendItem(            EHistoryType        eHistory    ,
 166                             const   OUString&    sURL        ,
 167                             const   OUString&    sFilter     ,
 168                             const   OUString&    sTitle      ,
 169                             const   OUString&    sPassword   );
 170
 171     private:
 172
 173         /*-****************************************************************************************************//**
 174             @short      return a reference to a static mutex
 175             @descr      Make these class threadsafe.
 176
 177             @seealso    -
 178
 179             @param      -
 180             @return     A reference to a static mutex member.
 181
 182             @onerror    -
 183         *//*-*****************************************************************************************************/
 184
 185         UNOTOOLS_DLLPRIVATE static ::osl::Mutex& GetOwnStaticMutex();
 186
 187     private:
 188
 189         /*Attention
 190
 191             Don't initialize these static member in these header!
 192             a) Double dfined symbols will be detected ...
 193             b) and unresolved externals exist at linking time.
 194             Do it in your source only.
 195          */
 196
 197         static SvtHistoryOptions_Impl*  m_pDataContainer    ;   /// impl. data container as dynamic pointer for smaller memory requirements!
 198         static sal_Int32                m_nRefCount         ;   /// internal ref count mechanism
 199
 200 };      // class SvtHistoryOptions
 201
 202 #endif // INCLUDED_UNOTOOLS_HISTORYOPTIONS_HXX
 203
 204 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */