include/svtools/templatefoldercache.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_SVTOOLS_TEMPLATEFOLDERCACHE_HXX
  21 #define INCLUDED_SVTOOLS_TEMPLATEFOLDERCACHE_HXX
  22
  23 #include <svtools/svtdllapi.h>
  24 #include <sal/types.h>
  25
  26
  27 namespace svt
  28 {
  29
  30
  31
  32     //= TemplateFolderCache
  33
  34     class TemplateFolderCacheImpl;
  35     /** allows to cache the state of the template directories of OOo
  36         <p>Usually, this class is used together with an instance of a the
  37         <service scope="com.sun.star.frame">DocumentTemplates</service> service. It allows to scan the template folders
  38         of the Office, and updates the configuration so that it reflects the most recent state of the folders.<br/>
  39         As this is an expensive, the TemplateFolderCache has been introduced. It caches the state of the template
  40         folders, and allows to determine if the DocumentTemplates service needs to be invoked to do the (much more expensive)
  41         update.</p>
  42     @example C++
  43     <listing>
  44         TemplateFolderCache aTemplateFolders;
  45         if ( aTemplateFolders.needsUpdate() )
  46         {
  47             // store the current state
  48             aCache.storeState();
  49
  50             // create the DocumentTemplates instance
  51             Reference< XDocumentTemplates > xTemplates = ...;
  52
  53             // update the templates configuration
  54             xTemplates->update();
  55         }
  56
  57         // do anything which relies on a up-to-date template configuration
  58     </listing>
  59     */
  60     class SVT_DLLPUBLIC TemplateFolderCache
  61     {
  62     private:
  63         TemplateFolderCacheImpl*        m_pImpl;
  64
  65     public:
  66         /** ctor.
  67         @param _bAutoStoreState
  68             Set this to <TRUE/> if you want the instance to automatically store the state of the template folders upon
  69             destruction.<br/>
  70             If set to <FALSE/>, you would epplicitly need to call <method>storeState</method> to do this.<br/>
  71             If the current state is not known (e.g. because you did not call needsUpdate, which retrieves it),
  72             it is not retrieved in the dtor, regardless of the <arg>_bAutoStoreState</arg> flag.
  73         */
  74         TemplateFolderCache( bool _bAutoStoreState = false );
  75         ~TemplateFolderCache( );
  76
  77         /** determines whether or not the template configuration needs to be updated
  78         @param _bForceCheck
  79             set this to <TRUE/> if you want the object to rescan the template folders in every case. The default (<FALSE/>)
  80             means that once the information has been retrieved in a first call, every second call returns the same result
  81             as the first one, even if in the meantime the template folders changed.
  82         @return
  83             <TRUE/> if the template configuration needs to be updated
  84         */
  85         bool    needsUpdate( bool _bForceCheck = false );
  86
  87         /** stores the current state of the template folders in the cache
  88         @param _bForceRetrieval
  89             if set to <TRUE/>, the current state of the template folders is retrieved again, even if it is already known.
  90             Usually, you set this to <FALSE/>: After calling <method>needsUpdate</method>, the state is know and does not
  91             need to be read again.
  92         */
  93         void        storeState( bool _bForceRetrieval = false );
  94     };
  95
  96
  97 }   // namespace svt
  98
  99
 100 #endif // INCLUDED_SVTOOLS_TEMPLATEFOLDERCACHE_HXX
 101
 102 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */