samples/richtext/readme.txt

   1
   2 wxRichTextCtrl README
   3 =====================
   4
   5 Welcome 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
  33 Sorry, this is a Windows-only demo for now but the code should
  34 compile on other platforms.
  35
  36 Design
  37 ======
  38
  39 Data is represented by a hierarchy of objects, all derived from
  40 wxRichTextObject.
  41
  42 The top of the hierarchy is the buffer, a kind of wxRichTextParagraphLayoutBox.
  43 These boxes will allow flexible placement of text boxes on a page, but
  44 for now there will be a single box representing the document,
  45 and this box will a wxRichTextParagraphLayoutBox which contains further
  46 wxRichTextParagraph objects, each of which can include text and images.
  47
  48 Each object maintains a range (start and end position) measured
  49 from the start of the main parent box.
  50 A paragraph object knows its range, and a text fragment knows its range
  51 too. So, a character or image in a page has a position relative to the
  52 start of the document, and a character in an embedded text box has
  53 a position relative to that text box. For now, we will not be dealing with
  54 embedded objects but it's something to bear in mind for later.
  55
  56 Before display, a changed buffer must have Layout() called on it,
  57 to do wrapping, alignment etc. Ranges representing wrapped lines are stored
  58 with each paragraph.
  59
  60 Since wxRichTextBuffer is separate from wxRichTextCtrl, the storage
  61 and rendering facilities can be used by other controls.
  62
  63 API
  64 ===
  65
  66 It's basically the wxTextCtrl with some additions. There is a new
  67 wxTextAttrEx class deriving from wxTextAttr, to accomodate new
  68 style attributes. This could be merged with wxTextAttr. There
  69 is also a wxRichTextAttr which is similar to wxTextAttrEx but
  70 doesn't store the font as a wxFont: this allows much more
  71 efficient operations, especially when querying styles in a
  72 UI update handler. We would not want to create several new wxFonts
  73 when querying for italics, bold, etc. every few milliseconds.
  74
  75 See "Functionality specific to wxRichTextCtrl" section in richtextctrl.h.
  76
  77 One addition is Set/GetBasicStyle, which is needed in addition to
  78 Set/GetDefaultStyle to get the overall style for the buffer
  79 from which content will inherit (after apply the default style).
  80
  81 wxRichTextRange is a new class representing start and end positions.
  82 It's used in the implementation so that pieces of content
  83 know their range, and also in the API in preference to using
  84 two positions.
  85
  86 What 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
  96 See todo.txt for a list of bugs, improvements and features,
  97 and also TODO throughout the source.
  98
  99 ==
 100 Julian Smart, October 18th 2005