]> git.lyx.org Git - lyx.git/blob - src/TextCache.h
ws changes only
[lyx.git] / src / TextCache.h
1 // -*- C++ -*-
2 /**
3  * \file TextCache.h
4  * This file is part of LyX, the document processor.
5  * Licence details can be found in the file COPYING.
6  *
7  * \author Lars Gullik Bjønnes
8  *
9  * Full author contact details are available in file CREDITS.
10  */
11
12 #ifndef TEXT_CACHE_H
13 #define TEXT_CACHE_H
14
15 #include <iosfwd>
16 #include <map>
17 #include <string>
18
19 class Buffer;
20 class LyXText;
21
22 // This is only the very first implemetation and use of the TextCache,
23 // operations on it needs to be put into a class or a namespace, that part
24 // is _NOT_ finished so don't bother to come with too many comments on it
25 // (unless you have some nice ideas on where/how to do it)
26 //
27 // I think we need a global TextCache that is common for all BufferViews,
28 // also the BufferList needs access to the TextCache. Please tell if you
29 // don't agree.
30 //
31 // Q. What are we caching?
32 // A. We are caching the screen representations (LyXText) of the
33 //    documents (Buffer,Paragraph) for specific BufferView widths.
34 // Q. Why the cache?
35 // A. It is not really needed, but it speeds things up a lot
36 //    when you have more than one document loaded at once since a total
37 //    rebreak (reformatting) need not be done when switching between
38 //    documents. When the cache is in function a document only needs to be
39 //    formatted upon loading and when the with of the BufferView changes.
40 //    Later it will also be unneccessary to reformat when having two
41 //    BufferViews of equal width with the same document, a simple copy
42 //    of the LyXText structure will do.
43 // Invariant for the TextCache:
44 //        - The buffer of the text  in the TextCache _must_ exists
45 //          in the bufferlist.
46 //        - For a text in the TextCache there _must not_ be an equivalent
47 //          text in any BufferView. (same buffer and width).
48 // Among others this mean:
49 //        - When a document is closed all trace of it must be removed from
50 //          the TextCache.
51 // Scenarios:
52 //    I believe there are only three possible scenarios where the two first
53 //    are also covered by the third.
54 //        - The simplest scenario is what we have now, a single
55 //          BufferView only.
56 //          o Opening
57 //            Nothing to do with the TextCache is done when opening a file.
58 //          o Switching
59 //            We switch from buffer A to buffer B.
60 //            * A's text is cached in TextCache.
61 //            * We make a search for a text in TextCache that fits B
62 //              (same buffer and same width).
63 //          o Horizontal resize
64 //            If the BufferView's width (LyXView) is horizontally changed all
65 //            the entries in the TextCache are deleted. (This causes
66 //            reformat of all loaded documents when next viewed)
67 //          o Close
68 //            When a buffer is closed we don't have to do anything, because
69 //            to close a single buffer it is required to only exist in the
70 //            BufferView and not in the TextCache. Upon LFUN_QUIT we
71 //            don't really care since everything is deleted anyway.
72 //        - The next scenario is when we have several BufferViews (in one or
73 //          more LyXViews) of equal width.
74 //          o Opening
75 //            Nothing to do with the TextCache is done when opening a file.
76 //          o Switching
77 //            We switch from buffer A to buffer B.
78 //            * If A is in another Bufferview we do not put it into TextCache.
79 //              else we put A into TextCache.
80 //            * If B is viewed in another BufferView we make a copy of its
81 //              text and use that, else we search in TextCache for a match.
82 //              (same buffer same width)
83 //          o Horizontal resize
84 //            If the BufferView's width (LyXView) is horisontaly changed all
85 //            the entries in the TextCache is deleted. (This causes
86 //            reformat of all loaded documents when next viewed)
87 //          o Close
88 //        - The last scenario should cover both the previous ones, this time
89 //          we have several BufferViews (in one or more LyXViews) with no
90 //          limitations on width. (And if you wonder why the two other
91 //          senarios are needed... I used them to get to this one.)
92 //          o Opening
93 //            Nothing to do with the TextCache is done when opening a file.
94 //          o Switching
95 //            We switch from buffer A to buffer B.
96 //          o Horisontal rezize
97 //          o Close
98
99 /** This class is used to cache generated LyXText's.
100     The LyXText's is used by the BufferView to visualize the contents
101     of a buffer and its paragraphs. Instead of deleting the LyXText when
102     we switch from one document to another we cache it here so that when
103     we switch back we do not have to reformat. This makes switching very
104     fast at the expense of a bit higher memory usage.
105 */
106 class TextCache {
107 public:
108         ///
109         typedef std::map<Buffer *, std::pair<int,LyXText *> > Cache;
110
111         ///
112         typedef Cache::value_type value_type;
113
114         /** Returns a pointer to a LyXText that fits the provided buffer
115             and width. Of there is no match 0 is returned. */
116         LyXText * findFit(Buffer * b, int p);
117         /** Lists all the LyXText's currently in the cache.
118             Uses msg as header for the list. */
119         void show(std::ostream & o, std::string const & msg);
120         /// Gives info on a single LyXText (buffer and width)
121         static void show(std::ostream & o, value_type const &);
122         /** Adds a LyXText to the cache iff its buffer is
123             present in bufferlist. */
124         void add(Buffer *, int witdth, LyXText *);
125         /** Clears the cache. Deletes all LyXText's and releases
126             the allocated memory. */
127         void clear();
128         /// Removes all LyXText's that has buffer b from the TextCache
129         void removeAllWithBuffer(Buffer * b);
130 private:
131         /// The cache.
132         Cache cache;
133 };
134
135 ///
136 extern TextCache textcache;
137 #endif