RichTextCtrl Overview

Introduction

RichTextCtrl provides a generic implementation of a rich text editor that can handle different character styles, paragraph formatting, and images.

It’s aimed at editing ‘natural’ language text - if you need an editor that supports code editing, wx.stc.StyledTextCtrl is a better choice.

Despite its name, it cannot currently read or write RTF (rich text format) files. Instead, it uses its own XML format, and can also read and write plain text. In future we expect to provide RTF or OpenDocument file capabilities. Custom file formats can be supported by creating additional file handlers and registering them with the control.

RichTextCtrl is largely compatible with the wx.TextCtrl API, but extends it where necessary. The control can be used where the native rich text capabilities of wx.TextCtrl are not adequate (this is particularly true on Windows) and where more direct access to the content representation is required. It is difficult and inefficient to read the style information in a wx.TextCtrl, whereas this information is readily available in RichTextCtrl. Since it’s written in pure wxWidgets, any customizations you make to RichTextCtrl will be reflected on all platforms.

RichTextCtrl supports basic printing via the easy-to-use RichTextPrinting class. Creating applications with simple word processing features is simplified with the inclusion of RichTextFormattingDialog, a tabbed dialog allowing interactive tailoring of paragraph and character styling. Also provided is the multi-purpose dialog RichTextStyleOrganiserDialog that can be used for managing style definitions, browsing styles and applying them, or selecting list styles with a renumber option.

There are a few disadvantages to using RichTextCtrl. It is not native, so does not behave exactly as a native wx.TextCtrl, although common editing conventions are followed. Users may miss the built-in spelling correction on Mac OS X, or any special character input that may be provided by the native control. It would also be a poor choice if intended users rely on screen readers that would be not work well with non-native text input implementation. You might mitigate this by providing the choice between wx.TextCtrl and RichTextCtrl, with fewer features in the former case.

A good way to understand RichTextCtrl‘s capabilities is to run the sample in the wxPython demo, and browse the code.

Related Classes

Major classes: RichTextCtrl, RichTextBuffer, RichTextEvent

Helper classes: wx.TextAttr,

RichTextRange

File handler classes: RichTextFileHandler, RichTextHTMLHandler, RichTextXMLHandler

Style classes: RichTextCharacterStyleDefinition, RichTextParagraphStyleDefinition, RichTextListStyleDefinition, RichTextStyleSheet

Additional controls: RichTextStyleComboCtrl, RichTextStyleListBox, RichTextStyleListCtrl

Printing classes: RichTextPrinting, RichTextPrintout, RichTextHeaderFooterData

Dialog classes: RichTextStyleOrganiserDialog, RichTextFormattingDialog, SymbolPickerDialog

Code Example

This is taken from the wxPython demo:

import wx
import wx.richtext as rt
import images

#----------------------------------------------------------------------

class RichTextFrame(wx.Frame):

    def __init__(self, *args, **kw):

        wx.Frame.__init__(self, *args, **kw)

        self.MakeMenuBar()
        self.MakeToolBar()
        self.CreateStatusBar()
        self.SetStatusText("Welcome to wx.richtext.RichTextCtrl!")

        self.rtc = rt.RichTextCtrl(self, style=wx.VSCROLL|wx.HSCROLL|wx.NO_BORDER);
        wx.CallAfter(self.rtc.SetFocus)

        self.rtc.Freeze()
        self.rtc.BeginSuppressUndo()

        self.rtc.BeginParagraphSpacing(0, 20)

        self.rtc.BeginAlignment(rt.TEXT_ALIGNMENT_CENTRE)
        self.rtc.BeginBold()

        self.rtc.BeginFontSize(14)
        self.rtc.WriteText("Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting " \
                           "styled text and images")
        self.rtc.EndFontSize()
        self.rtc.Newline()

        self.rtc.BeginItalic()
        self.rtc.WriteText("by Julian Smart")
        self.rtc.EndItalic()

        self.rtc.EndBold()

        self.rtc.Newline()
        self.rtc.WriteImage(images._rt_zebra.GetImage())

        self.rtc.EndAlignment()

        self.rtc.Newline()
        self.rtc.Newline()

        self.rtc.WriteText("What can you do with this thing? ")
        self.rtc.WriteImage(images._rt_smiley.GetImage())
        self.rtc.WriteText(" Well, you can change text ")

        self.rtc.BeginTextColour((255, 0, 0))
        self.rtc.WriteText("colour, like this red bit.")
        self.rtc.EndTextColour()

        self.rtc.BeginTextColour((0, 0, 255))
        self.rtc.WriteText(" And this blue bit.")
        self.rtc.EndTextColour()

        self.rtc.WriteText(" Naturally you can make things ")
        self.rtc.BeginBold()
        self.rtc.WriteText("bold ")
        self.rtc.EndBold()
        self.rtc.BeginItalic()
        self.rtc.WriteText("or italic ")
        self.rtc.EndItalic()
        self.rtc.BeginUnderline()
        self.rtc.WriteText("or underlined.")
        self.rtc.EndUnderline()

        self.rtc.BeginFontSize(14)
        self.rtc.WriteText(" Different font sizes on the same line is allowed, too.")
        self.rtc.EndFontSize()

        self.rtc.WriteText(" Next we'll show an indented paragraph.")

        self.rtc.BeginLeftIndent(60)
        self.rtc.Newline()

        self.rtc.WriteText("It was in January, the most down-trodden month of an Edinburgh winter. " \
                           "An attractive woman came into the cafe, which is nothing remarkable.")
        self.rtc.EndLeftIndent()

        self.rtc.Newline()

        self.rtc.WriteText("Next, we'll show a first-line indent, achieved using BeginLeftIndent(100, -40).")

        self.rtc.BeginLeftIndent(100, -40)
        self.