include/unotools/viewoptions.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_VIEWOPTIONS_HXX
  20 #define INCLUDED_unotools_VIEWOPTIONS_HXX
  21
  22 #include "unotools/unotoolsdllapi.h"
  23 #include <com/sun/star/uno/Sequence.hxx>
  24 #include <com/sun/star/beans/NamedValue.hpp>
  25 #include <unotools/configmgr.hxx>
  26 #include <unotools/configitem.hxx>
  27 #include <sal/types.h>
  28 #include <osl/mutex.hxx>
  29 #include <rtl/ustring.hxx>
  30 #include <unotools/options.hxx>
  31
  32 //_________________________________________________________________________________________________________________
  33 //  forward declarations
  34 //_________________________________________________________________________________________________________________
  35
  36 class SvtViewOptionsBase_Impl;
  37
  38 /*-************************************************************************************************************//**
  39     @descr          Use these enum values to specify right list in configuration in which your view data are saved.
  40 *//*-*************************************************************************************************************/
  41
  42 enum EViewType
  43 {
  44     E_DIALOG    =   0,
  45     E_TABDIALOG =   1,
  46     E_TABPAGE   =   2,
  47     E_WINDOW    =   3
  48 };
  49
  50 /*-************************************************************************************************************//**
  51     @short          collect information about view features
  52     @descr          We support different basetypes of views like dialogs, tab-dialogs, tab-pages and normal windows.
  53                     You must specify your basetype by using right enum value and must give us a valid name for your
  54                     subkey in registry! We support some fix features for some bastypes and user data as string for all!
  55                     see also configuration package "org.openoffice.Office.Views/..." for further information.
  56
  57                     template of configuration:
  58                         DialogType
  59                             /WindowState    [string]
  60                             /UserData       [set of any scalar types]
  61                         TabDialogType
  62                             /WindowState    [string]
  63                             /UserData       [set of any scalar types]
  64                             /PageID         [int]
  65                         TabPageType
  66                             /WindowState    [string]
  67                             /UserData       [set of any scalar types]
  68                         WindowType
  69                             /WindowState    [string]
  70                             /UserData       [set of any scalar types]
  71                             /Visible        [boolean]
  72
  73                     structure of configuration:
  74
  75                         org.openoffice.Office.Views [package]
  76                                                     /Dialogs    [set]
  77                                                                 /Dialog_FileOpen            [DialogType]
  78                                                                 /Dialog_ImportGraphics      [DialogType]
  79                                                                 ...
  80                                                                 /Dialog_<YourName>          [DialogType]
  81
  82                                                     /TabDialogs [set]
  83                                                                 /TabDialog_001              [TabDialogType]
  84                                                                 /TabDialog_Blubber          [TabDialogType]
  85                                                                 ...
  86                                                                 /TabDialog_<YourName>       [TabDialogType]
  87
  88                                                     /TabPages   [set]
  89                                                                 /TabPage_XXX                [TabPageType]
  90                                                                 /TabPage_Date               [TabPageType]
  91                                                                 ...
  92                                                                 /TabPage_<YourName>         [TabPageType]
  93
  94                                                     /Windows    [set]
  95                                                                 /Window_User                [WindowType]
  96                                                                 /Window_Options             [WindowType]
  97                                                                 ...
  98                                                                 /Window_<YourName>          [WindowType]
  99
 100     @implements     -
 101     @base           -
 102
 103     @devstatus      ready to use
 104 *//*-*************************************************************************************************************/
 105
 106 class UNOTOOLS_DLLPUBLIC SAL_WARN_UNUSED SvtViewOptions : public utl::detail::Options
 107 {
 108     //-------------------------------------------------------------------------------------------------------------
 109     //  public methods
 110     //-------------------------------------------------------------------------------------------------------------
 111
 112     public:
 113
 114         //---------------------------------------------------------------------------------------------------------
 115         //  constructor / destructor
 116         //---------------------------------------------------------------------------------------------------------
 117
 118         /*-****************************************************************************************************//**
 119             @short      standard constructor and destructor
 120             @descr      This will de-/initialize an instance with default values.
 121                         You must give us the basic type of your view and a name which specify right entry
 122                         in dynamical configuration list. If entry not exist, we create a new one!
 123
 124             @seealso    enum EViewType
 125
 126             @param      "eType" specify type of your view and is used to use right data container!
 127             @param      "sViewName" specify the name of your view and is the key name in data list too.
 128             @return     -
 129
 130             @onerror    An assertion is thrown in debug version. Otherwise we do nothing!
 131         *//*-*****************************************************************************************************/
 132
 133          SvtViewOptions(       EViewType        eType     ,
 134                          const OUString& sViewName );
 135         virtual ~SvtViewOptions();
 136
 137         /*-****************************************************************************************************//**
 138             @short      support preload of these config item
 139             @descr      Sometimes we need preloading of these configuration data without real using of it.
 140
 141             @seealso    -
 142
 143             @param      -
 144             @return     -
 145
 146             @onerror    -
 147         *//*-*****************************************************************************************************/
 148
 149         static void AcquireOptions();
 150         static void ReleaseOptions();
 151
 152         //---------------------------------------------------------------------------------------------------------
 153         //  interface
 154         //---------------------------------------------------------------------------------------------------------
 155
 156         /*-****************************************************************************************************//**
 157             @short      use it to get information about existing entries in configuration
 158             @descr      The methods to set/get the position or size will create a new entry automaticly if
 159                         it not already exist and work with default values!
 160                         If this a problem for you - you MUST call these method before and
 161                         you must make up your own mind about that.
 162
 163             @seealso    -
 164
 165             @onerror    No error should occure.
 166         *//*-*****************************************************************************************************/
 167
 168         sal_Bool Exists() const;
 169
 170         /*-****************************************************************************************************//**
 171             @short      use it to delete an entry of dynamic view set
 172             @descr      You can use this method to delete anexisting node in configuration.
 173                         But if you call a Set- or Get- method again on this instance
 174                         the item is created again! If you do nothing after this call
 175                         your view will die relay in configuration ...
 176
 177             @seealso    method Exist()
 178
 179             @return     True if delete OK, False otherwise.
 180
 181             @onerror    We return sal_False.
 182         *//*-*****************************************************************************************************/
 183
 184         sal_Bool Delete();
 185
 186         /*-****************************************************************************************************//**
 187             @short      use it to set/get the window state of your view
 188             @descr      These value describe position/size and some other states of a window.
 189                         Use it with right vcl methods directly. Normaly it's not neccessary to
 190                         parse given string!
 191
 192             @seealso    vcl methods
 193
 194             @onerror    -
 195         *//*-*****************************************************************************************************/
 196
 197         OUString GetWindowState(                               ) const;
 198         void            SetWindowState( const OUString& sState );
 199
 200         /*-****************************************************************************************************//**
 201             @short      use it to set/get the page number which was the last active one
 202             @descr      It's only supported for:    - tab-dialogs
 203                         If you call it for other ones you will get an assertion in debug version.
 204                         In a product version we do nothing!
 205
 206             @seealso    -
 207
 208             @onerror    An assertion is thrown in debug version. Otherwise we do nothing!
 209         *//*-*****************************************************************************************************/
 210
 211         sal_Int32 GetPageID(               ) const;
 212         void      SetPageID( sal_Int32 nID );
 213
 214         /*-****************************************************************************************************//**
 215             @short      use it to set/get the visual state of a window
 216             @descr      It's only supported for:    - windows
 217                         If you call it for other ones you will get an assertion in debug version.
 218                         In a product version we do nothing!
 219
 220             @seealso    -
 221
 222             @onerror    An assertion is thrown in debug version. Otherwise we do nothing!
 223         *//*-*****************************************************************************************************/
 224
 225         sal_Bool IsVisible (                 ) const;
 226         void     SetVisible( sal_Bool bState );
 227
 228         /** Return true if the "Visible" property actually has a non-nil value
 229
 230             (IsVisible will somewhat arbitrarily return false if the property is
 231             nil.)
 232         */
 233         bool HasVisible() const;
 234
 235         /*-****************************************************************************************************//**
 236             @short      use it to set/get the extended user data (consisting of a set of named scalar values)
 237             @descr      It's supported for ALL types!
 238                         Every view can handle its own user defined data set.
 239
 240             @seealso    -
 241
 242             @onerror    In the non-product version, an assertion is made. In a product version, errors are silently ignored.
 243         *//*-*****************************************************************************************************/
 244         ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue > GetUserData(                                                                                     ) const;
 245         void                                                                   SetUserData( const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& lData );
 246
 247         /*-****************************************************************************************************//**
 248             @short      use it to set/get ONE special user data item directly
 249             @descr      Normaly you can work on full user data list by using "Set/GetUserData()".
 250                         With this function you have an access on special list entries directly without any
 251
 252             @seealso    -
 253
 254             @onerror    In the non-product version, an assertion is made. In a product version, errors are silently ignored.
 255         *//*-*****************************************************************************************************/
 256
 257         ::com::sun::star::uno::Any GetUserItem( const OUString&            sName  ) const;
 258         void                       SetUserItem( const OUString&            sName  ,
 259                                                 const ::com::sun::star::uno::Any& aValue );
 260
 261     //-------------------------------------------------------------------------------------------------------------
 262     //  private methods
 263     //-------------------------------------------------------------------------------------------------------------
 264
 265     private:
 266
 267         /*-****************************************************************************************************//**
 268             @short      return a reference to a static mutex
 269             @descr      These class is threadsafe.
 270                         We create a static mutex only for one time and use it to protect our refcount and container
 271                         member!
 272
 273             @seealso    -
 274
 275             @param      -
 276             @return     A reference to a static mutex member.
 277
 278             @onerror    -
 279         *//*-*****************************************************************************************************/
 280
 281         UNOTOOLS_DLLPRIVATE static ::osl::Mutex& GetOwnStaticMutex();
 282
 283     //-------------------------------------------------------------------------------------------------------------
 284     //  private member
 285     //-------------------------------------------------------------------------------------------------------------
 286
 287     private:
 288
 289         /// specify which list of views in configuration is used! This can't be a static value!!!
 290         /// ... because we need this value to work with right static data container.
 291         EViewType           m_eViewType     ;
 292         OUString     m_sViewName     ;
 293
 294         /// - impl. data container as dynamic pointer for smaller memory requirements!
 295         /// - internal ref count mechanism
 296
 297         /*Attention
 298
 299             Don't initialize these static member in these header!
 300             a) Double defined symbols will be detected ...
 301             b) and unresolved externals exist at linking time.
 302             Do it in your source only.
 303          */
 304
 305         static SvtViewOptionsBase_Impl*    m_pDataContainer_Dialogs    ;   /// hold data for all dialogs
 306         static sal_Int32                   m_nRefCount_Dialogs         ;
 307         static SvtViewOptionsBase_Impl*    m_pDataContainer_TabDialogs ;   /// hold data for all tab-dialogs
 308         static sal_Int32                   m_nRefCount_TabDialogs      ;
 309         static SvtViewOptionsBase_Impl*    m_pDataContainer_TabPages   ;   /// hold data for all tab-pages
 310         static sal_Int32                   m_nRefCount_TabPages        ;
 311         static SvtViewOptionsBase_Impl*    m_pDataContainer_Windows    ;   /// hold data for all windows
 312         static sal_Int32                   m_nRefCount_Windows         ;
 313
 314 };      // class SvtViewOptions
 315
 316 #endif  // #ifndef INCLUDED_unotools_VIEWOPTIONS_HXX
 317
 318 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */