a first cut of the tools manual converted to scribble

svn: r9670

collects/scribblings/tools/common.ss

@@ -0,0 +1,21 @@
+(module common scheme/base
+  (require scribble/manual
+           scribble/basic
+           scheme/class
+           scheme/contract)
+  (provide (all-from-out scribble/manual)
+           (all-from-out scribble/basic)
+           (all-from-out scheme/class)
+           (all-from-out scheme/contract))
+
+  (require (for-label scheme/gui/base
+                      scheme/class
+                      scheme/contract
+                      scheme/base
+                      framework))
+  (provide (for-label (all-from-out scheme/gui/base)
+                      (all-from-out scheme/class)
+                      (all-from-out scheme/contract)
+                      (all-from-out scheme/base)
+                      (all-from-out framework))))
+

collects/scribblings/tools/debug.scrbl

@@ -0,0 +1,19 @@
+#lang scribble/doc
+@(require "common.ss")
+@(defmodule drscheme/tool-lib)@title{@tt{drscheme:debug}}
+
+@defmixin[drscheme:debug:profile-unit-frame-mixin () ((domain . drscheme:frame:) (domain . drscheme:unit:frame))]{
+
+}
+
+
+@defmixin[drscheme:debug:profile-interactions-text-mixin () ((domain . drscheme:rep:text))]{
+
+%%                                                                  %%                       drscheme:unit                              %%                                                                  
+}
+
+
+@defmixin[drscheme:debug:profile-definitions-text-mixin () ((domain . drscheme:unit:definitions-text) (domainc . text))]{
+
+}
+

collects/scribblings/tools/frame.scrbl

@@ -0,0 +1,268 @@
+#lang scribble/doc
+@(require "common.ss")
+@(defmodule drscheme/tool-lib)@title{@tt{drscheme:frame}}
+
+@defclass[drscheme:frame:name-message% canvas% ()]{
+
+This class implements the little filename button in the top-right hand
+side of drscheme's frame.
+
+
+
+@defconstructor/make[([parent (instance (implements @scheme[area-container<%>]))])]{}
+
+@defmethod[(set-message [name (union string \#f)]
+                        [short-name string?])
+           void?]{
+@methspec{
+
+Sets the names that the button shows.
+
+}
+@methimpl{
+
+The string @scheme[short-name] is the name that is shown on the button
+and @scheme[name] is shown when the button is clicked on, in a separate
+window. If @scheme[name] is \#f, a message indicating that the file
+hasn't been saved is shown.
+
+
+
+}}}
+
+
+@defmixin[drscheme:frame:mixin (drscheme:frame:<%>) ((domain . drscheme:frame:basics) (domain . frame:text-info) (domain . frame:editor))]{
+
+Provides an implementation of 
+@scheme[drscheme:frame:<%>] 
+%%                                                                  %%                       drscheme:language                          %%                                                                  
+}
+
+
+@defmixin[drscheme:frame:basics-mixin (drscheme:frame:basics<%>) ((domain . frame:standard-menus))]{
+
+Use this mixin to establish some common menu items across various DrScheme windows.
+
+
+
+@defmethod[#:mode override 
+           (edit-menu:between-find-and-preferences)
+           void?]{
+
+Adds a
+@scheme[separator-menu-item%]. Next, adds the
+@scheme["Keybindings"] menu item to the edit menu. Finally,
+if the 
+@scheme[current-eventspace-has-standard-menus?] procedure returns @scheme[#f], creates another 
+@scheme[separator-menu-item%].
+
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:between-open-and-revert [file-menu (is-a?/c @scheme[menu%])])
+           void?]{
+
+Adds an {\it Install .plt File...} menu item, which
+downloads and installs .plt files from the web, or installs
+them from the local disk. After that, calls the super
+method.
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:between-print-and-close [file-menu (is-a?/c @scheme[menu%])])
+           void?]{
+
+Calls the super method. Then, creates a menu item for
+multi-file searching. Finally,
+adds a
+@scheme[separator-menu-item%].
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:new-callback [item (instance (derived-from @scheme[menu-item%]))]
+                                   [evt (instance @scheme[control-event%])])
+           void?]{
+
+Opens a new, empty DrScheme window.
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:new-string)
+           string?]{
+
+Returns the empty string.
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:open-callback [item (instance (derived-from @scheme[menu-item%]))]
+                                    [evt (instance @scheme[control-event%])])
+           void?]{
+
+Calls 
+@scheme[handler:edit-file].
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:open-string)
+           string?]{
+
+Returns the empty string.
+
+
+}
+
+@defmethod[(get-additional-important-urls)
+           (listof (list string string))]{
+@methspec{
+
+Each string in the result of this method is added as a menu
+item to DrScheme's ``Related Web Sites'' menu item. The
+first string is the name of the menu item and the second
+string is a url that, when the menu item is chosen, is sent
+to the user's browser.
+
+}
+@methimpl{
+
+Defaultly returns the empty list.
+
+
+}}
+
+@defmethod[#:mode override 
+           (help-menu:about-callback [item (instance (derived-from @scheme[menu-item%]))]
+                                     [evt (instance @scheme[control-event%])])
+           void?]{
+
+Opens an about box for DrScheme.
+
+
+}
+
+@defmethod[#:mode override 
+           (help-menu:about-string)
+           string?]{
+
+Returns the string @scheme["DrScheme"].
+
+
+}
+
+@defmethod[#:mode override 
+           (help-menu:before-about [help-menu (instance @scheme[menu%])])
+           void?]{
+
+Adds the Help Desk menu item and the Welcome to DrScheme menu item.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% betweens 
+
+}
+
+@defmethod[#:mode override 
+           (help-menu:create-about?)
+           boolean?]{
+
+Returns @scheme[#t].
+
+
+}}
+
+
+@definterface[drscheme:frame:basics<%> (frame:standard-menus<%>)]{
+
+This interface is the result of the
+\iscmmixin{drscheme:frame:basics-mixin} 
+
+}
+
+
+@definterface[drscheme:frame:<%> (frame:editor<%> frame:text-info<%> drscheme:frame:basics<%>)]{
+
+
+
+@defmethod[(add-show-menu-items [show-menu (is-a?/c @scheme[menu%])])
+           void?]{
+@methspec{
+
+This method is called during the construction of the view
+menu.  This method is intended to be overridden. It is
+expected to add other Show/Hide menu items to the show menu.
+
+See also
+@method[drscheme:frame:<%> get-show-menu].
+
+}
+@methimpl{
+
+Does nothing.
+
+
+
+}}
+
+@defmethod[(get-show-menu)
+           (instanceof @scheme[menu%])]{
+\index{View menu}
+
+returns the view menu, for use by the
+@method[drscheme:frame:<%> update-shown] method.
+
+See also
+@method[drscheme:frame:<%> add-show-menu-items].
+
+The method (and others) uses the word {\tt show} to preserve
+backwards compatibility from when the menu itself was named
+the Show menu.
+
+}
+
+@defmethod[(not-running)
+           void?]{
+updates the status pane at the bottom of the window to show
+that evaluation is not taking place in the user's program.
+
+}
+
+@defmethod[(running)
+           void?]{
+updates the status pane at the bottom of the window to show
+that evaluation is taking place in the user's program.
+
+}
+
+@defmethod[(update-shown)
+           void?]{
+@methspec{
+
+This method is intended to be overridden. It's job is to
+update the @scheme["View"] menu to match the state of the
+visible windows. In the case of the standard DrScheme
+window, it change the menu items to reflect the visibility of
+the definitions and interaction @scheme[editor-canvas%]s.
+
+Call this method whenever the state of the show menu might
+need to change.
+
+See also
+@method[drscheme:frame:<%> get-show-menu].
+
+}
+@methimpl{
+
+Does nothing.
+
+
+}}}
+

