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