Chapter 3

Interface Reference

3.1  Menus

3.1.1  File

• New -- Creates a new DrScheme window.

• Open... -- Opens a find-file dialog for choosing a file to load into a definitions window.

• Open Recent -- Lists recently opened files. Choosing one of them opens that file for editing.

• Install PLT File... -- Opens a dialog asking for the location of the PLT file (either on the local disk or on the web) and installs the contents of the PLT file.

• Revert -- Re-loads the file that is currently in the definitions window. All changes since the file was last saved will be lost.

• Save Definitions -- Saves the program in the definitions window. If the program has never been saved before, a save-file dialog appears.

• Save Definitions As... -- Opens a save-file dialog for choosing a destination file to save the program in the definitions window. Subsequent saves write to the newly-selected file.

• Save Other -- Contains these sub-items

  • Save Definitions As Text... -- Like Save Definitions As..., but the file is saved in plain-text format (see DrScheme Files). Subsequent saves also write in plain-text format.

  • Save Interactions -- Saves the contents of the interactions window to a file. If the interaction constants have never been saved before, a save-file dialog appears.

  • Save Interactions As... -- Opens a save-file dialog for choosing a destination file to save the contents of the interactions window. Subsequent saves write to the newly-selected file.

  • Save Interactions As Text... -- Like Save Interactions As..., but the file is saved in plain-text format (see DrScheme Files). Subsequent saves are write in plain-text format.

• Log Definitions and Interactions... -- Starts a running of log of the text in the interactions and definitions windows, organized by executions. In a directory of your choosing, DrScheme saves files with the names 01-definitions, 01-interactions, 02-definitions, 02-interactions, etc as you interact with various programs.

• Print Definitions... -- Opens a dialog for printing the current program in the definitions window.

• Print Interactions... -- Opens a dialog for printing the contents of the interactions window.

• Search in Files... -- Opens a dialog where you can specify the parameters of a multi-file search. The results of the search are displayed in a separate window.

• Close -- Closes this DrScheme window. If this window is the only open DrScheme window, DrScheme quits.

• Quit or Exit Exits DrScheme. (Under Mac OS X this menu item is in the apple menu.)

3.1.2  Edit

All Edit menu items operate on either the definitions or interactions window, depending on the location of the selection or blinking caret. Each window maintains its own Undo and Redo history.

• Undo -- Reverses an editing action. Each window maintains a history of actions, so multiple Undo operations can reverse multiple editing actions.

• Redo -- Reverses an Undo action. Each window (and boxed-subwindow) maintains its own history of Undo actions, so multiple Redo operations can reverse multiple Undo actions.

• Cut -- Copies the selected text to the clipboard and deletes it from the window.

• Copy -- Copies the selected text to the clipboard.

• Paste -- Pastes the current clipboard contents into the window.

• Delete -- or Clear -- Deletes the selected text.

• Select All -- Highlights the entire text of the buffer.

• Wrap Text -- Toggles between wrapped text and unwrapped text in the window.

• Find... -- Opens a search dialog or, depending on the preferences, an interactive searching window attached to the frame.

• Find Again -- Finds the next occurrence of the text that was last searched for.

• Replace & Find Again -- Replaces the selection with the replace string (if it matches the find string) and finds the next occurrence of the text that was last searched for.

• Keybindings --

  • Show Active Keybindings -- Shows all of the keybindings available in the current window.

  • Add User-defined Keybindings... -- Choosing this menu item opens a file dialog where you can select a file containing Scheme-definitions of keybindings. See Defining Custom Shortcuts for more information.

• Preferences... -- Opens the preferences dialog. See section 3.2. (In Mac OS X, this menu item is under the apple menu.)

3.1.3  View

One each of the following show/hide pairs of menu items appears at any time.

• Show Definitions -- Shows the definitions window.

• Hide Definitions -- Hides the definitions window.

• Show Interactions -- Shows interactions window.

• Hide Interactions -- Hides interactions window.

• Show Program Contour -- Shows a ``20,000 foot'' overview window along the edge of the DrScheme window. Each pixel in this window corresponds to a letter in the program text.

• Hide Program Contour -- Hides the contour window.

• Show Module Browser -- Shows the module DAG rooted at the currently opened file in DrScheme.

• Hide Module Browser -- Hides the module browser.

