richtextoverview.tex

很牛的GUI源码wxWidgets-2.8.0.zip 可在多种平台下运行.

\section{wxRichTextCtrl overview}\label{wxrichtextctrloverview}

{\bf Major classes:} \helpref{wxRichTextCtrl}{wxrichtextctrl}, \helpref{wxRichTextBuffer}{wxrichtextbuffer}, \helpref{wxRichTextEvent}{wxrichtextevent}

{\bf Helper classes:} \helpref{wxRichTextAttr}{wxrichtextattr}, \helpref{wxTextAttrEx}{wxtextattrex}, 
\helpref{wxRichTextRange}{wxrichtextrange}

{\bf File handler classes:} \helpref{wxRichTextFileHandler}{wxrichtextfilehandler}, \helpref{wxRichTextHTMLHandler}{wxrichtexthtmlhandler}, 
\helpref{wxRichTextXMLHandler}{wxrichtextxmlhandler}

{\bf Style classes:} \helpref{wxRichTextCharacterStyleDefinition}{wxrichtextcharacterstyledefinition}, 
\helpref{wxRichTextParagraphStyleDefinition}{wxrichtextparagraphstyledefinition}, 
\helpref{wxRichTextListStyleDefinition}{wxrichtextliststyledefinition}, 
\helpref{wxRichTextStyleSheet}{wxrichtextstylesheet}

{\bf Additional controls:} \helpref{wxRichTextStyleComboCtrl}{wxrichtextstylecomboctrl}, 
\helpref{wxRichTextStyleListBox}{wxrichtextstylelistbox}, 
\helpref{wxRichTextStyleListCtrl}{wxrichtextstylelistctrl}

{\bf Printing classes:} \helpref{wxRichTextPrinting}{wxrichtextprinting}, 
\helpref{wxRichTextPrintout}{wxrichtextprintout}, 
\helpref{wxRichTextHeaderFooterData}{wxrichtextheaderfooterdata}

{\bf Dialog classes:} \helpref{wxRichTextStyleOrganiserDialog}{wxrichtextstyleorganiserdialog}, 
\helpref{wxRichTextFormattingDialog}{wxrichtextformattingdialog}, 
\helpref{wxSymbolPickerDialog}{wxsymbolpickerdialog}

wxRichTextCtrl 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, wxStyledTextCtrl 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 file capabilities. Custom file formats can be supported by creating additional
file handlers and registering them with the control.

wxRichTextCtrl is largely compatible with the wxTextCtrl API, but extends it where necessary.
The control can be used where the native rich text capabilities of wxTextCtrl 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 wxTextCtrl, whereas this information is readily
available in wxRichTextCtrl. Since it's written in pure wxWidgets, any customizations
you make to wxRichTextCtrl will be reflected on all platforms.

wxRichTextCtrl supports basic printing via the easy-to-use \helpref{wxRichTextPrinting}{wxrichtextprinting} class.
Creating applications with simple word processing features is simplified with the inclusion of\rtfsp
\helpref{wxRichTextFormattingDialog}{wxrichtextformattingdialog}, a tabbed dialog allowing
interactive tailoring of paragraph and character styling. Also provided is the multi-purpose dialog\rtfsp
\helpref{wxRichTextStyleOrganiserDialog}{wxrichtextstyleorganiserdialog} 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 wxRichTextCtrl. It is not native,
so does not behave exactly as a native wxTextCtrl, 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 wxTextCtrl and wxRichTextCtrl, with fewer features in the
former case.

A good way to understand wxRichTextCtrl's capabilities is to compile and run the
sample, {\tt samples/richtext}, and browse the code. The following screenshot shows the sample in action:

$$\image{8cm;0cm}{richtextctrl.gif}$$

\wxheading{Example}\label{wxrichtextctrlexample}

The following code is taken from the sample, and adds text and styles to a rich text control programmatically.

