Warning, /office/calligra/libs/textlayout/DESCRIPTION.txt is written in an unsupported language. File is not indexed.
0001 The text layout framework 0002 ------------------------- 0003 The data of the document is stored in a QTextDocument (with some resouces set by the KoTextDocument helper class) The styles are stored in a KoStyleManager, and we have some other managers and helpers as needed. 0004 0005 The layout of that document is handled by the KoTextDocumentLayout class. It builds a series of KoTextLayoutRootArea which roughly corresponds to a page, but since this is completely abstract such a root area could also be the cell in a spreadsheet. For both the spreadsheet case and a normal textshape only a single root area is created, but for Words we can create many root areas. 0006 0007 A KoTextLayoutRootArea is a subclass of KoTextLayoutArea which is the main worker of text layout. Basically it represents the layout of a series of paragraphs. If there is a table in between the paragraphs it will create a new area, namely a KoTextLayoutTableArea. 0008 0009 A KoTextLayoutTableArea holds a KoTextLayoutArea for each of the cells. 0010 0011 Now if a table or paragraph is visible on more than one root area (page) then it is represented by one area for each page. So it is _not_ the same area but a new one that just start where the previous area ended (due to the page break). 0012 0013 0014 How we create a new KoTextLayoutRootArea 0015 ---------------------------------------- 0016 The KoTextDocumentLayout doesn't just create a new KoTextLayoutRootArea whenever it needs to. First of all it keeps a list of the root areas it already have, and only that number of root ares is too small or large do we add/remove root areas. 0017 0018 The actual adding/removing of areas is done by the abstract class KoTextLayoutRootAreaProvider. It has a simple implementation in the TextShape that can only return one root area and that is it. It corresponds to there only being one textshape. 0019 0020 In Words every KWTextFrameSet has an own KWRootAreaProvider. This way headers, footers and the main text have different providers. The provider can depend on each other to allow layouting in a defined order. 0021 0022 In Calligra Sheets it would also be a simple provider with a root area corresponding to a cell. 0023 0024 0025 Trigging of (re)layout 0026 ---------------------- 0027 In order to always have an up to date layout of the current QTextDocument we have a system of marking root areas as dirty. 0028 A root area can be marked as dirty in several ways: 0029 * through KoTextDocumentLayout::documentChanged () which is called by Qt 0030 - this goes through all the root areas and marks them as dirty as needed 0031 * when any calls setDirty() on a root area (eg a shape does this when changing 0032 size og having collisions 0033 0034 When a root area is marked as dirty it asks the KoTextDocumentLayout to emit a signal (layoutIsDirty) which other people can react to. The plain TextShape just connects that signal to KoTextDocumentLayout::scheduleLayout(). This will schedule a layout for later using QTimer::singleShot. If multiple layouts are scheduled they will be compressed to one single layout run. 0035 0036 The KoTextDocumentLayout class provides the two methods layout() and scheduleLayout(). The first allows synchronous and the second asynchronous layouting. 0037 0038 On layouting all root areas are checked if they are dirty. Those who are will be relayouted. If a root area is relayouted then the change may effect other root areas. This will be detected cause every root area keeps information where content started and ended using the FrameIterator class. 0039 0040 0041 FrameIterator and TableIterator 0042 ------------------------------- 0043 0044 Iterators are used to mark positions within a QTextDocument. Every root area has a start- and end-iterator that presents a view on a part of the document. 0045 0046 The start-iterator of a root area is the end-iterator of the previous root area. 0047 0048 During layouting every root area becomes dirty and will be relayouted if the start-iterator doesn't match any longer to the end-iterator of the previous root area. This makes it possible to propagate changes within a root area as result of a relayout forward.