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