sd/source/ui/inc/TemplateScanner.hxx

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