collects/scribblings/tools/get-slash-extend.scrbl

@@ -0,0 +1,92 @@
+#lang scribble/doc
+@(require "common.ss")
+@(defmodule drscheme/tool-lib)@title{@tt{drscheme:get/extend}}
+
+@defclass[drscheme:get/extend:base-unit-frame% (drscheme:debug:profile-unit-frame-mixin) ()]{
+
+
+
+@defconstructor[()]{
+Passes all arguments to @scheme[super-init].
+}}
+
+
+@defclass[drscheme:get/extend:base-tab% () ()]{
+
+
+
+@defconstructor[()]{
+Passes all arguments to @scheme[super-init].
+}}
+
+
+@defclass[drscheme:get/extend:base-interactions-text% (drscheme:debug:profile-interactions-text-mixin) ()]{
+
+
+
+@defconstructor[()]{
+Passes all arguments to @scheme[super-init].
+}}
+
+
+@defclass[drscheme:get/extend:base-interactions-canvas% (canvas:delegate-mixin canvas:info-mixin) ()]{
+
+
+
+@defconstructor/make[()]{
+
+Calls @scheme[super-new], adding @scheme['hide-hscroll] to the style argument.
+
+
+}
+
+@defconstructor[()]{
+Passes all arguments to @scheme[super-init].
+}
+
+@defmethod[#:mode override 
+           (on-focus)
+           void?]{
+
+When the focus is on, calls
+@method[drscheme:unit:frame% make-searchable] with @scheme[this].
+
+
+}}
+
+
+@defclass[drscheme:get/extend:base-definitions-text% (drscheme:debug:profile-definitions-text-mixin) ()]{
+
+
+
+@defconstructor[()]{
+Passes all arguments to @scheme[super-init].
+}}
+
+
+@defclass[drscheme:get/extend:base-definitions-canvas% (canvas:delegate-mixin canvas:info-mixin) ()]{
+
+
+
+@defconstructor/make[()]{
+
+Calls @scheme[super-new], adding @scheme['hide-hscroll] to the style argument.
+
+
+}
+
+@defconstructor[()]{
+Passes all arguments to @scheme[super-init].
+}
+
+@defmethod[#:mode override 
+           (on-focus)
+           void?]{
+
+When the focus is on, calls
+@method[drscheme:unit:frame% make-searchable] with @scheme[this].
+
+%%                                                                  %%                        drscheme:debug                            %%                                                                  
+
+}}
+

collects/scribblings/tools/rep.scrbl

@@ -0,0 +1,462 @@
+#lang scribble/doc
+@(require "common.ss")
+@(defmodule drscheme/tool-lib)@title{@tt{drscheme:rep}}
+
+@definterface[drscheme:rep:text<%> ()]{
+
+
+}
+
+
+@defclass[drscheme:rep:text% scheme:text% (drscheme:rep:text<%>)]{
+
+This class implements a read-eval-print loop for DrScheme.  User
+submitted evaluations in DrScheme are evaluated asynchronously, in an
+eventspace created for the user. No evaluations carried out by this
+class affect the implementation that uses it.
+
+
+
+@defconstructor/make[([context (implements @scheme[drscheme:rep:context<%>])])]{
+
+%          %          %%        begin rep-text methods        %          
+
+}
+
+@defmethod[#:mode override 
+           (after-delete)
+           void?]{
+
+Resets any error highlighting in this editor.
+
+
+}
+
+@defmethod[#:mode override 
+           (after-insert)
+           void?]{
+
+Resets any error highlighting in this editor.
+
+
+}
+
+@defmethod[(display-results [results (list-of TST)])
+           void?]{
+
+This displays each of the elements of @scheme[results] in the interactions
+window, expect those elements of @scheme[results] that are void. Those
+are just ignored.
+
+
+}
+
+@defmethod[(do-many-evals [run-loop (((-> void) -> void) -> void)])
+           void?]{
+@methspec{
+
+Use this function to evaluate code or run actions that should mimic
+the user's interactions. For example, DrScheme uses this function to
+evaluate expressions in the definitions window and expressions
+submitted at the prompt.
+
+}
+@methimpl{
+
+The function @scheme[run-loop] is called. It is expected to loop, calling
+it's argument with a thunk that corresponds to the user's
+evaluation. It should call it's argument once for each expression the
+user is evaluating.  It should pass a thunk to it's argument that
+actually does the users's evaluation.
+
+
+}}
+
+@defmethod[(do-many-text-evals [text (is-a?/c text%)]
+                               [start int]
+                               [end int ]
+                               [complete-program? any/c])
+           void?]{
+@methspec{
+
+This function evaluates all of the expressions in a text.
+
+}
+@methimpl{
+
+It evaluates all of the expressions in @scheme[text] starting at
+@scheme[start] and ending at @scheme[end], calling
+@method[drscheme:rep:text% do-many-evals] to handle the evaluation.
+
+The @scheme[complete-program?] argument determines if the
+@method[drscheme:language:language<%> front-end/complete-program] method or the
+@method[drscheme:language:language<%> front-end/interaction] method is called.
+
+
+}}
+
+@defmethod[(get-error-range)
+           (union \#f (list (instanceof @scheme[text:basic%] number number)))]{
+@methspec{
+
+Indicates the highlighted error range. The state for the
+error range is shared across all instances of this class, so
+there can only be one highlighted error region at a time.
+
+}
+@methimpl{
+
+If \scm{\#f}, no region is highlighted. If a list, the first
+element is the editor where the range is highlighted and the
+second and third are the beginning and ending regions,
+respectively.
+
+
+}}
+
+@defmethod[(get-user-custodian)
+           (union \#f custodian)]{
+This is the custodian controlling the user's program.
+
+}
+
+@defmethod[(get-user-eventspace)
+           (union \#f eventspace)]{
+This is the user's eventspace. The result of
+@method[drscheme:rep:text% get-user-thread] is the main thread of this eventspace.
+
+}
+
+@defmethod[(get-user-language-settings)
+           language-settings]{
+Returns the user's language-settings for the most recently
+run program. Consider using
+@method[drscheme:unit:definitions-text<%> get-next-settings] instead, since the user may have selected a new language
+since the program was last run.
+
+}
+
+@defmethod[(get-user-namespace)
+           (union \#f namespace)]{
+Returns the user's namespace. This method
+returns a new namespace each time Run is
+clicked.
+
+}
+
+@defmethod[(get-user-thread)
+           (union \#f thread)]{
+This method returns the thread that the users code runs
+in. It is returns a different result, each time the user
+runs the program.
+
+It is @scheme[#f] before the first time the user click on
+the Run button or the evaluation has been killed.
+
+This thread has all of its parameters initialized according to the
+settings of the current execution.
+See \Mzhyperref{parameters}{mz:parameters}
+for more information about parameters.
+
+}
+
+@defmethod[(highlight-errors [locs (listof (list (instance (implements @scheme[text:basic<%>])) small-integer small-integer))])
+           void?]{
+Call this method to highlight errors associated with this repl.
+See also
+@method[drscheme:rep:text% reset-highlighting], and
+@method[drscheme:rep:text% highlight-errors/exn].
+
+This method highlights a series of dis-contiguous ranges in
+the editor.
+
+It puts the caret at the location of the first error.
+
+}
+
+@defmethod[(highlight-errors/exn [exn exn])
+           void?]{
+
+Highlights the errors associated with the exn (only syntax
+and read errors -- does not extract any information from the
+continuation marks)
+
+See also 
+@method[drscheme:rep:text% highlight-errors].
+
+
+}
+
+@defmethod[(initialize-console)
+           void?]{
+
+This inserts the ``Welcome to DrScheme'' message into the interactions
+buffer, calls
+@method[drscheme:rep:text% reset-console],
+@method[drscheme:rep:text% insert-prompt], and 
+@method[editor<%> clear-undos].
+
+Once the console is initialized, this method calls
+@method[drscheme:language:language<%> first-opened]. Accordingly, this method should not be called to initialize
+a REPL when the user's evaluation is imminent. That is,
+this method should be called when new tabs or new windows
+are created, but not when the Run button is clicked. 
+
+
+}
+
+@defmethod[(insert-prompt)
+           void?]{
+
+Inserts a new prompt at the end of the text.
+
+
+%%                                                                  %%                       drscheme:frame                             %%                                                                  
+
+}
+
+@defmethod[(kill-evaluation)
+           void?]{
+This method is called when the user chooses the kill menu item.
+
+}
+
+@defmethod[#:mode override 
+           (on-close)
+           void?]{
+
+Calls 
+@method[drscheme:rep:text% shutdown].
+
+Calls the super method.
+
+
+}
+
+@defmethod[(queue-output [thnk (-> void?)])
+           void?]{
+@methspec{
+
+This method queues thunks for drscheme's eventspace in a
+special output-related queue.
+
+}
+@methimpl{
+
+%          %          %%      begin console-text methods      %          %% many more methods should be added here....
+
+
+}}
+
+@defmethod[(reset-console)
+           void?]{
+
+Kills the old eventspace, and creates a new
+parameterization for it.
+
+
+}
+
+@defmethod[(reset-highlighting)
+           void?]{
+This method resets the highlighting being displayed for this repl. See also:
+@method[drscheme:rep:text% highlight-errors], and
+@method[drscheme:rep:text% highlight-errors/exn].
+
+}
+
+@defmethod[(run-in-evaluation-thread [f ( -> void)])
+           void?]{
+@methspec{
+
+This function runs it's arguments in the user evaluation thread. This
+thread is the same as the user's eventspace main thread.
+
+See also  
+@method[drscheme:rep:text% do-many-evals].
+
+}
+@methimpl{
+
+Calls @scheme[f], after switching to the user's thread.
+
+
+}}
+
+@defmethod[(shutdown)
+           void?]{
+Shuts down the user's program and all windows. Reclaims any
+resources the program allocated.  It is expected to be
+called from DrScheme's main eventspace thread.
+
+}
+
+@defmethod[(wait-for-io-to-complete)
+           void?]{
+This waits for all pending IO in the rep to finish
+and then returns.
+
+This method must only be called from the main thread in
+DrScheme's eventspace
+
+}
+
+@defmethod[(wait-for-io-to-complete/user)
+           void?]{
+This waits for all pending IO in the rep to finish
+and then returns.
+
+This method must only be called from the main thread
+in the user's eventspace
+
+}}
+
+
+@defmixin[drscheme:rep:drs-bindings-keymap-mixin () ((domain . editor:keymap))]{
+
+This mixin adds some drscheme-specific keybindings to the
+editor it is mixed onto.
+
+
+
+@defmethod[#:mode override 
+           (get-keymaps)
+           (listof (instanceof @scheme[keymap%]))]{
+
+Calls the super method and adds in a keymap with the
+drscheme-specific keybindings:
+
+@itemize{
+@item{f5 - Run}
+
+@item{c:x;o - toggles the focus between the definition and
+interactions windows.}
+}
+
+
+
+}}
+
+
+@definterface[drscheme:rep:context<%> ()]{
+
+Objects that match this interface provide all of the services that the 
+@scheme[drscheme:rep:text%] class needs to connect with it's context.
+
+
+
+@defmethod[(clear-annotations)
+           void?]{
+@methspec{
+
+Call this method to clear any annotations in the text before
+executing or analyzing or other such activities that should
+process the program.
+
+Tools that annotate the program text should augment this
+method to clear their own annotations on the program text.
+
+DrScheme calls this method before a program is run (via the
+Run button).
+
+}
+@methimpl{
+
+Clears any error highlighting in the definitions window.
+
+
+
+}}
+
+@defmethod[(disable-evaluation)
+           void?]{
+Call this method to disable evaluation GUI evaluation while
+some evaluation (or expansion) is taking place on another
+thread.
+
+Override this method if you add a GUI-based mechanism for
+initiating evaluation in the frame.
+
+This method is also called when the user switches tabs.
+
+See also
+@method[drscheme:rep:context<%> enable-evaluation].
+
+}
+
+@defmethod[(enable-evaluation)
+           void?]{
+This method must disable the GUI controls that start
+user-sponsored evaluation. It is called once the user starts
+some evaluation to ensure that only one evaluation proceeds
+at a time.
+
+It is also called when the user switches tabs.
+
+See also
+@method[drscheme:rep:context<%> disable-evaluation].
+
+}
+
+@defmethod[(ensure-rep-shown [rep (is-a?/c @scheme[drscheme:rep:text<%>])])
+           void?]{
+
+This method is called to force the rep window to be visible when, for
+example, an error message is put into the rep. Also ensures
+that the appropriate tab is visible, if necessary.
+
+
+}
+
+@defmethod[(get-breakables)
+           (values (union thread \#f) (union custodian \#f))]{
+Returns the last values passed to
+@method[drscheme:rep:context<%> set-breakables].
+
+}
+
+@defmethod[(get-directory)
+           (union string \#f)]{
+The result of this method is used as the initial directory for the
+user's program to be evaluated in.
+
+}
+
+@defmethod[(needs-execution)
+           (union string? false/c)]{
+This method should return an explanatory string when the
+state of the program that the repl reflects has changed. It
+should return @scheme[#f] otherwise.
+
+}
+
+@defmethod[(reset-offer-kill)
+           void?]{
+The break button typically offers to kill if it has been
+pushed twice in a row. If this method is called, however, it
+ignores any prior clicks.
+
+}
+
+@defmethod[(set-breakables [thread (union thread \#f)]
+                           [custodian (union custodian \#f)])
+           void?]{
+Calling this method with a thread and a custodian means that
+the next time the break button is clicked, it will either
+break the thread or shutdown the custodian.
+
+See also
+@method[drscheme:rep:context<%> get-breakables].
+
+}
+
+@defmethod[(update-running [running? any/c])
+           void?]{
+
+This method should update some display in the gui that
+indicates whether or not evaluation is currently proceeding
+in the user's world.
+
+
+}}
+

collects/scribblings/tools/tools.scrbl

@@ -14,7 +14,7 @@
 
 @title{@bold{Plugins}: Extending DrScheme}
 
-@section{This Manual}
+@bold{This Manual}
 
 This manual describes DrScheme's tools interface. It assumes
 familiarity with 
@@ -25,7 +25,9 @@ DrScheme, as described in
 and the Framework, as described in
 @(other-manual '(lib "framework/framework.scrbl")).
 
-@section{Thanks}
+@table-of-contents[]
+
+@bold{Thanks}
 
 Thanks especially to 
 Eli Barzilay, 
@@ -479,4 +481,11 @@ the tool shows this part of the GUI for DrScheme.
 See @scheme[drscheme:language:register-capability]
 for a list of the capabilities registered by default.
 
+@include-section["get-slash-extend.scrbl"]
+@include-section["unit.scrbl"]
+@include-section["language.scrbl"]
+@include-section["debug.scrbl"]
+@include-section["rep.scrbl"]
+@include-section["frame.scrbl"]
+
 @index-section[]

collects/scribblings/tools/unit.scrbl

@@ -0,0 +1,842 @@
+#lang scribble/doc
+@(require "common.ss")
+@(defmodule drscheme/tool-lib)@title{@tt{drscheme:unit}}
+
+@definterface[drscheme:unit:tab<%> (drscheme:rep:context<%>)]{
+
+
+
+@defmethod[(break-callback)
+           void?]{
+@methspec{
+
+This method is called when the break button is clicked and
+this tab is the active tab.
+
+}
+@methimpl{
+
+By default, breaks any evaluation that may be happening at
+this point.
+
+
+}}
+
+@defmethod[#:mode pubment 
+           (can-close?)
+           boolean?]{
+@methspec{
+
+This method is called to determine if it is okay to close this tab.
+
+}
+@methimpl{
+
+Calls the definitions text's and interactions text's
+@method[editor:basic<%> can-close?] method.
+
+
+}}
+
+@defmethod[#:mode override 
+           (disable-evaluation)
+           void?]{
+
+Disables the Run button, and the Run menu item and
+@method[editor<%> lock]s the interactions window, and the definitions window.
+
+
+}
+
+@defmethod[#:mode override 
+           (enable-evaluation)
+           void?]{
+
+Enables the Run button, and the Run menu item and unlocks
+(via the
+@method[editor<%> lock]method) the interactions window and the definitions window.
+
+
+}
+
+@defmethod[#:mode override 
+           (get-breakables)
+           (values (union thread \#f) (union custodian \#f))]{}
+
+@defmethod[(get-defs)
+           (is-a?/c @scheme[drscheme:rep:text%])]{
+This text is initially the top half of the drscheme window and
+contains the users program.
+
+This text defaults to a @scheme[text%]
+object, but if you change
+@scheme[drscheme:get/extend:extend-interactions-text] procedure, it will use the extended class to create the text.
+
+}
+
+@defmethod[#:mode override 
+           (get-directory)
+           (union string \#f)]{
+
+This is the directory that the file is saved in, or the
+directory DrScheme started up in, if the file has not been
+saved.
+
+
+}
+
+@defmethod[(get-enabled)
+           boolean?]{
+Indicates if evaluation is currently enabled in this
+tab. Evaluation is typically disabled when some evaluation
+is already running (in another thread).
+
+}
+
+@defmethod[(get-frame)
+           (is-a?/c @scheme[drscheme:unit:frame%])]{
+Returns the frame that this tab is inside.
+
+}
+
+@defmethod[(get-ints)
+           (is-a?/c @scheme[drscheme:unit:definitions-text<%>])]{
+This text is initially the bottom half of the drscheme window and
+contains the users interactions with the REPL.
+
+This text defaults to a @scheme[drscheme:rep:text%]
+object, but if you use the
+@scheme[drscheme:get/extend:extend-interactions-text] procedure,
+it will use the extended class to create the text.
+
+}
+
+@defmethod[(is-current-tab?)
+           boolean?]{
+Indicates if this tab is the currently active tab.
+
+}
+
+@defmethod[(is-running?)
+           boolean?]{
+
+Indicates if the running message in the bottom right of
+drscheme's frame should be ``running'' or ``not running''
+when this frame is active.
+
+
+
+}
+
+@defmethod[#:mode pubment 
+           (on-close)
+           void?]{
+@methspec{
+
+This method is called when the tab is closed.
+
+}
+@methimpl{
+
+Calls the definitions text's
+@method[editor:basic<%> on-close] and interactions text's
+@method[drscheme:rep:text% on-close] methods.
+
+
+}}
+
+@defmethod[#:mode override 
+           (reset-offer-kill)
+           void?]{}
+
+@defmethod[#:mode override 
+           (set-breakables [thread (union thread \#f)]
+                           [custodian (union custodian \#f)])
+           void?]{}}
+
+
+@defclass[drscheme:unit:tab% object% (drscheme:unit:tab<%>)]{
+
+The base class that implements the tab's functionality.
+
+
+
+@defconstructor/make[()]{}
+
+@defmethod[#:mode override 
+           (clear-annotations)
+           void?]{
+
+Clears any error highlighting.
+
+
+
+
+}}
+
+
+@defmixin[drscheme:unit:program-editor-mixin () ((domainc . text) (domain . editor:basic))]{
+
+This mixes in the ability to reset the highlighting for
+error message when the user modifies the buffer. Use it for
+editors that have program text where errors can occur.
+
+
+
+@defmethod[#:mode override 
+           (after-delete [start number]
+                         [len number])
+           void?]{
+
+Calls the super method.
+
+Resets an error highlighting.
+
+
+
+}
+
+@defmethod[#:mode override 
+           (after-insert [start number]
+                         [len number])
+           void?]{
+
+Calls the super method.
+
+Resets an error highlighting.
+
+
+}}
+
+
+@defclass[drscheme:unit:interactions-canvas% canvas:wide-snip% ()]{
+
+
+
+
+
+@defconstructor/auto-super[()]{
+Passes all arguments to @scheme[super-init].
+}}
+
+
+@defclass[drscheme:unit:frame% (drscheme:frame:mixin drscheme:frame:basics-mixin drscheme:unit:frame<%>) ()]{
+
+This frame inserts the Scheme and Language menus into the menu bar as it is initialized.
+
+
+
+
+@defconstructor/auto-super[()]{
+Passes all arguments to @scheme[super-init].
+}
+
+@defconstructor[()]{
+Passes all arguments to @scheme[super-init].
+}
+
+@defmethod[#:mode override 
+           (add-show-menu-items [show-menu (is-a?/c @scheme[menu%])])
+           void?]{
+
+Adds the ``Show Definitions'', ``Show Interactions'' and
+``Show Contour'' menu items.
+
+
+}
+
+@defmethod[(break-callback)
+           void?]{
+@methspec{
+
+This method is called when the user clicks on the break
+button or chooses the break menu item.
+
+}
+@methimpl{
+
+Breaks the user's evaluation started by the Run button
+(or possibly a queued callback in the user's eventspace).
+
+
+}}
+
+@defmethod[(change-to-file [file string?])
+           void?]{
+
+Loads this file into this already created frame. In normal
+DrScheme use, this method is only called if this is the
+first frame opened and no editing has occurred. It should be
+safe to call this at anytime, however.
+
+
+}
+
+@defmethod[#:mode override 
+           (edit-menu:between-select-all-and-find)
+           void?]{
+
+Adds the @scheme["Split"] and @scheme["Collapse"] menu items.
+
+
+}
+
+@defmethod[(execute-callback)
+           void?]{
+@methspec{
+
+This method is called when the user clicks on the Run
+button or chooses the Run menu item.
+
+}
+@methimpl{
+
+It calls 
+@method[drscheme:rep:context<%> ensure-rep-shown] and then it calls
+@method[drscheme:rep:text% do-many-text-evals] passing in the result of
+@method[drscheme:unit:frame<%> get-interactions-text] and its entire range, unless the first two characters are 
+"\#!" in which case, it skips the first line.
+
+
+}}
+
+@defmethod[#:mode override 
+           (file-menu:between-open-and-revert)
+           void?]{
+
+Calls the super method and adds a
+@scheme[separator-menu-item%] to the menu.
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:between-print-and-close)
+           void?]{
+
+Adds a menu item for printing the interactions.
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:between-save-as-and-print)
+           void?]{
+
+Adds a submenu that contains various save options:
+@itemize{
+@item{save definitions as text}
+@item{save interactions}
+@item{save interactions as}
+@item{save interactions as text}
+}
+
+and adds a separator item.
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:print-string)
+           void?]{
+
+returns @scheme["Definitions"]
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:save-as-string)
+           void?]{
+
+Returns @scheme["Definitions"].
+
+
+}
+
+@defmethod[#:mode override 
+           (file-menu:save-string)
+           void?]{
+
+Returns @scheme["Definitions"].
+
+
+}
+
+@defmethod[(get-break-button)
+           (instanceof @scheme[button%])]{
+Returns the break button. Mostly used for test suites.
+
+}
+
+@defmethod[(get-button-panel)
+           (instanceof @scheme[horizontal-panel%])]{
+This panel goes along the top of the drscheme window and has buttons
+for important actions the user frequently executes. 
+
+A tool can add a button to this panel to make some new functionality
+easily accessible to the user.
+
+See also mrlib's {\tt bitmap-label-maker}.
+
+}
+
+@defmethod[#:mode override 
+           (get-canvas)
+           (instanceof @scheme[editor-canvas%])]{
+
+Returns the result of
+@method[drscheme:unit:frame<%> get-definitions-canvas].
+
+
+}
+
+@defmethod[#:mode override 
+           (get-canvas\%)
+           (instanceof (derived-from @scheme[canvas%]))]{
+
+Returns the result of
+@scheme[drscheme:get/extend:get-definitions-canvas].
+
+
+}
+
+@defmethod*[([(get-definitions/interactions-panel-parent)
+              (instanceof @scheme[vertical-panel%])]
+             [(get-definitions/interactions-panel-parent)
+              void?])]{
+@methspec{
+
+This method is provided so that tools can add 
+@scheme[area-container<%>]s to the drscheme frame. Override this method so that it
+returns a child of the super-classes's result and insert new 
+children inbetween.
+
+}
+@methimpl{
+First case:
+
+
+Returns the result of 
+@method[frame:basic<%> get-area-container] 
+
+
+Second case:
+
+
+
+}}
+
+@defmethod[#:mode override 
+           (get-editor)
+           (instanceof @scheme[editor<%>])]{
+
+Returns the result of
+@method[drscheme:unit:frame<%> get-definitions-text].
+
+
+
+}
+
+@defmethod[#:mode override 
+           (get-editor\%)
+           (instanceof (derived-from @scheme[editor<%>]))]{
+
+Returns the result of
+@scheme[drscheme:get/extend:get-definitions-text].
+
+
+}
+
+@defmethod[(get-execute-button)
+           (instanceof @scheme[button%])]{
+Returns the Run button. Mostly used for test suites.
+
+}
+
+@defmethod[#:mode override 
+           (get-text-to-search)
+           (is-a?/c text:searching%)]{
+
+returns the text that is active in the last canvas passed to
+@method[drscheme:unit:frame% make-searchable] 
+
+}
+
+@defmethod[(make-searchable [canvas (is-a?/c drscheme:unit:interactions-canvas%)])
+           void?]{
+
+stores the canvas, until 
+@method[drscheme:unit:frame% get-text-to-search] is called.
+
+
+}
+
+@defmethod[#:mode override 
+           (on-close)
+           void?]{
+
+Sends the result of
+@method[drscheme:unit:frame<%> get-interactions-text] the
+@method[drscheme:rep:text% shutdown] and 
+@method[drscheme:rep:text% on-close] methods.
+
+Calls the super method.
+
+
+}
+
+@defmethod[#:mode override 
+           (on-size)
+           void?]{
+
+Updates the preferences for the window width and height
+so next time a drscheme window is opened, it will be this
+width and height.
+
+
+}
+
+@defmethod[(still-untouched?)
+           boolean?]{
+@methspec{
+
+determines if the definitions window has not been
+modified. Used in conjunction with
+@method[drscheme:unit:frame% change-to-file].
+
+}
+@methimpl{
+
+Returns @scheme[#t] if the buffer is empty, it has not been
+saved and it is unmodified.
+
+
+}}
+
+@defmethod[(update-save-button [modified? any/c])
+           void?]{
+
+This method hides or shows the save button, based on
+the @scheme[modified?] argument. 
+
+If the save button has not been created yet, it remembers
+the @scheme[modified?] argument as an initial visibility for
+the save button.
+
+This method is called by the
+@method[drscheme:unit:definitions-text% set-modified] method.
+
+
+}
+
+@defmethod[(update-save-message [name string?])
+           void?]{
+
+Updates the save message on the drscheme frame. This method is called by
+the 
+@method[drscheme:unit:definitions-text% set-filename] method.
+
+
+}
+
+@defmethod[#:mode override 
+           (update-shown)
+           void?]{
+
+Updates the interactions, definitions, and contour menu
+items based on the contents of the windows.
+
+
+}}
+
+
+@definterface[drscheme:unit:frame<%> ()]{
+
+
+
+@defmethod[(ensure-defs-shown)
+           void?]{
+Ensures that the definitions window is visible.
+
+}
+
+@defmethod[(ensure-rep-hidden)
+           void?]{
+
+Makes sure the rep is hidden (by making the definitions window
+visible).
+
+
+}
+
+@defmethod[(ensure-rep-shown)
+           void?]{
+
+Shows the interactions window
+
+
+}
+
+@defmethod[(get-current-tab)
+           (is-a?/c @scheme[drscheme:unit:tab<%>])]{
+Returns the currently active tab.
+
+}
+
+@defmethod[(get-definitions-canvas)
+           (instanceof (derivedfrom @scheme[drscheme:unit:definitions-canvas%]))]{
+
+This canvas is the canvas containing the 
+@method[drscheme:unit:frame<%> get-definitions-text]. It is initially the top half of the drscheme window.
+
+This canvas defaults to a @scheme[drscheme:unit:definitions-canvas%]
+object, but if you change the
+@scheme[drscheme:get/extend:extend-definitions-canvas] procedure, it will use the class in the parameter to create the canvas.
+
+
+}
+
+@defmethod[(get-definitions-text)
+           (instaceof (derivedfrom @scheme[drscheme:unit:definitions-text%]))]{
+
+Calls result of
+@method[drscheme:unit:frame<%> get-current-tab]'s 
+@method[drscheme:unit:tab<%> get-ints] method.
+
+
+}
+
+@defmethod[(get-insert-menu)
+           (is-a?/c @scheme[menu%])]{
+@methspec{
+
+Returns the \scm|"Insert"| menu. 
+
+}
+@methimpl{
+
+
+
+}}
+
+@defmethod[(get-interactions-canvas)
+           (instanceof (derivedfrom @scheme[drscheme:unit:interactions-canvas%]))]{
+
+This canvas is the canvas containing the 
+@method[drscheme:unit:frame<%> get-interactions-text]. It is initially the bottom half of the drscheme window.
+
+This canvas defaults to a @scheme[drscheme:unit:interactions-canvas%]
+object, but if you use the
+@scheme[drscheme:get/extend:extend-interactions-canvas] procedure,
+it will use the extended class to create the canvas.
+
+
+}
+
+@defmethod[(get-interactions-text)
+           (instanceof (derivedfrom @scheme[drscheme:rep:text%]))]{
+
+Calls result of
+@method[drscheme:unit:frame<%> get-current-tab]'s 
+@method[drscheme:unit:tab<%> get-defs] method.
+
+
+}
+
+@defmethod[(get-tabs)
+           (listof @scheme[drscheme:unit:tab<%>])]{
+Returns the list of tabs in this frame.
+
+}
+
+@defmethod[#:mode pubment 
+           (on-tab-change [from-tab (is-a?/c @scheme[drscheme:unit:tab<%>])]
+                          [to-tab (is-a?/c @scheme[drscheme:unit:tab<%>])])
+           void?]{
+@methspec{
+
+Called after a new tab becomes the selected tab in the frame.
+
+}
+@methimpl{
+
+The @scheme[from-tab] argument is the previously selected tab, and the
+ @scheme[to-tab] argument is the newly selected tab.
+
+
+
+}}
+
+@defmethod[(register-capability-menu-item [key symbol]
+                                          [menu (is-a? @scheme[menu%])])
+           void?]{
+Registers the menu item that was most recently added as
+being controlled by the capability @scheme[key]. This means
+that the (boolean) value of the capability determines if the
+menu item is present in the menu (the capability is checked
+when the menus are cliked on).
+
+This assumes that the menu items in this menu are not moved
+around, except by the this capability. If they are, things
+can go funny ({\it i.e.}, no good checks are in place).
+
+Note that the capability must be registered separately, via
+@scheme[drscheme:language:register-capability].
+
+
+}}
+
+
+@defclass[drscheme:unit:definitions-text% (scheme:text-mixin drscheme:unit:program-editor-mixin drscheme:rep:drs-bindings-keymap-mixin drscheme:unit:definitions-text<%>) ()]{
+
+
+
+@defconstructor[()]{
+Passes all arguments to @scheme[super-init].
+}
+
+@defmethod[#:mode override 
+           (set-filename)
+           void?]{
+
+Calls
+@method[drscheme:unit:frame% update-save-message].
+
+
+}
+
+@defmethod[#:mode override 
+           (set-modified)
+           void?]{
+
+Calls
+@method[drscheme:unit:frame% update-save-button].
+
+%%                                                                  %%                        drscheme:rep                              %%                                                                  
+
+}}
+
+
+@definterface[drscheme:unit:definitions-text<%> ()]{
+
+This interface is implemented by the definitions text. 
+
+
+
+@defmethod[#:mode pubment 
+           (after-set-next-settings [language-settings language-settings])
+           void?]{
+@methspec{
+
+Called when the next settings changes. See also
+@method[drscheme:unit:definitions-text<%> get-next-settings].
+
+}
+@methimpl{
+
+
+
+
+}}
+
+@defmethod[(begin-metadata-changes)
+           void?]{
+Augment this method to be notified when DrScheme is changing
+the buffer to insert metadata. The metadata is only inserted
+during saving, so tools that track changes to DrScheme will
+need to ignore changes that occur after this method is
+called, and before
+@method[drscheme:unit:definitions-text<%> end-metadata-changes] is called.
+
+A call to @scheme[begin-metadata-changes] will always be
+followed with a call to @scheme[end-metadata-changes] (ie,
+the calls cannot be nested).
+
+}
+
+@defmethod[(end-metadata-changes)
+           void?]{
+Called when the changes to insert metadata are done, and the
+editor is back to its state at the time of the call to
+@method[drscheme:unit:definitions-text<%> begin-metadata-changes].
+
+A call to @scheme[begin-metadata-changes] will always be
+followed with a call to @scheme[end-metadata-changes] (ie,
+the calls cannot be nested).
+
+}
+
+@defmethod[(get-next-settings)
+           language-settings]{
+This method returns the language-settings that will be used
+when the user next clicks Run in this DrScheme window.
+
+}
+
+@defmethod[(get-port-name-identifier)
+           symbol]{
+
+Returns an identifier that can be used as a port's name when
+the editor is not saved. (If it is saved, the filename of
+the editor should be used.)
+
+
+}
+
+@defmethod[(get-tab)
+           (instanceof @scheme[drscheme:unit:tab%])]{
+Returns the editor's enclosing tab.
+
+}
+
+@defmethod[(port-name-matches? [id any])
+           boolean?]{
+
+Indicates if the name of a port (which is also saved in the
+source field of an exception record) matches this editor.
+
+
+}
+
+@defmethod[(set-needs-execution-message [msg string?])
+           void?]{
+@methspec{
+
+This method, when called, puts this drscheme window in a
+state such that interactions submitted to the REPL will
+trigger a yellow warning message. The state is reset when
+the program is next Run.
+
+}
+@methimpl{
+
+Records @scheme[msg] and uses it the next time the user submits
+an interaction (unless the Runs first).
+
+
+}}
+
+@defmethod[(set-next-settings [language-settings language-settings]
+                              [update-prefs? any/c @scheme[#t]])
+           void?]{
+
+Changes the language settings for this window. If
+@scheme[update-prefs?] is a true value, the preference is
+changed, which affects newly created windows.
+
+See also
+@method[drscheme:unit:definitions-text<%> after-set-next-settings] and
+@method[drscheme:unit:definitions-text<%> get-next-settings].
+
+
+}}
+
+
+@defclass[drscheme:unit:definitions-canvas% editor-canvas% ()]{
+
+Initializes the visibility of the save button.
+
+
+}
+