sd/source/ui/slidesorter/inc/cache/SlsPageCache.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: SlsPageCache.hxx,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef SD_SLIDESORTER_PAGE_CACHE_HXX
  32 #define SD_SLIDESORTER_PAGE_CACHE_HXX
  33
  34 #include "cache/SlsCacheContext.hxx"
  35 #include <sal/types.h>
  36 #include <vcl/bitmapex.hxx>
  37 #include <boost/function.hpp>
  38 #include <boost/scoped_ptr.hpp>
  39 #include <boost/shared_ptr.hpp>
  40
  41 namespace sd { namespace slidesorter { namespace view {
  42 class PageObjectViewObjectContact;
  43 } } }
  44
  45 namespace sd { namespace slidesorter { namespace cache {
  46
  47 class GenericPageCache;
  48 class RequestData;
  49
  50 /** The page cache is responsible for the creation and storage of preview
  51     bitmaps of pages that are shown by the slide sorter.
  52
  53     <p>Bitmaps for previews and a cache are used to speed up the display
  54     (painting) of the slide sorter.  But, of course, we have to limit this
  55     time-space-tradeoff by limiting the amount of space that can be use to
  56     store bitmaps.</p>
  57
  58     <p>There are several strategies employed by this class to shorten the
  59     perceived time that is used to paint the slide sorter:
  60     <ul>
  61     <li>Rendering pages ahead of time.  Additionally to rendering the
  62     visible slides we try to render part or all of the slides that are not
  63     (yet) visible.  This, of course, makes sense only when the computer is
  64     ohterwise idle while doing that.</li>
  65     <li>When the size of the slides on the screen changes we mark the
  66     bitmaps as needing an update but use them while the new bitmap in the
  67     correct size is not available.</li>
  68     <li>Give the UI the chance to handle user events between the rendering
  69     of differe slides.</li>
  70     <li>Limit the amount of space that may be used for storing preview
  71     bitmaps and throw.</li>
  72     </p>
  73
  74     <p>There are three somewhat similar methods for requesting new previews:
  75     a) GetPreviewBitmap() schedules a re-rendering (when necessary) and
  76     returns the preview what is currently available, either as a preview of
  77     the preview or, when nothing has changed since the last call, as the
  78     final thing.
  79     b) RequestPreviewBitmap() schedules, like GetPreviewBitmap(), a
  80     re-rendering when the currently available preview is not up-to-date.  It
  81     does not, however, return anything.  Use this if you can wait for the
  82     preview.
  83     c) InvalidatePreviewBitmap() does not schedule a re-rendering, but
  84     remembers that one is necessary when one of the other two methods is
  85     called.
  86     </p>
  87 */
  88 class PageCache
  89 {
  90 public:
  91     /** The page chache is created with a reference to the slide sorter so
  92         that it has access to both the view and the model and so can fill
  93         itself with requests for all or just the visible pages.
  94
  95         It is the task of the PageCacheManager to create new objects of this
  96         class.
  97     */
  98     PageCache (
  99         const Size& rPreviewSize,
 100         const SharedCacheContext& rpCacheContext);
 101
 102     ~PageCache (void);
 103
 104     void ChangeSize(const Size& rPreviewSize);
 105
 106     /** Request a preview bitmap for the specified page object in the
 107         specified size.  The returned bitmap may be a preview of the
 108         preview, i.e. either a scaled (up or down) version of a previous
 109         preview (of the wrong size) or an empty bitmap.  In this case a
 110         request for the generation of a new preview is created and inserted
 111         into the request queue.  When the preview is available the page
 112         shape will be told to paint itself again.  When it then calls this
 113         method again if receives the correctly sized preview bitmap.
 114         @param rRequestData
 115             This data is used to determine the preview.
 116         @param rSize
 117             The size of the requested preview bitmap.
 118         @return
 119             Returns a bitmap that is either empty, contains a scaled (up or
 120             down) version or is the requested bitmap.
 121     */
 122     BitmapEx GetPreviewBitmap (
 123         CacheKey aKey,
 124         const Size& rSize);
 125
 126     /** When the requested preview bitmap does not yet exist or is not
 127         up-to-date then the rendering of one is scheduled.  Otherwise this
 128         method does nothing.
 129     */
 130     void RequestPreviewBitmap (
 131         CacheKey aKey,
 132         const Size& rSize);
 133
 134     /** Tell the cache that the bitmap associated with the given request
 135         data is not up-to-date anymore.  Unlike the RequestPreviewBitmap()
 136         method this does not trigger the rendering itself.  It just
 137         remembers to render it when the preview is requested the next time.
 138         @param rRequestData
 139             It is safe to pass a (barly) living object.  It will called only
 140             once to obtain its page object.
 141     */
 142     void InvalidatePreviewBitmap (CacheKey aKey);
 143
 144     /** Call this method when a view-object-contact object is being deleted
 145         and does not need (a) its current bitmap in the cache and (b) a
 146         requested new bitmap.
 147     */
 148     void ReleasePreviewBitmap (CacheKey aKey);
 149
 150     /** Call this method when all preview bitmaps have to be generated anew.
 151         This is the case when the size of the page objects on the screen has
 152         changed or when the model has changed.
 153         @param bUpdateCache
 154             When this flags is <TRUE/> then requests for updated previews
 155             are created.  When it is <FALSE/> the existing previews are only
 156             marked as not being up-to-date anymore.
 157     */
 158     void InvalidateCache (bool bUpdateCache = true);
 159
 160     /** With the precious flag you can control whether a bitmap can be
 161         removed or reduced in size to make room for other bitmaps or is so
 162         precious that it will not touched.  A typical use is to set the
 163         precious flag for exactly the visible pages.
 164     */
 165     void SetPreciousFlag (CacheKey aKey, bool bIsPrecious);
 166
 167     void Pause (void);
 168     void Resume (void);
 169
 170 private:
 171     ::boost::scoped_ptr<GenericPageCache> mpImplementation;
 172 };
 173
 174 } } } // end of namespace ::sd::slidesorter::cache
 175
 176 #endif