sd/source/ui/inc/TemplateScanner.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: TemplateScanner.hxx,v $
  10  * $Revision: 1.7 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _TEMPLATE_SCANNER_HXX
  32 #define _TEMPLATE_SCANNER_HXX
  33
  34 #include "tools/AsynchronousTask.hxx"
  35 #include "sddllapi.h"
  36 #include <ucbhelper/content.hxx>
  37 #include <tools/string.hxx>
  38 #include "com/sun/star/uno/Reference.hxx"
  39
  40 #include <vector>
  41 #include <boost/scoped_ptr.hpp>
  42
  43 namespace com { namespace sun { namespace star { namespace ucb {
  44 class XContent;
  45 class XCommandEnvironment;
  46 } } } }
  47
  48 namespace com { namespace sun { namespace star { namespace sdbc {
  49 class XResultSet;
  50 } } } }
  51
  52 namespace sd {
  53
  54 /** Representation of a template or layout file.
  55 */
  56 class TemplateEntry
  57 {
  58 public:
  59     TemplateEntry   (const String& rsTitle, const String& rsPath)
  60         :   msTitle(rsTitle), msPath(rsPath) {}
  61
  62     String msTitle;
  63     String msPath;
  64 };
  65
  66
  67
  68
  69 /** Representation of a template or layout folder.
  70 */
  71 class TemplateDir
  72 {
  73 public:
  74     TemplateDir (const String& rsRegion, const String& rsUrl )
  75         :   msRegion(rsRegion), msUrl(rsUrl), maEntries() {}
  76
  77     String msRegion;
  78     String msUrl;
  79     ::std::vector<TemplateEntry*> maEntries;
  80 };
  81
  82
  83
  84
  85 /** This class scans the template folders for impress templates.  There are
  86     two ways to use this class.
  87     1. The old and deprecated way is to call Scan() to scan all templates
  88     and collect the supported ones in a tree structure.  This structure is
  89     returned by GetFolderList().
  90     2. The new way implements the AsynchronousTask interface.  Call
  91     RunNextStep() as long HasNextStep() returns <TRUE/>.  After every step
  92     GetLastAddedEntry() returns the template that was scanned (and has a
  93     supported format) last.  When a step does not add a new template then
  94     the value of the previous step is returned.
  95 */
  96 class SD_DLLPUBLIC TemplateScanner
  97     : public ::sd::tools::AsynchronousTask
  98 {
  99 public:
 100     /** Create a new template scanner and prepare but do not execute the scanning.
 101     */
 102     TemplateScanner (void);
 103
 104     /** The destructor deletes any remaining entries of the local list of
 105         templates.
 106     */
 107     virtual ~TemplateScanner (void);
 108
 109     /** Execute the actual scanning of templates.  When this method
 110         terminates the result can be obtained by calling the
 111         <member>GetTemplateList</member> method.
 112     */
 113     void Scan (void);
 114
 115     /** Return the list of template folders.  It lies in the responsibility
 116         of the caller to take ownership of some or all entries and remove
 117         them from the returned list.  All entries that remain until the
 118         destructor is called will be destroyed.
 119     */
 120     std::vector<TemplateDir*>& GetFolderList (void);
 121
 122     /** Implementation of the AsynchronousTask interface method.
 123     */
 124     virtual void RunNextStep (void);
 125
 126     /** Implementation of the AsynchronousTask interface method.
 127     */
 128     virtual bool HasNextStep (void);
 129
 130     /** Return the TemplateDir object that was last added to
 131         mpTemplateDirectory.
 132         @return
 133             <NULL/> is returned either before the template scanning is
 134             started or after it has ended.
 135     */
 136     const TemplateEntry* GetLastAddedEntry (void) const;
 137
 138 private:
 139     /** The current state determines which step will be executed next by
 140         RunNextStep().
 141     */
 142     enum State {
 143         INITIALIZE_SCANNING,
 144         INITIALIZE_FOLDER_SCANNING,
 145         GATHER_FOLDER_LIST,
 146         SCAN_FOLDER,
 147         INITIALIZE_ENTRY_SCAN,
 148         SCAN_ENTRY,
 149         DONE,
 150         ERROR
 151     };
 152     State meState;
 153
 154     ::ucbhelper::Content maFolderContent;
 155     TemplateDir* mpTemplateDirectory;
 156
 157     /** The data structure that is to be filled with information about the
 158         template files.
 159     */
 160      std::vector<TemplateDir*> maFolderList;
 161
 162     /** This member points into the maFolderList to the member that was most
 163         recently added.
 164     */
 165     TemplateEntry* mpLastAddedEntry;
 166
 167     /** The folders that are collected by GatherFolderList().
 168     */
 169     class FolderDescriptorList;
 170     ::boost::scoped_ptr<FolderDescriptorList> mpFolderDescriptors;
 171
 172     /** Set of state variables used by the methods
 173         InitializeFolderScanning(), GatherFolderList(), ScanFolder(),
 174         InitializeEntryScanning(), and ScanEntry().
 175     */
 176     com::sun::star::uno::Reference<com::sun::star::ucb::XContent> mxTemplateRoot;
 177     com::sun::star::uno::Reference<com::sun::star::ucb::XCommandEnvironment> mxFolderEnvironment;
 178     com::sun::star::uno::Reference<com::sun::star::ucb::XCommandEnvironment> mxEntryEnvironment;
 179     com::sun::star::uno::Reference<com::sun::star::sdbc::XResultSet> mxFolderResultSet;
 180     com::sun::star::uno::Reference<com::sun::star::sdbc::XResultSet> mxEntryResultSet;
 181
 182     /** Obtain the root folder of the template folder hierarchy.  The result
 183         is stored in mxTemplateRoot for later use.
 184     */
 185     State GetTemplateRoot (void);
 186
 187     /** Initialize the scanning of folders.  This is called exactly once.
 188         @return
 189             Returns one of the two states ERROR or GATHER_FOLDER_LIST.
 190     */
 191     State InitializeFolderScanning (void);
 192
 193     /** Collect all available top-level folders in an ordered list which can
 194         then be processed by ScanFolder().
 195         @return
 196             Returns one of the two states ERROR or SCAN_FOLDER.
 197     */
 198     State GatherFolderList (void);
 199
 200     /** From the list of top-level folders collected by GatherFolderList()
 201         the one with highest priority is processed.
 202         @return
 203             Returns one of the states ERROR, DONE, or INITILIZE_ENTRY_SCAN.
 204     */
 205     State ScanFolder (void);
 206
 207     /** Initialize the scanning of entries of a top-level folder.
 208         @return
 209             Returns one of the states ERROR or SCAN_ENTRY.
 210     */
 211     State InitializeEntryScanning (void);
 212
 213     /** Scan one entry.  When this entry matches the recognized template
 214         types it is appended to the result set.
 215         @return
 216             Returns one of the states ERROR, SCAN_ENTRY, or SCAN_FOLDER.
 217     */
 218     State ScanEntry (void);
 219 };
 220
 221 } // end of namespace sd
 222
 223 #endif