Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version

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

1.0 The Rich Text Interactive 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.

2.0 The Rich Text Programmatic Interface

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

Text-Formatting Functions --- Individual Format Parameters

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

Accessing Rich Text Strings

Functions for reading and Writing Rich Text Files

Clipboard-Related Functions

Support for Hypertext Links

Miscellaneous Functionality

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version