• Show Toolbar -- Makes the toolbar (along the top of DrScheme's window) and the status line (along the bottom) visible.

• Hide Toolbar -- Hides the toolbar (along the top of DrScheme's window) and the status line (along the bottom).

• Show Profile -- Shows the current profiling report. This menu is useful only if you have enabled profiling in the Choose Language... dialog's Details section. Profiling does not apply to all languages.

• Hide Profile -- Hides any profiling information currently displayed in the DrScheme window.

• Show Tracing -- Shows a trace of functions called since the last time Run was clicked. This menu is useful only if you have enabled tracing in the Choose Language... dialog's Details section. Profiling does not apply to all languages.

• Hide Tracing -- Hides the tracing display.

• Split -- Splits the current window in half to allow for two different portions of the current window to be visible simultaneously.

• Collapse -- If the window has been split before, this menu item becomes enabled, allowing you to collapse the split window.

Note: whenever a program is run, the interactions window is made visible if it is hidden.

3.1.4  Language

• Choose Language... -- Opens a dialog for selecting the current evaluation language. Click Run to make the language active in the interactions window. See section 2.6 for more information about the languages.

• Add Teachpack... -- Opens a find-file dialog for choosing a teachpack to extend the current language. Click Run to make the teachpack available in the interactions windows. See Extending DrScheme for information on creating teachpacks.

• Clear All Teachpacks -- Clears all of the current teachpacks. Click Run to clear the teachpack from the interactions window.

In addition to the above items, a menu item for each teachpack that clears only the corresponding teachpack.

3.1.5  Scheme

• Run -- Resets the interactions window and runs the program in the definitions window.

• Break -- Breaks the current evaluation.

• Kill -- Terminates the current evaluation.

• Clear Error Highlight -- Removes the red background that signals the source location of an error.

• Create Executable... -- Creates a separate launcher for running your program. See Executables for more info.

• Module Browser... -- Prompts for a file and then opens a window showing the module import structure for the module import DAG starting at the selected module.

  The module browser window contains a square for each module. The squares are colored based on the number of lines of code in the module. If a module has more lines of code, it gets a darker color.

  In addition, for each normal import, a blue line drawn is from the module to the importing module. Similarly, purple lines are drawn for each for-syntax import. In the initial module layout, modules to the left import modules to the right, but since modules can be moved around interactively, that property might not be preserved.

  To open the file corresponding to the module, right-click or control-click (Mac OS X) on the box for that module.

• Reindent -- Indents the selected text according to the standard Scheme formatting conventions. (Pressing the Tab key has the same effect.)

• Reindent All -- Indents all of the text in either the definitions or interactions window, depending on the location of the selection or blinking caret.

• Comment Out with Semicolons -- Puts ``;'' characters at each of the the beginning of each selected line of text.

• Comment Out with a Box -- Boxes the selected text with a comment box.

• Uncomment -- Removes all ``;'' characters at the start of each selected line of text or removes a comment box around the text. Uncommenting only removes a ``;'' if it appears at the start of a line and it only removes the first ``;'' on each line.

• Disable All Test Cases -- Disables all test case boxes (see section 2.11)

3.1.6  Special

• Insert Comment Box -- Inserts a box that is ignored by DrScheme; use it to write comments for people who read your program.

• Insert Image... -- Opens a find-file dialog for selecting an image file in GIF, BMP, XBM, XPM, PNG, or JPG format. The image is treated as a value.

• Insert Fraction... -- Opens a dialog for a mixed-notation fraction, and inserts the given fraction into the current editor.

• Insert Large Letters... -- Opens a dialog for a line of text, and inserts a large version of the text (using semicolons and spaces).

• Insert lambda -- Inserts the symbol lambda (as a Unicode character) into the program. The lambda symbol is normally bound the same as lambda.

• Insert Java Comment Box -- Inserts a box that is ignored by DrScheme. Unlike the Insert Comment Box menu item, this is designed for the ProfessorJ language levels. See the ProfessorJ Beginner Language, ProfessorJ Intermediate Language, and ProfessorJ Advanced Language manuals for details.

• Insert Java Interactions Box -- Inserts a box that will allows Java expressions and statements within Scheme programs. The result of the box is a Scheme value corresponding to the result(s) of the Java expressions. At this time, Scheme values cannot enter the box. The box will accept one Java statement or expression per line.

• Insert Java Examples -- Inserts a box that allows field-like definitions in the definitions window. The names created by this box can be used in any definition or test case box that follows and in the Interactions window. This box is intended only for use in the ProfessorJ language levels and should only appear at the top level. See the ProfessorJ Beginner Language, ProfessorJ Intermediate Language, and ProfessorJ Advanced Language manuals for details.

• Insert XML Box -- Inserts an XML; see XML in DrScheme for more information.

• Insert Scheme Box -- Inserts a box to contain Scheme code, typically used inside an XML box; see also XML in DrScheme.

• Insert Scheme Splice Box -- Inserts a box to contain Scheme code, typically used inside an XML box; see also XML in DrScheme.

• Insert Test Case -- Creates a new test case box; see section 2.11.

• Insert Pict Box -- Creates a box for generating a Slideshow picture. Inside the pict box, insert and arrange Scheme boxes that produce picture values.

3.1.7  Windows

• Bring Frame to Front... -- Opens a window that lists all of the opened DrScheme frames. Selecting one of them brings the window to the front.

• Most Recent Window -- Toggles between the currently focused window and the one that most recently had the focus.

Additionally, after the above menu items, this menu contains an entry for each window in DrScheme. Selecting a menu item brings the corresponding window to the front.

3.1.8  Help

• Help Desk -- Opens the Help Desk. This is the clearing house for all documentation about DrScheme and its language.

• About DrScheme... -- Shows the credits for DrScheme.

• Related Web Sites -- Provides links to related web sites.

• Tool Web Sites -- Provides links to web sites for installed tools.

• Interact with DrScheme in English -- Changes DrScheme's interface to use English; the menu item appears only when the current language is not English. Additional menu items switch DrScheme to other languages.

3.2  Preferences

The preferences dialog comprises several panels:

• Font

  This panel controls the main font used by DrScheme.

• Colors

  The Coloring panel has several subpanels that enable you to configure the colors that DrScheme uses for the editor background, for highlighting matching parentheses, for online coloring, and for Check Syntax.

• Background Color

  This panel configures the background color for the editors in DrScheme.

• Editing

  The Editing panel consists of several sub-panels:

  • Indenting

    This panel controls which keywords DrScheme recognizes for indenting, and how each keyword is treated.

  • General

    • Number of recent items -- controls the length of the Open Recent menu (in the File menu).

    • Auto-save files -- If checked, the editor generates autosave files (see DrScheme Files) for files that have not been saved after five minutes.

    • Backup files -- If checked, when saving a file for the first time in each editing session, the original copy of the file is copied to a backup file in the same directory. The backup files have the same name as the original, except that they end in either .bak or ~.

    • Map delete to backspace -- If checked, the editor treats the Delete key like the Backspace key.

    • Show status-line -- If checked, DrScheme shows a status line at the bottom of each window.

    • Count column numbers from one -- If checked, the status line's column counter counts from one. Otherwise, it counts from zero.

    • Display line numbers in buffer; not character offsets -- If checked, the status line shows a line:column display for the current selection rather than the character offset into the text.

    • Wrap words in editor buffers -- If checked, DrScheme editors auto-wrap text lines by default. Changing this preference affects new windows only.

    • Use separate dialog for searching -- If checked, then selecting the Find -- menu item opens a separate dialog for searching and replacing. Otherwise, selecting Find -- opens an interactive search-and-replace panel at the bottom of a DrScheme window.

    • Reuse existing frames when opening new files -- If checked, new files are opened in the same DrScheme window, rather than creating a new DrScheme window for each new file.

    • Enable keybindings in menus -- If checked, some DrScheme menu items have keybindings. Otherwise, no menu items have key bindings. This preference is designed for people who are comfortable editing in Emacs and find the standard menu keybindings interfere with the Emacs keybindings.

    • Color syntax interactively -- If checked, DrScheme colors your syntax as you type.

    • Automatically print to PostScript file -- If checked, printing will automatically save PostScript files. If not, printing will use the standard printing mechanisms for your computer.

    • Open files in separate tabs (not separate windows) - If checked, DrScheme will use tabs in the front-most window to open new files, rather than creating new windows for new files.

    • Automatically open interactions window when running a program - If checked, DrScheme shows the interactions window (if it is hidden) when a program is run.

  • Scheme

    • Highlight between matching parens -- If checked, the editor marks the region between matching parenthesis with a gray background (in color) or a stipple pattern (in monochrome) when the blinking caret is next to a parenthesis.

    • Correct parens -- If checked, the editor automatically converts a typed ``)'' to ``]'' to match ``['', or it converts a typed ``]'' to ``)'' to match ``(``.

    • Flash paren match -- If checked, typing a closing parenthesis, square bracket, or quotation mark flashes the matching open parenthesis/bracket/quote.

• Warnings

  • Ask before changing save format -- If checked, DrScheme consults the user before saving a file in non-text format (see DrScheme Files).

  • Verify exit -- If checked, DrScheme consults the user before exiting.

  • Only warn once when executions and interactions are not synchronized -- If checked, DrScheme warns the user on the first interaction after the definitions window, language, or teachpack is changed without a corresponding click on Run. Otherwise, the warning appears on every interaction.

  • Ask about clearing test coverage -- If checked, when test coverage annotations are displayed DrScheme prompts about removing them. This setting only applies to the PLT languages. DrScheme never asks in the teaching languages.

  • Check for newer PLT Scheme versions -- If checked, DrScheme will periodically poll a server to determine whether a newer version of DrScheme is available.

• Profiling

  This preference panel configures the profiling report. The band of color shows the range of colors that profiled functions take on. Colors near the right are used for code that is not invoked often and colors on the right are used for code that is invoked often.

  If you are interested in more detail at the low end, choose the ``Square root'' check box. If you are interested in more detail at the upper end, choose the ``Square'' check box.

• Browser

  The Use Help Desk browser for external URLs check box determines whether Help Desk visits URLs (out of our documentation) in a platform-specific browser or within Help Desk itself.

  This preferences panel also allows you to configure your HTTP proxy. Contact your system administrator for details.

3.3  Keyboard Shortcuts

Most key presses simply insert a character into the editor (``a'', ``3'', ``('', etc.). Other keys and key combinations act as keyboard shortcuts that move the blinking caret, delete a line, copy the selection, etc. Keyboard shortcuts are usually trigger by key combinations using the Control, Meta, or Command key.

C-key = This means press the Control key, hold it down and then press key and then release them both. For example: C-e (Control-E) moves the blinking caret to the end of the current line.

M-key = Same as C-key, except with the Meta key. Depending on your keyboard, Meta may be called ``Left'', ``Right'' or have a diamond symbol, but it's usually on the bottom row next to the space bar. M-key can also be performed as a two-character sequence: first, strike and release the Escape key, then strike key. Under Windows and Mac OS X, Meta is only available through the Escape key.

DEL = The Delete key.

SPACE = The Space bar.

Note: On most keyboards, ``<'' and ``>'' are shifted characters. So, to get M->, you actually have to type Meta-Shift->. That is, press and hold down both the Meta and Shift keys, and then strike ``>''.

Note: Many of the key bindings can also be done with menu items.

Under Windows, some of these keybindings are actually standard menu items. Those keybindings will behave according to the menus, unless the Enable keybindings in menus preference is unchecked.

If you are most familiar with Emacs-style key bindings, you should uncheck the Enable keybindings in menus preference. Many of the keybindings below are inspired by Emacs.

3.3.1  Moving Around

• C-f move forward one character

• C-b move backward one character

• M-f move forward one word

• M-b move backward one word

• C-v move forward one page

• M-v move backward one page

• M-< move to beginning of file

• M-> move to end of file

• C-a move to beginning of line (left)

• C-e move to end of line (right)

• C-n move to next line (down)

• C-p move to previous line (up)

• M-C-f move forward one S-expression

• M-C-b move backward one S-expression

• M-C-u move up out of an S-expression

• M-C-d move down into a nested S-expression

• M-C-SPACE select forward S-expression

• M-C-p match parentheses backward

• M-C-left move backwards to the nearest editor box

• A-C-left move backwards to the nearest editor box

• M-C-right move forward to the nearest editor box

• A-C-right move forward to the nearest editor box

• M-C-up move up out of an embedded editor

• A-C-up move up out of an embedded editor

• M-C-down move down into an embedded editor

• A-C-down move down into an embedded editor

3.3.2  Editing Operations

• C-d delete forward one character

• C-h delete backward one character

• M-d delete forward one word

• M-DEL delete backward one word

• C-k delete forward to end of line

• M-C-k delete forward one S-expression

• M-w copy selection to clipboard

• C-w delete selection to clipboard (cut)

• C-y paste from clipboard (yank)

• C-t transpose characters

• M-t transpose words

• M-C-t transpose sexpressions

• M-C-m toggle dark green marking of matching parenthesis

• M-C-k cut complete sexpression

• M-( wrap selection in parentheses

• M-[ wrap selection in square brackets

• M-{ wrap selection in curly brackets

• M-S-L wrap selection in (lambda () ...) and put the insertion point in the arglist of the lambda

• C-_ undo

• C-+ redo

• C-x u undo

• M-o toggle overwrite mode

3.3.3  File Operations

• C-x C-s save file

• C-x C-w save file under new name

3.3.4  Searching

• C-s search for string forward

• C-r search for string backward

3.3.5  Miscellaneous

• F5 Run

3.3.6  Interactions

The interactions window has all of the same keyboard shortcuts as the definitions window plus a few more:

• M-p bring the previously entered expression down to the prompt.

• M-n bring the expression after the current expression in the expression history down to the prompt.

3.3.7  Defining Custom Shortcuts

The Add User-defined Keybindings... menu item in the Keybindings sub-menu of Edit selects a file containing Scheme definitions of keybindings. The file must contain a single module that uses a special keybindings language, (lib "keybinding-lang.ss" "framework"). For example, a file named mykeys.ss for keybindings might contain the following code:

(module mykeys (lib "keybinding-lang.ss" "framework")
  ...)

The keybindings language includes all of MzScheme, (lib "mred.ss" "mred"), (lib "class.ss"), and one addition, a keybinding form:

(keybinding keybinding-string-expr keybinding-proc-expr)

The keybinding-string-expr must produce a suitable first argument for map-function in keymap%, and the keybinding-proc-expr must produce a suitable second argument for add-function in keymap%.

3.4  DrScheme Files

3.4.1  Program Files

The standard extension for a Scheme program file is .scm. The extensions .ss and .sch are also acceptable.

DrScheme's editor can save a program file in two different formats:

• Plain-text format -- All text editors can read this format. DrScheme saves a program in plain-text format by default, unless the program contains images or text boxes. (Plain-text format does not preserve images or text boxes.)

  Plain-text format is platform-specific because different platforms have different newline conventions. However, most tools for moving files across platforms support a ``text'' transfer mode that adjusts newlines correctly.

• Multimedia format -- This format is specific to DrScheme, and no other editor recognizes it. DrScheme saves a program in multimedia format by default when the program contains images, text boxes, or formatted text.

  Multimedia format is platform-independent, and it uses an ASCII encoding (so that different ways of transferring the file are unlikely to corrupt the file).

3.4.2  Backup and Autosave Files

When you modify an existing file in DrScheme and save it, DrScheme copies the old version of the file to a special backup file if no backup file exists. The backup file is saved in the same directory as the original file, and the backup file's name is generated from the original file's name:

• Under Unix and Mac OS X, a tilde (~) is added to the end of the file's name.

• Under Windows, the file's extension is replaced with .bak.

When a file in an active DrScheme editor is modified but not saved, DrScheme saves the file to a special autosave file after five minutes (in case of a power failure or catastrophic error). If the file is later saved, or if the user exists DrScheme without saving the file, the autosave file is removed. The autosave file is saved in the same directory as the original file, and the autosave file's name is generated from the original file's name:

• Under Unix and Mac OS X, a pound sign (#) is added to the start and end of the file's name, then a number is added after the ending pound sign, and then one more pound sign is appended to the name. The number is selected to make the autosave filename unique.

• Under Windows, the file's extension is replaced with a number to make the autosave filename unique.

3.4.3  Preference Files

On start-up, DrScheme reads configuration information from a preferences file. The name and location of the preferences file depends on the platform and user:²

• Under Unix, preferences are stored in a .plt-scheme subdirectory in the user's home directory, in a file plt-prefs.ss.

• Under Windows, preferences are stored in a file plt-prefs.ss in a sub-directory PLT Scheme in the user's application-data folder as specified by the Windows registry; the application-data folder is usually Application Data in the user's profile directory.

• Under Mac OS X, preferences are stored in org.plt-scheme.prefs.ss in the user's preferences folder.

A lock file is used while modifying the preferences file, and it is created in the same directory as the preferences file. Under Windows, the lock file is named _LOCKplt-prefs.ss; under Unix, it is .LOCK.plt-prefs.ss; under Mac OS X, it is .LOCK.org.plt-scheme.prefs.ss.

If the user-specific preferences file does not exist, and the file plt-prefs.ss in the defaults collection does exist, then it is used for the initial preference settings. (See Library Collections and MzLib for more information about collections.) This file thus allows site-specific configuration for preference defaults. To set up such a configuration, start DrScheme and configure the preferences to your liking. Then, exit DrScheme and copy your preferences file into the defaults collection as plt-prefs.ss. Afterward, users who have no preference settings already will get the preference settings that you chose.