{\small
\begin{verbatim}
    wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl(splitter, wxID_ANY, wxEmptyString, wxDefaultPosition, wxSize(200, 200), wxVSCROLL|wxHSCROLL|wxNO_BORDER|wxWANTS_CHARS);

    wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL);
    wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD);
    wxFont italicFont = wxFont(12, wxROMAN, wxITALIC, wxNORMAL);

    wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL);

    m_richTextCtrl->SetFont(font);

    wxRichTextCtrl& r = richTextCtrl;

    r.BeginSuppressUndo();

    r.BeginParagraphSpacing(0, 20);

    r.BeginAlignment(wxTEXT_ALIGNMENT_CENTRE);
    r.BeginBold();

    r.BeginFontSize(14);
    r.WriteText(wxT("Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting styled text and images"));
    r.EndFontSize();
    r.Newline();

    r.BeginItalic();
    r.WriteText(wxT("by Julian Smart"));
    r.EndItalic();

    r.EndBold();

    r.Newline();
    r.WriteImage(wxBitmap(zebra_xpm));

    r.EndAlignment();

    r.Newline();
    r.Newline();

    r.WriteText(wxT("What can you do with this thing? "));
    r.WriteImage(wxBitmap(smiley_xpm));
    r.WriteText(wxT(" Well, you can change text "));

    r.BeginTextColour(wxColour(255, 0, 0));
    r.WriteText(wxT("colour, like this red bit."));
    r.EndTextColour();

    r.BeginTextColour(wxColour(0, 0, 255));
    r.WriteText(wxT(" And this blue bit."));
    r.EndTextColour();

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

    r.BeginFontSize(14);
    r.WriteText(wxT(" Different font sizes on the same line is allowed, too."));
    r.EndFontSize();

    r.WriteText(wxT(" Next we'll show an indented paragraph."));

    r.BeginLeftIndent(60);
    r.Newline();

    r.WriteText(wxT("Indented paragraph."));
    r.EndLeftIndent();

    r.Newline();

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

    r.BeginLeftIndent(100, -40);
    r.Newline();

    r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter."));
    r.EndLeftIndent();

    r.Newline();

    r.WriteText(wxT("Numbered bullets are possible, again using subindents:"));

    r.BeginNumberedBullet(1, 100, 60);
    r.Newline();

    r.WriteText(wxT("This is my first item. Note that wxRichTextCtrl doesn't automatically do numbering, but this will be added later."));
    r.EndNumberedBullet();

    r.BeginNumberedBullet(2, 100, 60);
    r.Newline();

    r.WriteText(wxT("This is my second item."));
    r.EndNumberedBullet();

    r.Newline();

    r.WriteText(wxT("The following paragraph is right-indented:"));

    r.BeginRightIndent(200);
    r.Newline();

    r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter. An attractive woman came into the cafe, which is nothing remarkable."));
    r.EndRightIndent();

    r.Newline();

    wxArrayInt tabs;
    tabs.Add(400);
    tabs.Add(600);
    tabs.Add(800);
    tabs.Add(1000);
    wxTextAttrEx attr;
    attr.SetFlags(wxTEXT_ATTR_TABS);
    attr.SetTabs(tabs);
    r.SetDefaultStyle(attr);
    
    r.WriteText(wxT("This line contains tabs:\tFirst tab\tSecond tab\tThird tab"));

    r.Newline();
    r.WriteText(wxT("Other notable features of wxRichTextCtrl include:"));

    r.BeginSymbolBullet(wxT('*'), 100, 60);
    r.Newline();
    r.WriteText(wxT("Compatibility with wxTextCtrl API"));
    r.EndSymbolBullet();

    r.WriteText(wxT("Note: this sample content was generated programmatically from within the MyFrame constructor in the demo. The images were loaded from inline XPMs. Enjoy wxRichTextCtrl!"));

    r.EndSuppressUndo();
\end{verbatim}
}

\subsection{Programming with wxRichTextCtrl}