1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef SD_SLIDESORTER_PAGE_CACHE_HXX
25 #define SD_SLIDESORTER_PAGE_CACHE_HXX
26 
27 #include "cache/SlsCacheContext.hxx"
28 #include <sal/types.h>
29 #include <tools/gen.hxx>
30 #include <boost/scoped_ptr.hpp>
31 #include <vcl/bitmap.hxx>
32 
33 
34 namespace sd { namespace slidesorter { namespace view {
35 class PageObjectViewObjectContact;
36 } } }
37 
38 namespace sd { namespace slidesorter { namespace cache {
39 
40 class GenericPageCache;
41 class RequestData;
42 
43 /** The page cache is responsible for the creation and storage of preview
44     bitmaps of pages that are shown by the slide sorter.
45 
46     <p>Bitmaps for previews and a cache are used to speed up the display
47     (painting) of the slide sorter.  But, of course, we have to limit this
48     time-space-tradeoff by limiting the amount of space that can be use to
49     store bitmaps.</p>
50 
51     <p>There are several strategies employed by this class to shorten the
52     perceived time that is used to paint the slide sorter:
53     <ul>
54     <li>Rendering pages ahead of time.  Additionally to rendering the
55     visible slides we try to render part or all of the slides that are not
56     (yet) visible.  This, of course, makes sense only when the computer is
57     ohterwise idle while doing that.</li>
58     <li>When the size of the slides on the screen changes we mark the
59     bitmaps as needing an update but use them while the new bitmap in the
60     correct size is not available.</li>
61     <li>Give the UI the chance to handle user events between the rendering
62     of differe slides.</li>
63     <li>Limit the amount of space that may be used for storing preview
64     bitmaps and throw.</li>
65     </p>
66 
67     <p>There is another somewhat similar methods for requesting new previews:
68     GetPreviewBitmap() schedules a re-rendering (when necessary) and
69     returns the preview what is currently available, either as a preview of
70     the preview or, when nothing has changed since the last call, as the
71     final thing.
72     </p>
73 */
74 class PageCache
75 {
76 public:
77     /** The page chache is created with a reference to the slide sorter so
78         that it has access to both the view and the model and so can fill
79         itself with requests for all or just the visible pages.
80 
81         It is the task of the PageCacheManager to create new objects of this
82         class.
83     */
84     PageCache (
85         const Size& rPreviewSize,
86         const bool bDoSuperSampling,
87         const SharedCacheContext& rpCacheContext);
88 
89     ~PageCache (void);
90 
91     void ChangeSize(
92         const Size& rPreviewSize,
93         const bool bDoSuperSampling);
94 
95     /** Request a preview bitmap for the specified page object in the
96         specified size.  The returned bitmap may be a preview of the
97         preview, i.e. either a scaled (up or down) version of a previous
98         preview (of the wrong size) or an empty bitmap.  In this case a
99         request for the generation of a new preview is created and inserted
100         into the request queue.  When the preview is available in the right
101         size the page shape will be told to paint itself again.  When it
102         then calls this method again if receives the correctly sized preview
103         bitmap.
104         @param rRequestData
105             This data is used to determine the preview.
106         @param bResize
107             When <TRUE/> then when the available bitmap has not the
108             requested size, it is scaled before it is returned.  When
109             <FALSE/> then the bitmap is returned in the wrong size and it is
110             the task of the caller to scale it.
111         @return
112             Returns a bitmap that is either empty, contains a scaled (up or
113             down) version or is the requested bitmap.
114     */
115     Bitmap GetPreviewBitmap (
116         const CacheKey aKey,
117         const bool bResize);
118 
119     Bitmap GetMarkedPreviewBitmap (
120         const CacheKey aKey,
121         const bool bResize);
122     void SetMarkedPreviewBitmap (
123         const CacheKey aKey,
124         const Bitmap& rBitmap);
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 (const CacheKey aKey);
131 
132     /** Tell the cache that the bitmap associated with the given request
133         data is not up-to-date anymore.  This will invalidate all previews
134         in other caches that represent the same page as well.
135         @param bRequestPreview
136             When <TRUE/> then a new preview is requested and will lead
137             eventually to a repaint of the associated page object.
138     */
139     void InvalidatePreviewBitmap (
140         const CacheKey aKey,
141         const bool bRequestPreview);
142 
143     /** Call this method when a view-object-contact object is being deleted
144         and does not need (a) its current bitmap in the cache and (b) a
145         requested new bitmap.
146     */
147     void ReleasePreviewBitmap (const CacheKey aKey);
148 
149     /** Call this method when all preview bitmaps have to be generated anew.
150         This is the case when the size of the page objects on the screen has
151         changed or when the model has changed.
152         @param bUpdateCache
153             When this flags is <TRUE/> then requests for updated previews
154             are created.  When it is <FALSE/> the existing previews are only
155             marked as not being up-to-date anymore.
156     */
157     void InvalidateCache (const bool bUpdateCache = true);
158 
159     /** With the precious flag you can control whether a bitmap can be
160         removed or reduced in size to make room for other bitmaps or is so
161         precious that it will not touched.  A typical use is to set the
162         precious flag for exactly the visible pages.
163     */
164     void SetPreciousFlag (const CacheKey aKey, const bool bIsPrecious);
165 
166     void Pause (void);
167     void Resume (void);
168 
169 private:
170     ::boost::scoped_ptr<GenericPageCache> mpImplementation;
171 };
172 
173 } } } // end of namespace ::sd::slidesorter::cache
174 
175 #endif
176