sd/source/ui/inc/TemplateScanner.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 _TEMPLATE_SCANNER_HXX
  21 #define _TEMPLATE_SCANNER_HXX
  22
  23 #include "tools/AsynchronousTask.hxx"
  24 #include "sddllapi.h"
  25 #include <ucbhelper/content.hxx>
  26 #include <tools/string.hxx>
  27 #include "com/sun/star/uno/Reference.hxx"
  28
  29 #include <vector>
  30 #include <boost/scoped_ptr.hpp>
  31 #include <boost/shared_ptr.hpp>
  32
  33 namespace com { namespace sun { namespace star { namespace ucb {
  34 class XContent;
  35 class XCommandEnvironment;
  36 } } } }
  37
  38 namespace com { namespace sun { namespace star { namespace sdbc {
  39 class XResultSet;
  40 } } } }
  41
  42 namespace comphelper { namespace string {
  43 class NaturalStringSorter;
  44 } }
  45
  46 namespace sd {
  47
  48 /** Representation of a template or layout file.
  49 */
  50 class TemplateEntry
  51 {
  52 public:
  53     TemplateEntry   (const String& rsTitle, const String& rsPath)
  54         :   msTitle(rsTitle), msPath(rsPath) {}
  55
  56     String msTitle;
  57     String msPath;
  58 };
  59
  60
  61
  62
  63 /** Functor that compares two TemplateEntries based on their titles
  64 */
  65 class TemplateEntryCompare
  66 {
  67 public:
  68     TemplateEntryCompare();
  69     bool operator()(TemplateEntry* pA, TemplateEntry* pB) const;
  70
  71 private:
  72     ::boost::shared_ptr<comphelper::string::NaturalStringSorter> mpStringSorter;
  73 };
  74
  75
  76
  77
  78 /** Representation of a template or layout folder.
  79 */
  80 class TemplateDir
  81 {
  82 public:
  83     TemplateDir (const String& rsRegion, const String& rsUrl )
  84         :   msRegion(rsRegion), msUrl(rsUrl), maEntries(),
  85             mbSortingEnabled(false), mpEntryCompare(NULL) {}
  86
  87     String msRegion;
  88     String msUrl;
  89     ::std::vector<TemplateEntry*> maEntries;
  90
  91     void EnableSorting(bool bSortingEnabled = true);
  92     void InsertEntry(TemplateEntry* pNewEntry);
  93
  94 private:
  95     bool mbSortingEnabled;
  96     ::boost::scoped_ptr<TemplateEntryCompare> mpEntryCompare;
  97 };
  98
  99
 100
 101
 102 /** This class scans the template folders for impress templates.  There are
 103     two ways to use this class.
 104     1. The old and deprecated way is to call Scan() to scan all templates
 105     and collect the supported ones in a tree structure.  This structure is
 106     returned by GetFolderList().
 107     2. The new way implements the AsynchronousTask interface.  Call
 108     RunNextStep() as long HasNextStep() returns <TRUE/>.  After every step
 109     GetLastAddedEntry() returns the template that was scanned (and has a
 110     supported format) last.  When a step does not add a new template then
 111     the value of the previous step is returned.
 112 */
 113 class SD_DLLPUBLIC TemplateScanner
 114     : public ::sd::tools::AsynchronousTask
 115 {
 116 public:
 117     /** Create a new template scanner and prepare but do not execute the scanning.
 118     */
 119     TemplateScanner (void);
 120
 121     /** The destructor deletes any remaining entries of the local list of
 122         templates.
 123     */
 124     virtual ~TemplateScanner (void);
 125
 126     /** Execute the actual scanning of templates.  When this method
 127         terminates the result can be obtained by calling the
 128         <member>GetTemplateList</member> method.
 129     */
 130     void Scan (void);
 131
 132     /** Return the list of template folders.  It lies in the responsibility
 133         of the caller to take ownership of some or all entries and remove
 134         them from the returned list.  All entries that remain until the
 135         destructor is called will be destroyed.
 136     */
 137     std::vector<TemplateDir*>& GetFolderList (void);
 138
 139     /** Implementation of the AsynchronousTask interface method.
 140     */
 141     virtual void RunNextStep (void);
 142
 143     /** Implementation of the AsynchronousTask interface method.
 144     */
 145     virtual bool HasNextStep (void);
 146
 147     /** Return the TemplateDir object that was last added to
 148         mpTemplateDirectory.
 149         @return
 150             <NULL/> is returned either before the template scanning is
 151             started or after it has ended.
 152     */
 153     const TemplateEntry* GetLastAddedEntry (void) const;
 154
 155     /** Set whether to sort the template entries inside the regions.
 156     */
 157     void EnableEntrySorting (bool isEntrySortingEnabled = true)
 158         {mbEntrySortingEnabled = isEntrySortingEnabled;}
 159
 160 private:
 161     /** The current state determines which step will be executed next by
 162         RunNextStep().
 163     */
 164     enum State {
 165         INITIALIZE_SCANNING,
 166         INITIALIZE_FOLDER_SCANNING,
 167         GATHER_FOLDER_LIST,
 168         SCAN_FOLDER,
 169         INITIALIZE_ENTRY_SCAN,
 170         SCAN_ENTRY,
 171         DONE,
 172         ERROR
 173     };
 174     State meState;
 175
 176     ::ucbhelper::Content maFolderContent;
 177     TemplateDir* mpTemplateDirectory;
 178
 179     /** The data structure that is to be filled with information about the
 180         template files.
 181     */
 182      std::vector<TemplateDir*> maFolderList;
 183
 184     /** Whether the template entries have to be sorted.
 185     */
 186     bool mbEntrySortingEnabled;
 187
 188     /** This member points into the maFolderList to the member that was most
 189         recently added.
 190     */
 191     TemplateEntry* mpLastAddedEntry;
 192
 193     /** The folders that are collected by GatherFolderList().
 194     */
 195     class FolderDescriptorList;
 196     ::boost::scoped_ptr<FolderDescriptorList> mpFolderDescriptors;
 197
 198     /** Set of state variables used by the methods
 199         InitializeFolderScanning(), GatherFolderList(), ScanFolder(),
 200         InitializeEntryScanning(), and ScanEntry().
 201     */
 202     com::sun::star::uno::Reference<com::sun::star::ucb::XContent> mxTemplateRoot;
 203     com::sun::star::uno::Reference<com::sun::star::ucb::XCommandEnvironment> mxFolderEnvironment;
 204     com::sun::star::uno::Reference<com::sun::star::ucb::XCommandEnvironment> mxEntryEnvironment;
 205     com::sun::star::uno::Reference<com::sun::star::sdbc::XResultSet> mxFolderResultSet;
 206     com::sun::star::uno::Reference<com::sun::star::sdbc::XResultSet> mxEntryResultSet;
 207
 208     /** Obtain the root folder of the template folder hierarchy.  The result
 209         is stored in mxTemplateRoot for later use.
 210     */
 211     State GetTemplateRoot (void);
 212
 213     /** Initialize the scanning of folders.  This is called exactly once.
 214         @return
 215             Returns one of the two states ERROR or GATHER_FOLDER_LIST.
 216     */
 217     State InitializeFolderScanning (void);
 218
 219     /** Collect all available top-level folders in an ordered list which can
 220         then be processed by ScanFolder().
 221         @return
 222             Returns one of the two states ERROR or SCAN_FOLDER.
 223     */
 224     State GatherFolderList (void);
 225
 226     /** From the list of top-level folders collected by GatherFolderList()
 227         the one with highest priority is processed.
 228         @return
 229             Returns one of the states ERROR, DONE, or INITILIZE_ENTRY_SCAN.
 230     */
 231     State ScanFolder (void);
 232
 233     /** Initialize the scanning of entries of a top-level folder.
 234         @return
 235             Returns one of the states ERROR or SCAN_ENTRY.
 236     */
 237     State InitializeEntryScanning (void);
 238
 239     /** Scan one entry.  When this entry matches the recognized template
 240         types it is appended to the result set.
 241         @return
 242             Returns one of the states ERROR, SCAN_ENTRY, or SCAN_FOLDER.
 243     */
 244     State ScanEntry (void);
 245 };
 246
 247 } // end of namespace sd
 248
 249 #endif
 250
 251 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */