Miscellaneous - The Racket Graphical Interface Toolkit

(begin-busy-cursor) → void?

Changes the cursor to a watch cursor for all windows in the current eventspace. Use end-busy-cursorto revert the cursor back to its previous state. Calls tobegin-busy-cursor andend-busy-cursorcan be nested arbitrarily.

The cursor installed by begin-busy-cursor overrides any window-specific cursors in-stalled withset-cursor.

5 Editors

The editor toolbox provides a foundation for two common kinds of applications:

• Programs that need a sophisticated text editor — The simple text field control is in-adequate for text-intensive applications. Many programs need editors that can handle multiple fonts and non-text items.

• Programs that need a canvas with dragable objects — The drawing toolbox provides a generic drawing surface for plotting lines and boxes, but many applications need an interactive canvas, where the user can drag and resize individual objects.

Both kinds of applications need an extensible editor that can handle text, images, programmer-defined items, and even embedded editors. The difference between them is the layout of items. The editor toolbox therefore provides two kinds of editors via two classes:

• text%— in a text editor, items are automatically positioned in a paragraph flow.

• pasteboard%— in a pasteboard editor, items are explicitly positioned and dragable.

This editor architecture addresses the full range of real-world issues for an editor—including cut-and-paste, extensible file formats, and layered text styles—while supporting a high level of extensibility. Unfortunately, the system is fairly complex as a result, and using the editor classes effectively requires a solid understanding of the structure and terminology of the editor toolbox. Nevertheless, enough applications fit one (or both) of the descriptions above to justify the depth and complexity of the toolbox and the learning investment required to use it.

A brief example illustrates how editors work. To start, an editor needs aneditor-canvas%

to display its contents. Then, we can create a text editor and install it into the canvas:

(define f (new frame% [label "Simple Edit"]

[width 200]

[height 200])) (define c (new editor-canvas% [parent f])) (define t (new text%))

