sd/source/ui/sidebar/MasterPageContainer.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_SD_SOURCE_UI_SIDEBAR_MASTERPAGECONTAINER_HXX
  21 #define INCLUDED_SD_SOURCE_UI_SIDEBAR_MASTERPAGECONTAINER_HXX
  22
  23 #include "MasterPageContainerProviders.hxx"
  24
  25 #include <vcl/image.hxx>
  26 #include <PreviewRenderer.hxx>
  27 #include <vcl/timer.hxx>
  28 #include <tools/SdGlobalResourceContainer.hxx>
  29
  30 #include <memory>
  31
  32 class SdPage;
  33
  34 namespace sd { namespace sidebar {
  35
  36 class MasterPageDescriptor;
  37 class MasterPageContainerChangeEvent;
  38
  39 /** This container manages the master pages used by the MasterPagesSelector
  40     controls.  It uses internally a singleton implementation object.
  41     Therefore, all MasterPageContainer object operator on the same set of
  42     master pages.  Each MasterPageContainer, however, has its own
  43     PreviewSize value and thus can independently switch between large and
  44     small previews.
  45
  46     The container maintains its own document to store master page objects.
  47
  48     For each master page container stores its URL, preview bitmap, page
  49     name, and, if available, the page object.
  50
  51     Entries are accessed via a Token, which is mostly a numerical index but
  52     whose values do not necessarily have to be consecutive.
  53 */
  54 class MasterPageContainer final
  55 {
  56 public:
  57     typedef int Token;
  58     static const Token NIL_TOKEN = -1;
  59
  60     MasterPageContainer();
  61     ~MasterPageContainer();
  62
  63     void AddChangeListener (const Link<MasterPageContainerChangeEvent&,void>& rLink);
  64     void RemoveChangeListener (const Link<MasterPageContainerChangeEvent&,void>& rLink);
  65
  66     enum PreviewSize { SMALL, LARGE };
  67     /** There are two different preview sizes, a small one and a large one.
  68         Which one is used by the called container can be changed with this
  69         method.
  70         When the preview size is changed then all change listeners are
  71         notified of this.
  72     */
  73     void SetPreviewSize (PreviewSize eSize);
  74
  75     /** Returns the preview size.
  76     */
  77     PreviewSize GetPreviewSize() const { return mePreviewSize;}
  78
  79     /** Return the preview size in pixels.
  80     */
  81     Size const & GetPreviewSizePixel() const;
  82
  83     enum PreviewState { PS_AVAILABLE, PS_CREATABLE, PS_PREPARING, PS_NOT_AVAILABLE };
  84     PreviewState GetPreviewState (Token aToken);
  85
  86     /** This method is typically called for entries in the container for
  87         which GetPreviewState() returns OS_CREATABLE.  The creation of the
  88         preview is then scheduled to be executed asynchronously at a later
  89         point in time.  When the preview is available the change listeners
  90         will be notified.
  91     */
  92     bool RequestPreview (Token aToken);
  93
  94     /** Each entry of the container is either the first page of a template
  95         document or is a master page of an Impress document.
  96     */
  97     enum Origin {
  98         MASTERPAGE,  // Master page of a document.
  99         TEMPLATE,    // First page of a template file.
 100         DEFAULT,     // Empty master page with default style.
 101         UNKNOWN
 102     };
 103
 104     /** Put the master page identified and described by the given parameters
 105         into the container.  When there already is a master page with the
 106         given URL, page name, or object pointer (when that is not NULL) then
 107         the existing entry is replaced/updated by the given one.  Otherwise
 108         a new entry is inserted.
 109     */
 110     Token PutMasterPage (const std::shared_ptr<MasterPageDescriptor>& rDescriptor);
 111     void AcquireToken (Token aToken);
 112     void ReleaseToken (Token aToken);
 113
 114     /** This and the GetTokenForIndex() methods can be used to iterate over
 115         all members of the container.
 116     */
 117     int GetTokenCount() const;
 118
 119     /** Determine whether the container has a member for the given token.
 120     */
 121     bool HasToken (Token aToken) const;
 122
 123     /** Return a token for an index in the range
 124         0 <= index < GetTokenCount().
 125     */
 126     Token GetTokenForIndex (int nIndex);
 127
 128     Token GetTokenForURL (const OUString& sURL);
 129     Token GetTokenForStyleName (const OUString& sStyleName);
 130     Token GetTokenForPageObject (const SdPage* pPage);
 131
 132     OUString GetURLForToken (Token aToken);
 133     OUString GetPageNameForToken (Token aToken);
 134     OUString GetStyleNameForToken (Token aToken);
 135     SdPage* GetPageObjectForToken (Token aToken, bool bLoad);
 136     Origin GetOriginForToken (Token aToken);
 137     sal_Int32 GetTemplateIndexForToken (Token aToken);
 138     std::shared_ptr<MasterPageDescriptor> GetDescriptorForToken (Token aToken);
 139
 140     void InvalidatePreview (Token aToken);
 141
 142     /** Return a preview for the specified token.  When the preview is not
 143         present then the PreviewProvider associated with the token is
 144         executed only when that is not expensive.  It is the responsibility
 145         of the caller to call RequestPreview() to do the same
 146         (asynchronously) for expensive PreviewProviders.
 147         Call GetPreviewState() to find out if that is necessary.
 148         @param aToken
 149             This token specifies for which master page to return the preview.
 150             Tokens are returned for example by the GetTokenFor...() methods.
 151         @return
 152             The returned image is the requested preview or a substitution.
 153     */
 154     Image GetPreviewForToken (Token aToken);
 155
 156 private:
 157     class Implementation;
 158     std::shared_ptr<Implementation> mpImpl;
 159     PreviewSize mePreviewSize;
 160 };
 161
 162 /** For some changes to the set of master pages in a MasterPageContainer or
 163     to the data stored for each master page one or more events are sent to
 164     registered listeners.
 165     Each event has an event type and a token that tells the listener where
 166     the change took place.
 167 */
 168 class MasterPageContainerChangeEvent
 169 {
 170 public:
 171     enum class EventType {
 172         // A master page was added to the container.
 173         CHILD_ADDED,
 174         // A master page was removed from the container.
 175         CHILD_REMOVED,
 176         // The preview of a master page has changed.
 177         PREVIEW_CHANGED,
 178         // The size of a preview has changed.
 179         SIZE_CHANGED,
 180         // Some of the data stored for a master page has changed.
 181         DATA_CHANGED,
 182         // The TemplateIndex of a master page has changed.
 183         INDEX_CHANGED,
 184     } meEventType;
 185
 186     // Token of the container entry whose data changed or which was added or
 187     // removed.
 188     MasterPageContainer::Token maChildToken;
 189 };
 190
 191 } } // end of namespace sd::sidebar
 192
 193 #endif
 194
 195 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */