readme.txt
1
2wxRichTextCtrl README
3=====================
4
5Welcome to wxRichTextCtrl. It includes the following functionality:
6
7* Text entry, paragraph wrapping
8
9* Scrolling, keyboard navigation
10
11* Application of character styles:
12
13 bold, italic, underlined, font face, text colour
14
15* Application of paragraph styles:
16
17 left/right indentation, sub-indentation (first-line indent),
18 paragraph spacing (before and after), line spacing,
19 left/centre/right alignment, numbered bullets
20
21* Insertion of images
22
23* Copy/paste
24
25* Undo/Redo with optional batching and undo history suppression
26
27* Named paragraph and character styles management and application
28
29* File handlers allow addition of file formats
30
31* Text saving and loading, XML saving and loading, HTML saving (unfinished)
32
33Sorry, this is a Windows-only demo for now but the code should
34compile on other platforms.
35
36Design
37======
38
39Data is represented by a hierarchy of objects, all derived from
40wxRichTextObject.
41
42The top of the hierarchy is the buffer, a kind of wxRichTextParagraphLayoutBox.
43These boxes will allow flexible placement of text boxes on a page, but
44for now there will be a single box representing the document,
45and this box will a wxRichTextParagraphLayoutBox which contains further
46wxRichTextParagraph objects, each of which can include text and images.
47
48Each object maintains a range (start and end position) measured
49from the start of the main parent box.
50A paragraph object knows its range, and a text fragment knows its range
51too. So, a character or image in a page has a position relative to the
52start of the document, and a character in an embedded text box has
53a position relative to that text box. For now, we will not be dealing with
54embedded objects but it's something to bear in mind for later.
55
56Before display, a changed buffer must have Layout() called on it,
57to do wrapping, alignment etc. Ranges representing wrapped lines are stored
58with each paragraph.
59
60Since wxRichTextBuffer is separate from wxRichTextCtrl, the storage
61and rendering facilities can be used by other controls.
62
63API
64===
65
66It's basically the wxTextCtrl with some additions. There is a new
67wxTextAttrEx class deriving from wxTextAttr, to accomodate new
68style attributes. This could be merged with wxTextAttr. There
69is also a wxRichTextAttr which is similar to wxTextAttrEx but
70doesn't store the font as a wxFont: this allows much more
71efficient operations, especially when querying styles in a
72UI update handler. We would not want to create several new wxFonts
73when querying for italics, bold, etc. every few milliseconds.
74
75See "Functionality specific to wxRichTextCtrl" section in richtextctrl.h.
76
77One addition is Set/GetBasicStyle, which is needed in addition to
78Set/GetDefaultStyle to get the overall style for the buffer
79from which content will inherit (after apply the default style).
80
81wxRichTextRange is a new class representing start and end positions.
82It's used in the implementation so that pieces of content
83know their range, and also in the API in preference to using
84two positions.
85
86What next?
87==========
88
89- Decision about where to put it: wxCode, wxWidgets
90- Makefiles/bakefiles
91- Refining the API
92- Documentation
93- Bug fixing/improvements
94
95
96See todo.txt for a list of bugs, improvements and features,
97and also TODO throughout the source.
98
99==
100Julian Smart, October 18th 2005
101