(send c set-editor t) (send f show #t)

At this point, the editor is fully functional: the user can type text into the editor, but no cut-and-paste operations are available. We can support all of the standard operations on an editor via the menu bar:

(define mb (new menu-bar% [parent f]))

(define m-edit (new menu% [label "Edit"] [parent mb])) (define m-font (new menu% [label "Font"] [parent mb])) (append-editor-operation-menu-items m-edit #f)

(append-editor-font-menu-items m-font)

Now, the standard cut and paste operations work, and the user can even set font styles. The user can also insert an embedded editor by selectingInsert Text from the Edit menu; after selecting the menu item, a box appears in the editor with the caret inside. Typing with the caret in the box stretches the box as text is added, and font operations apply wherever the caret is active. Text on the outside of the box is rearranged as the box changes sizes. Note that the box itself can be copied and pasted.

The content of an editor is made up of snips. An embedded editor is a single snip from the embedding editor’s point-of-view. To encode immediate text, a snip can be a single character, but more often a snip is a sequence of adjacent characters on the same line. The find-snipmethod extracts a snip from a text editor:

(send t find-snip 0 'after)

The above expression returns the first snip in the editor, which may be a string snip (for immediate text) or an editor snip (for an embedded editor).

An editor is not permanently attached to any display. We can take the text editor out of our canvas and put a pasteboard editor in the canvas, instead:

(define pb (new pasteboard%)) (send c set-editor pb)

With the pasteboard editor installed, the user can no longer type characters directly into the editor (because a pasteboard does not support directly entered text). However, the user can cut text from elsewhere and paste it into pasteboard, or select one of theInsert menu items in theEdit menu. Snips are clearly identifiable in a pasteboard editor (unlike a text editor) because each snip is separately dragable.

We can insert the old text editor (which we recently removed from the canvas) as an embed-ded editor in the pasteboard by explicitly creating an editor snip:

(define s (make-object editor-snip% t)) ; t is the old text editor (send pb insert s)

An individual snip cannot be inserted into different editors at the same time, or inserted multiple times in the same editor:

(send pb insert s) ; no effect

However, we can make a deep copy of the snip and insert the copy into the pasteboard:

(send pb insert (send s copy))

Applications that use the editor classes typically derive new versions of the text% and pasteboard% classes. For example, to implement an append-only editor (which allows insertions only at the end and never allows deletions), derive a new class fromtext%and override thecan-insert?andcan-delete?methods:

(define append-only-text%

(class text%

(inherit last-position)

(define/augment (can-insert? s l) (= s (last-position))) (define/augment (can-delete? s l) #f)

(super-new)))

5.1 Editor Structure and Terminology

The editor toolbox supports extensible and nestable editors by decomposing an editor as-sembly into three functional parts:

• The editor itself stores the state of the text or pasteboard and handles most events and editing operations. Theeditor<%>interface defines the core editor functionality, but editors are created as instances oftext%orpasteboard%.

• A snip is a segment of information within the editor. Each snip can contain a sequence of characters, a picture, or an interactive object (such as an embedded editor). In a text editor, snips are constrained to fit on a single line and generally contain data of a single type. Thesnip%class implements a basic snip. Other snip classes include string-snip%for managing text,image-snip%for managing pictures, andeditor-snip%

for managing embedded editors.

• A display presents the editor on the screen. The display lets the user scroll around an editor or change editors. Most displays are instances of theeditor-canvas%class, but theeditor-snip%class also acts as a display for embedded editors.

These three parts are illustrated by a simple word processor. The editor corresponds to the text document. The editor object receives keyboard and mouse commands for editing the text. The text itself is distributed among snips. Each character could be a separate snip, or multiple characters on a single line could be grouped together into a snip. The display roughly corresponds to the window in which the text is displayed. While the editor manages the arrangement of the text as it is displayed into a window, the display determines which window to draw into and which part of the editor to display.

Each selectable entity in an editor is an item. In a pasteboard, all selection and dragging operations work on snips, so there is a one-to-one correspondence between snips and items.

In an editor, one snip contains one or more consecutive items, and every item belongs to some snip. For example, in a simple text editor, each character is an item, but multiple adjacent characters may be grouped into a single snip. The number of items in a snip is the snip’s count.

Each place where the insertion point can appear in a text editor is a position. A text editor with n items contains n+1 positions: one position before each item, and one position after the last item.

The order of snips within a pasteboard determines each snip’s drawing plane. When two snips overlap within the pasteboard, the snip that is earlier in the order is in front of the other snip (i.e., the former is drawn after the latter, such that the former snip may cover part of the latter snip).

When an editor is drawn into a display, each snip and position has a location. The location of a position or snip is specified in coordinates relative to the top-left corner of the editor.

Locations in an editor are only meaningful when the editor is displayed.

5.1.1 Administrators

Two extra layers of administration manage the display-editor and editor-snip connections.

An editor never communicates directly with a display; instead, it always communicates with an editor administrator, an instance of theeditor-admin%class, which relays information to the display. Similarly, a snip communicates with a snip administrator, an instance of the snip-admin%class.

The administrative layers make the editor hierarchy flexible without forcing every part of an editor assembly to contain the functionality of several parts. For example, a text editor can be a single item within another editor; without administrators, thetext%class would also have to contain all the functionality of a display (for the containing editor) and a snip (for the embedded editor). Using administrators, an editor class can serve as both a containing and an embedded editor without directly implementing the display and snip functionality.

A snip belongs to at most one editor via a single administrator. An editor also has only one administrator at a time. However, the administrator that connects the an editor to the stan-dard display (i.e., an editor canvas) can work with other such administrators. In particular, the administrator of aneditor-canvas% (each one has its own administrator) can work with othereditor-canvas%administrators, allowing an editor to be displayed in multiple editor-canvas%windows at the same time.

When an editor is displayed by multiple canvases, one of the canvases’ administrators is used as the editor’s primary administrator. To handle user and update events for other canvases, the editor’s administrator is temporarily changed and then restored through the editor’s

set-admin method. The return value of the editor’sget-adminmethod thus depends on the context of the call.

5.1.2 Styles

A style, an instance of thestyle<%>interface, parameterizes high-level display information that is common to all snip classes. This includes the font, color, and alignment for drawing the item. A single style is attached to each snip.

Styles are hierarchical: each style is defined in terms of another style. There is a single root style, named"Basic", from which all other styles in an editor are derived. The difference between a base style and each of its derived style is encoded in a style delta (or simply delta).

In document The Racket Graphical Interface Toolkit (Page 169-182)