rich-text-pane

rich-text-pane Class

Summary

A text pane with extended formatting.

Package

capi

Superclasses

Initargs

`:character-format`	A plist.
`:paragraph-format`	A plist.
`:change-callback`	A function called when a change is made.
`:protected-callback`
	A function determining whether the user may edit a protected part of the text, on Microsoft Windows.
`:filename`	A file to display.
`:text`	A string or `nil`.
`:text-limit`	An integer.
`:link-callback`	Windows only: A function designator, `:open` (the default), `:ignore` or `nil`.

Accessors

rich-text-pane-change-callback
rich-text-pane-limit
rich-text-pane-text

Description

The class rich-text-pane provides a text editor which supports character and paragraph formatting of its text.

character-format is the default character format. It is a plist which is interpreted in the same way as the attributes-plist argument of set-rich-text-pane-character-format. The default value of character-format is nil.

paragraph-format is the default paragraph format. It is a plist which is interpreted in the same way as the attributes-plist argument of set-rich-text-pane-paragraph-format. The default value of paragraph-format is nil.

change-callback, if non-nil, is a function of two arguments: the pane itself, and a keyword denoting the type of change. This second argument is either :text or :selection. The default value of change-callback is nil.

protected-callback, if supplied, is called when the user tries to modify protected text. (Text is protected by setting the protected attribute, see set-rich-text-pane-character-format.) protected-callback must be a function of four arguments: the pane itself, bounding indexes of the protected text, and a boolean which is true when the change would affect the selection. If the change would affect just a single character, this last argument is nil. If protected-callback returns nil, then the change is not performed. If protected-callback is not supplied, then the user cannot modify protected text. protected-callback is supported only on Microsoft Windows.

filename, if non-nil, should be a string or pathname naming a file to display in the pane. filename takes precedence over text if both are non-nil.

text, if non-nil, should be a string which is displayed in the pane if filename is nil.

text-limit, if non-nil, should be an integer which is an upper bound for the length of text displayed in the pane.

link-callback can be used on Windows to control what happens when the user clicks on a link in the text. By default, LispWorks opens the link in the default browser. link-callback can be used to change this behavior. :open and nil give the default behaviour. :ignore means that LispWorks ignores gestures for the hyperlink. Otherwise, link-callback must be a function designator that takes three arguments: the pane, the gesture that the user entered, and the URL of the hyperlink (a string). The gesture conforms to the syntax of the input model as described in 12.2 Receiving input from the user. Currently it is always either the keyword :motion, or a list specifying a button mapping as in 12.2.1.3 Button mappings. link-callback should do any processing that is required, including opening the URL if appropriate. When the cursor is moved outside of a link, link-callback is called with getsure :motion and the URL is nil.

Notes

rich-text-pane is supported only on Microsoft Windows, and Cocoa in macOS 10.3 and later. Some of its features are supported only on Microsoft Windows, as mentioned above.
change-callback and protected-callback are not yet implemented on Cocoa.
The functions that are specific to rich-text-pane cannot be called before the pane is created. If you need to perform operations on the pane before it appears, and which cannot be performed using the initargs, the best approach is to define an :after method on interface-display on the class of the interface containing the rich-text-pane, and perform the operations inside this method.

Examples

For an example of using rich-text-pane, see:

(example-edit-file "capi/applications/rich-text-editor")