About rich text editing in Common Graphics
This document contains the following sections:
1.0 The Rich Text Interactive Interface
2.0 The Rich Text Programmatic Interface
Getting Started
Invoke the
File |
New Form
menu
command and select rich-edit-dialog from the list of choices. This
will make a rich-edit-dialog form and will automatically add a
rich-edit control and an associated rich-edit-ruler
just above it to the form, and also add auxiliary widgets in a toolbar
for use with the rich-edit control.
This dialog will act as a complete WordPad-like application. If
you would like to add additional controls to the form or toolbar, you
can do so. The rich-edit
controls appear at the right end of the component toolbar. Note that
if multiple rich-edit controls are added to a single form, the single
set of rich-edit helper controls works for all of the rich-edit
controls on the same parent window, reflecting the rich-edit that most
recently had the keyboard focus.
Try running the initial rich-edit form (with that form selected, click
on Run | Run
Form), then clicking the Open button in the toolbar and
selecting the file cg\rich-edit-sample.rtf (in the cg subdirectory of
the main Allegro directory). This should show some sample rich text.
Building Rich Edit Forms from Scratch
To test making your own rich edit dialog from scratch, invoke the
File | New
Form command, and select dialog from the list of window
classes that you can create. Double click the interior of the new form
to inspect it.
If you would like to start the menu-bar off with the special rich-edit
commands, then go to the menu property of the form in the inspector
and enter #.(rich-edit-menubar) in the inspector line for the menu
property. (The #. reader macro is a trick to evaluate the expression
typed directly into a line of the inspector.) This should add the
standard rich-edit menu-bar to the form, and you can further edit this
menu as you like.
Back on the inspector, toggle the toolbar property on to give the form
a toolbar. Also toggle the status-bar property to give the form a
status-bar for messages. Next, click on the Rich-Edit button of the
Component Toolbar (the one with a big green "R"), and then click in
the main interior of your form to create a rich-edit control. You may
want to size the rich-edit control larger, since the default size is
rather small. Now click on each of the next three rich-edit "helper"
controls on the Component Toolbar and instantiate those widgets from
left to right on the toolbar of your new form. (The helper controls
consist of the rich-edit-multipic
, the font-face-combo-box
,
and the font-size-combo-box
. Finally,
click on the Ruler button on the Component Toolbar, position it just
above the rich-edit control, and then drag it or stretch it partly
over the rich-edit as needed to make it snap into place along the top.
Having done this, you now have a dialog that is functionally similar
to the one created by using the rich-edit-dialog class. You can
customize either however you like by adding additional controls and
editing the initial rich-edit menubar. Note that only a
rich-edit-dialog has the built-in feature of prompting the user to
save any unsaved rich-edit controls when a closing gesture is made.
Special Features
While the rich edit functionality basically allows for custom
WordPad-like applications, there are a couple of features that are
somewhat unique:
Multiple editor panes. The rich-edit helper controls will
automatically keep track of which rich-edit control most recently had
the keyboard focus, and apply any editing commands to that
rich-edit. Also, as the focus moves from one rich-edit to another, the
rich edit helper controls will update themselves to reflect the
current rich-edit, just as they update to reflect the currently
selected text within a single rich-edit.
Copying formatting. The Edit menu (on the rich-edit-dialog) has a
couple of items called Copy Format and Paste Format that allow you to
easily copy character formatting rather than text. Just select some
text (or position the text cursor), invoke Edit | Copy Format, then
select some other text, and invoke Edit | Paste Format (again, these
commands are on the Edit menu on the rich-edit-dialog, not on the
Allegro CL Edit menu) The second text range will now have the
character formatting of the first text range.
Package of symbols
All symbols documented here are exported from the common-graphics (cg)
package, since this is an extension to common graphics.
Widgets (controls) versus windows
Most of these commands work on a window (the new rich-edit-pane and/or
the older text-edit-pane
) rather than on a
widget. If you are using a widget instead (the new rich-edit control
or the older multi-line-editable-text
control), then you first need to call the function
window on the
control to retrieve the window of the control, and then pass that to
the function that expects a window.
Rich-edit-specific classes versus plain-text classes
Much of this functionality works using the pre-existing text-edit-pane
windows
and multi-line-editable-text
controls. The corresponding newer classes, rich-edit-pane and the
rich-edit control, are provided mostly for automatically linking up
with text-formatting controls, for determining which type of text is
pasted into a given control, and other potential circumstances in
which the controls will need to default either to rich or plain
text. Thus, anything that's documented here to work on a text-edit-pane
will
also work on a rich-edit-pane, and anything that works on a multi-line-editable-text
will also work on a rich-edit. But note that the converse is not true.
Units of measurement
Most measurements here are in points. A point is approximately 1 /
72nd of an inch. This applies even to font sizes, which are usually
measured in pixels in common graphics, but there does not appear to be
a feasible way to convert character formatting measurements to pixels,
and so this difference needs to be kept in mind. Therefore the
functions font
and (setf font)
should not be used to change the
font of a rich-edit-pane, instead the rich-edit functions that change
individual font attributes should be used, such as (setf face) and set-character-format. Note that a
list of available faces is returned by (font-faces (screen
*system*))
. See font-faces, screen, and *system*
.
Text-Formatting Functions --- Multiple Format Parameters
-
get-character-format returns as
multiple values information about rich text. The scope keyword
argument is either :default (return the default characteristics of
text in the rich-text-pane) or :selection (return information about
the selected text in a rich-edit-pane). The information is the font
face, whether it is bold, italic, underlined, and its color, and
point-size. (See face, bold, italic, underline, color, and point-size). When scope
is :selection, the information is about the first character of
selected text and additional returned values say whether the whole
selection shares the characteristic with the first character.
-
set-character-format
sets the format of text.
-
get-paragraph-format
returns information about the formatting of paragraphs in rich text.
-
set-paragraph-format
sets the paragraph format of a rich-edit-pane.
-
character-format
returns a
character-format
instance representing the character format of the character just
before the current text cursor position in a rich-edit-pane.
-
(setf character-format) sets the
character formatting of the currently selected text of a
rich-edit-pane to reflect an argument
character-format
instance.
-
copy-character-format sets the
global variable
*copied-character-format*
to a
character-format
instance reflecting the character format of the character just before
the current text cursor position in a window.
-
paste-character-format sets the
character format of the currently selected text in a window to reflect
the
character-format
instance that is
currently the value of the global variable *copied-character-format*
.
Text-Formatting Functions --- Individual Format Parameters
-
bold returns true
if all of the selected range of a text-edit-pane is bold, nil if it is
all non-bold, and :some if there is a mix. (setf bold) sets
whether selected text is bold or not.
-
italic returns
true if all of the selected range of a text-edit-pane is italic, nil
if it is all non-italic, and :some if there is a mix. (setf
italic) sets whether selected text is italic or not.
-
underline returns
true if all of the selected range of a text-edit-pane is underlined, nil
if it is all not underlined, and :some if there is a mix. (setf
underline) sets whether selected text is underlined or not.
-
color returns two
values: (1) an rgb object for the color of the first character in the
selected range of a text-edit-pane (or the character at the cursor),
and (2) non-nil if and only if the whole selection is the same
color. (setf
color) sets the color of the selected range of a
text-edit-pane to an rgb color object.
-
face returns two
values: (1) the font face of the first character of the selected range
of text-edit-pane as a keyword, and (2) non-nil if and only if the
entire selection is the same font face.
(setf face)
sets the font face of the selected range of text-edit-pane to a
specified font face. (font-faces (screen
*system*))
returns the available face names that may be
passed to (setf face)
. See face, font-faces, screen, and *system*
.
-
point-size
returns two values: (1) the font point size of the first character of
the selected range of a text-edit-pane, and (2) non-nil if and only if
the entire selection is the same point-size. (setf point-size) sets
the font point size of the selected range of a text-edit-pane (the new
value should be an integer).
-
justification
returns the paragraph justification of the selected text of a
text-edit-pane. The value can be :left, :center, or :right. (setf
justification) sets the paragraph justification
of the selected text.
-
numbering-style
returns the paragraph numbering style of the selected text of a
text-edit-pane. The value can be either :plain or :bullets. (setf
numbering-style) sets the paragraph numbering
style of the selected text of a text-edit-pane.
-
top-left-indentation returns the
left indentation of the first line of the first paragraph of the
selected text of a text-edit-pane. The value is the distance rightward
from the interior left edge of text-edit-pane (or the printed page),
and is specified in points. (setf
top-left-indentation) sets the left
indentation of the first line of each paragraph of the selected text
of a text-edit-pane.
-
body-left-indentation the current
indentation of the lefthand side of a paragraph of text in a
text-edit-pane
, or the
indentation indicated by the corresponding lower-left slider of a
rich-edit-ruler
.
-
right-indentation
returns the right indentation of the first paragraph of the selected
text of a text-edit-pane. The value is the distance leftward from the
interior right edge of text-edit-pane (or the printed page), and is
specified in points. (setf
right-indentation) sets it.
-
tabs returns
a list of tabstop positions for a text-edit-pane or a rich-edit
control, indicating to where text will move rightward wherever a tab
character appears in the text. (setf tabs) sets
tabstop positions.
Responding to Format Changes
on-format-change is
an event handler for rich-edit controls. Its value should be a
function that will be called when formatting changes are made.
Rich Edit Classes
-
rich-edit-pane
is a text-edit-pane
that will automatically link up with any rich-edit formatting controls
that are either on the same parent or on a toolbar of the parent.
-
rich-edit
is
the control built on rich-edit-pane
.
-
rich-edit-dialog
is a dialog intended for use with rich-edit controls.
-
rich-edit-menubar
is a useful associated function. It returns a menubar suitable for use
on a dialog that has one or more rich-edit controls.
-
rich-edit-multipic
is a multi-picture-button
that will automatically link up with any rich-edit controls that are
on the same dialog, in order to edit the character and paragraph
formatting of the rich-edit control(s).
-
font-face-combo-box
is a combo-box
that will automatically link up with any rich-edit controls that are
on the same dialog, in order to edit the font face of the rich-edit
control(s).
-
font-size-combo-box
is a combo-box
that will automatically link up with any rich-edit controls that are
on the same dialog, in order to edit the font size of the rich-edit
control(s). The font-size-combo-box may optionally be on a toolbar.
-
rich-edit-ruler
is a widget that reflects and controls the indentation and tabstops of
the selected paragraph(s) of its associated rich-edit control.
-
character-format
is an object that contains a set of character format parameters.
Accessing Rich Text Strings
-
rich-edit-range
returns a rich-text or plain string from a window. With setf it sets a
string in a window. start and
end arguments control what is read or set.
-
rich-edit-selected-range
is similar to rich-edit-range but works on the selected text of a
window and does not have start and
end arguments.
Functions for reading and Writing Rich Text Files
-
rich-edit-new clears a
rich-edit-pane for editing a new file.
-
rich-edit-open reads
a new file into a rich-edit-pane for editing.
-
rich-edit-save saves
the contents of a rich-edit-pane to its file.
-
rich-edit-save-as
saves the contents of a rich-edit-pane to a new file.
-
save-text creates a file
containing a specified string (either a plain-text or rich-text
string).
-
read-text returns a lisp
string containing the contents of a file, which may be either a
plain-text or rich-text file.
-
rich-edit-print
prints the contents of rich-edit-pane to a printer.
-
print-rich-text
prints all or part of the text of a rich-edit-pane to a
printer-stream.
Clipboard-Related Functions
-
available-clipboard-formats
returns a list of the clipboard formats that are currently on the
Windows clipboard.
-
can-paste returns non-nil
if pasting particular formats (specified by the second argument) is
possible.
-
clipboard-string
gets or sets (with setf) a string from the Windows clipboard.
-
default-clipboard-format
returns the clipboard format that will be used by default when
copying, cutting, and pasting in a window.
Support for Hypertext Links
-
color-string-at-index
returns two values unless the text just before the index is black, in
which case a single nil is returned. The two values returned are (1)
the string that surrounds the character at the argument index and
which is in the color of the rich-edit-pane at that position (in other
words, the color of the character just before the index position), and
(2) the color of the string as an RGB color object.
-
color-string-at-cursor calls
color-string-at-index
with the location of the cursor as the index.
-
find-links finds all of
the substrings of a certain color on a rich-edit-pane and returns a list
indicating the starting and ending indices of each string.
-
links returns the
list of links that were found by find-links and cached as
the value of this property of a rich-edit-pane.
-
save-links
returns (or sets with setf) whether a rich-edit-pane will currently
save its links into a .lin links file whenever rich-edit-save or rich-edit-save-as is called on it.
-
jump-to-links is
a property of a
rich-edit-pane
that determines whether jumping to links is enabled.
-
save-links-file
saves the current links of a rich-edit-pane to a file.
-
read-links-file
reads the links that were saved to an argument file and establishes
them as the current links of an argument rich-text-pane.
-
link-color
returns (or sets with setf) the color that will be used by default
when find-links
is called to find all of the link strings in a rich-edit-pane. The
link-color defaults to
blue
.
-
link-at-mouse-cursor
returns the link under the mouse cursor in a rich-edit-pane, if any.
-
link-at-position
returns the link at a certain pixel position in the interior of a
rich-edit-pane, if any.
-
link-at-text-cursor
returns the link at the current text cursor position of a
rich-edit-pane, if any.
-
link-at-index returns
the link at a certain character index, if any.
-
character-index-at-position
returns the character index at a certain pixel position in the
interior of a text-edit-pane.
-
jump-to-link is
called when the user clicks on a link that has earlier been found by
find-links and
cached as the links property of a rich-edit-pane.
-
pathname-for-link
takes a link-string that was clicked on in a rich-edit-pane, and
should return the path of an .rtf file that should be opened for that
link.
Miscellaneous Functionality
-
concatenate-rich-text takes any
number of rich-text-strings as arguments and returns a single
rich-text-string which is a concatenation of them all. Note that
concatenate
will not work properly with rich-text-strings.
-
find-rich-edit-pane
can be used to find a rich-edit-pane that has or most recently had
keyboard focus on a window, its parent, and so on until a top-level
window is searched.
-
rich-to-plain-text creates and returns
a plain-text string that is equivalent to the argument
rich-text-string except without any formatting.
-
plain-to-rich-text
creates and returns a rich-text string with the text of a
specified plain-text string.
-
get-selection returns
two values indicating the start and end of the current selection of a
text-edit-pane.
-
set-selection sets the
selection of a text-edit-pane.