sd/source/ui/slidesorter/inc/cache/SlsPageCache.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_SLIDESORTER_INC_CACHE_SLSPAGECACHE_HXX
  21 #define INCLUDED_SD_SOURCE_UI_SLIDESORTER_INC_CACHE_SLSPAGECACHE_HXX
  22
  23 #include <cache/SlsCacheContext.hxx>
  24 #include <vcl/bitmapex.hxx>
  25 #include <memory>
  26
  27 class Size;
  28
  29 namespace sd { namespace slidesorter { namespace cache {
  30
  31 class GenericPageCache;
  32
  33 /** The page cache is responsible for the creation and storage of preview
  34     bitmaps of pages that are shown by the slide sorter.
  35
  36     <p>Bitmaps for previews and a cache are used to speed up the display
  37     (painting) of the slide sorter.  But, of course, we have to limit this
  38     time-space-tradeoff by limiting the amount of space that can be use to
  39     store bitmaps.</p>
  40
  41     <p>There are several strategies employed by this class to shorten the
  42     perceived time that is used to paint the slide sorter:
  43     <ul>
  44     <li>Rendering pages ahead of time.  Additionally to rendering the
  45     visible slides we try to render part or all of the slides that are not
  46     (yet) visible.  This, of course, makes sense only when the computer is
  47     otherwise idle while doing that.</li>
  48     <li>When the size of the slides on the screen changes we mark the
  49     bitmaps as needing an update but use them while the new bitmap in the
  50     correct size is not available.</li>
  51     <li>Give the UI the chance to handle user events between the rendering
  52     of differe slides.</li>
  53     <li>Limit the amount of space that may be used for storing preview
  54     bitmaps and throw.</li>
  55     </p>
  56
  57     <p>There is another somewhat similar methods for requesting new previews:
  58     GetPreviewBitmap() schedules a re-rendering (when necessary) and
  59     returns the preview what is currently available, either as a preview of
  60     the preview or, when nothing has changed since the last call, as the
  61     final thing.
  62     </p>
  63 */
  64 class PageCache
  65 {
  66 public:
  67     /** The page cache is created with a reference to the slide sorter so
  68         that it has access to both the view and the model and so can fill
  69         itself with requests for all or just the visible pages.
  70
  71         It is the task of the PageCacheManager to create new objects of this
  72         class.
  73     */
  74     PageCache (
  75         const Size& rPreviewSize,
  76         const bool bDoSuperSampling,
  77         const SharedCacheContext& rpCacheContext);
  78
  79     ~PageCache();
  80
  81     void ChangeSize(
  82         const Size& rPreviewSize,
  83         const bool bDoSuperSampling);
  84
  85     /** Request a preview bitmap for the specified page object in the
  86         specified size.  The returned bitmap may be a preview of the
  87         preview, i.e. either a scaled (up or down) version of a previous
  88         preview (of the wrong size) or an empty bitmap.  In this case a
  89         request for the generation of a new preview is created and inserted
  90         into the request queue.  When the preview is available in the right
  91         size the page shape will be told to paint itself again.  When it
  92         then calls this method again if receives the correctly sized preview
  93         bitmap.
  94         @param rRequestData
  95             This data is used to determine the preview.
  96         @param bResize
  97             When <TRUE/> then when the available bitmap has not the
  98             requested size, it is scaled before it is returned.  When
  99             <FALSE/> then the bitmap is returned in the wrong size and it is
 100             the task of the caller to scale it.
 101         @return
 102             Returns a bitmap that is either empty, contains a scaled (up or
 103             down) version or is the requested bitmap.
 104     */
 105     BitmapEx GetPreviewBitmap (
 106         const CacheKey aKey,
 107         const bool bResize);
 108
 109     BitmapEx GetMarkedPreviewBitmap (
 110         const CacheKey aKey);
 111     void SetMarkedPreviewBitmap (
 112         const CacheKey aKey,
 113         const BitmapEx& rBitmap);
 114
 115     /** When the requested preview bitmap does not yet exist or is not
 116         up-to-date then the rendering of one is scheduled.  Otherwise this
 117         method does nothing.
 118     */
 119     void RequestPreviewBitmap (const CacheKey aKey);
 120
 121     /** Tell the cache that the bitmap associated with the given request
 122         data is not up-to-date anymore.  This will invalidate all previews
 123         in other caches that represent the same page as well.
 124         A new preview is requested and will lead
 125         eventually to a repaint of the associated page object.
 126     */
 127     void InvalidatePreviewBitmap (const CacheKey aKey);
 128
 129     /** Call this method when all preview bitmaps have to be generated anew.
 130         This is the case when the size of the page objects on the screen has
 131         changed or when the model has changed.
 132     */
 133     void InvalidateCache ();
 134
 135     /** With the precious flag you can control whether a bitmap can be
 136         removed or reduced in size to make room for other bitmaps or is so
 137         precious that it will not touched.  A typical use is to set the
 138         precious flag for exactly the visible pages.
 139     */
 140     void SetPreciousFlag (const CacheKey aKey, const bool bIsPrecious);
 141
 142     void Pause();
 143     void Resume();
 144
 145 private:
 146     std::unique_ptr<GenericPageCache> mpImplementation;
 147 };
 148
 149 } } } // end of namespace ::sd::slidesorter::cache
 150
 151 #endif
 152
 153 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */