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