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 #pragma once
  21
  22 #include "tools/AsynchronousTask.hxx"
  23 #include <ucbhelper/content.hxx>
  24 #include <com/sun/star/uno/Reference.h>
  25
  26 #include <memory>
  27 #include <utility>
  28 #include <vector>
  29
  30 namespace com::sun::star::ucb
  31 {
  32 class XContent;
  33 class XCommandEnvironment;
  34 }
  35
  36 namespace com::sun::star::sdbc
  37 {
  38 class XResultSet;
  39 }
  40
  41 namespace sd
  42 {
  43 /** Representation of a template or layout file.
  44 */
  45 class TemplateEntry
  46 {
  47 public:
  48     TemplateEntry(OUString sTitle, OUString sPath)
  49         : msTitle(std::move(sTitle))
  50         , msPath(std::move(sPath))
  51     {
  52     }
  53
  54     OUString msTitle;
  55     OUString msPath;
  56 };
  57
  58 /** This class scans the template folders for impress templates.  There are
  59     two ways to use this class.
  60     1. The old and deprecated way is to call Scan() to scan all templates
  61     and collect the supported ones in a tree structure.  This structure is
  62     returned by GetFolderList().
  63     2. The new way implements the AsynchronousTask interface.  Call
  64     RunNextStep() as long HasNextStep() returns <TRUE/>.  After every step
  65     GetLastAddedEntry() returns the template that was scanned (and has a
  66     supported format) last.  When a step does not add a new template then
  67     the value of the previous step is returned.
  68 */
  69 class TemplateScanner final : public ::sd::tools::AsynchronousTask
  70 {
  71 public:
  72     /** Create a new template scanner and prepare but do not execute the scanning.
  73     */
  74     TemplateScanner();
  75
  76     /** The destructor deletes any remaining entries of the local list of
  77         templates.
  78     */
  79     virtual ~TemplateScanner();
  80
  81     /** Implementation of the AsynchronousTask interface method.
  82     */
  83     virtual void RunNextStep() override;
  84
  85     /** Implementation of the AsynchronousTask interface method.
  86     */
  87     virtual bool HasNextStep() override;
  88
  89     /** Return the TemplateDir object that was last added to
  90         mpTemplateEntries.
  91         @return
  92             <nullptr/> is returned either before the template scanning is
  93             started or after it has ended.
  94     */
  95     const TemplateEntry* GetLastAddedEntry() const
  96     {
  97         return mpTemplateEntries.empty() ? nullptr : mpTemplateEntries.back().get();
  98     }
  99
 100 private:
 101     /** The current state determines which step will be executed next by
 102         RunNextStep().
 103     */
 104     enum State
 105     {
 106         INITIALIZE_SCANNING,
 107         INITIALIZE_FOLDER_SCANNING,
 108         GATHER_FOLDER_LIST,
 109         SCAN_FOLDER,
 110         INITIALIZE_ENTRY_SCAN,
 111         SCAN_ENTRY,
 112         DONE,
 113         ERROR
 114     };
 115     State meState;
 116
 117     ::ucbhelper::Content maFolderContent;
 118     ::std::vector<std::unique_ptr<TemplateEntry>> mpTemplateEntries;
 119
 120     /** The folders that are collected by GatherFolderList().
 121     */
 122     class FolderDescriptorList;
 123     std::unique_ptr<FolderDescriptorList> mpFolderDescriptors;
 124
 125     /** Set of state variables used by the methods
 126         InitializeFolderScanning(), GatherFolderList(), ScanFolder(),
 127         InitializeEntryScanning(), and ScanEntry().
 128     */
 129     css::uno::Reference<css::ucb::XContent> mxTemplateRoot;
 130     css::uno::Reference<css::ucb::XCommandEnvironment> mxFolderEnvironment;
 131     css::uno::Reference<css::ucb::XCommandEnvironment> mxEntryEnvironment;
 132     css::uno::Reference<css::sdbc::XResultSet> mxFolderResultSet;
 133     css::uno::Reference<css::sdbc::XResultSet> mxEntryResultSet;
 134
 135     /** Obtain the root folder of the template folder hierarchy.  The result
 136         is stored in mxTemplateRoot for later use.
 137     */
 138     State GetTemplateRoot();
 139
 140     /** Initialize the scanning of folders.  This is called exactly once.
 141         @return
 142             Returns one of the two states ERROR or GATHER_FOLDER_LIST.
 143     */
 144     State InitializeFolderScanning();
 145
 146     /** Collect all available top-level folders in an ordered list which can
 147         then be processed by ScanFolder().
 148         @return
 149             Returns one of the two states ERROR or SCAN_FOLDER.
 150     */
 151     State GatherFolderList();
 152
 153     /** From the list of top-level folders collected by GatherFolderList()
 154         the one with highest priority is processed.
 155         @return
 156             Returns one of the states ERROR, DONE, or INITIALIZE_ENTRY_SCAN.
 157     */
 158     State ScanFolder();
 159
 160     /** Initialize the scanning of entries of a top-level folder.
 161         @return
 162             Returns one of the states ERROR or SCAN_ENTRY.
 163     */
 164     State InitializeEntryScanning();
 165
 166     /** Scan one entry.  When this entry matches the recognized template
 167         types it is appended to the result set.
 168         @return
 169             Returns one of the states ERROR, SCAN_ENTRY, or SCAN_FOLDER.
 170     */
 171     State ScanEntry();
 172 };
 173
 174 } // end of namespace sd
 175
 176 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */