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