20 drracket:module-language-tools

If the result of read-language for a language is a function, DrRacket will query it to determine if there are any new toolbar buttons to be used when editing files in this language (when DrRacket’s language is set to the Module language).

Specifically, DrRacket will pass 'drracket:toolbar-buttons to the function and expect back a value matching this contract:

(or/c (listof (list/c string?
                      (is-a?/c bitmap%)
                      (-> (is-a?/c drracket:unit:frame<%>) any)
                      (or/c real? #f)))
      #f)

which is then used to create new toolbar buttons, one for each list in the first. The string is the label on the button; the bitmap is the icon (it should be 16x16); the function is called when the button is clicked; and the number is passed as the #:number argument to register-toolbar-button.

If the result is #f, then no toolbar buttons are created.

To implement functionality similar to the Run button, call the execute-callback method. You may also want to use the drracket:rep:after-expression parameter.

If 'drracket:toolbar-buttons is not recognized, DrRacket will also pass 'drscheme:toolbar-buttons; this is for backwards compatibility and new code should not use it. Similarly, if the fourth element from the list (the argument to #:number) is not present, then it is treated as #f.

procedure
(drracket:module-language-tools:add-opt-out-toolbar-button
make-button
id
[ #:number number])
→ void?
   make-button :
(-> (is-a?/c top-level-window<%>)
    (is-a?/c area-container<%>)
    (is-a?/c switchable-button%))
  id : symbol?
  number : (or/c real? #f) = #f

Call this function to add another button to DrRacket’s toolbar. When buttons are added this way, DrRacket monitors the #lang line at the top of the file; when it changes DrRacket queries the language to see if this button should be included. These buttons are “opt out”, meaning that if the language doesn’t explicitly ask to not have this button (or all such buttons), the button will appear.

The number argument is the same as the number argument to register-toolbar-button.

See read-language for more details on how a language can opt out. DrRacket will invoke the get-info proc from read-language with 'drracket:opt-out-toolbar-buttons (and 'drscheme:opt-out-toolbar-buttons for backwards compatibility). If the result is a list of symbols, the listed symbols are opted out. If the result is #f, all buttons are opted out. The default is the empty list, meaning that all opt-out buttons appear.

procedure
(drracket:module-language-tools:add-online-expansion-handler
mod-path
id
local-handler)
→ void?
  mod-path : path-string?
  id : symbol?
   local-handler :
(-> (is-a?/c drracket:unit:definitions-text<%>)
    any/c
    any)

Registers a pair of procedures with DrRacket’s online expansion machinery.

The first two arguments name a procedure in a module that is loaded by dynamic-require is a separate place. When DrRacket detects that the editor has been modified, it sends the contents of the editor over to that separate place, expands the program there, and then supplies the fully expanded object to that first procedure. (The procedure is called in the same context as the expansion process.)

The contract for that procedure is

(-> syntax? path? any/c custodian?
any)

There are three other arguments.

The path? argument is the path that was the current-directory when the code was expanded. This directory should be used as the current-directory when resolving module paths obtained from the syntax object.
The third argument is the source object used in the syntax objects that come from the definitions window in DrRacket. It may be a path (if the file was saved), but it also might not be. Use equal? to compare it with the syntax-source field of syntax objects to determine if they come from the definitions window.
Note that the thread that calls this procedure may be killed at any time: DrRacket may kill it when the user types in the buffer (in order to start a new expansion), but bizarro code may also create a separate thread during expansion that lurks around and then mutates arbitrary things.
Some code, however, should be longer running, surviving such custodian shutdowns. To support this, the procedure called in the separate place is supplied with a more powerful custodian that is not shut down.

The result of the procedure is expected to be something that can be sent across a place-channel, which is then sent back to the original place where DrRacket itself is running and passed to the local-handler argument. At this point, the only code running is trusted code (DrRacket itself and other tools), but any long running computations may freeze DrRacket’s GUI, since this procedure is invoked on DrRacket’s eventspace’s handler thread.

procedure
(drracket:module-language-tools:register-online-expansion-pref func)
→ void?
func : (-> (is-a?/c vertical-panel%) void?)

Registers func so that it is called while building the preferences panel. The function is passed a panel that contains other configuration controls for online expansion.

top ← prev up next →

1	Implementing Dr Racket Plugins
2	Adding Languages to Dr Racket
3	Creating New Kinds of Dr Racket Frames
4	Extending the Existing Dr Racket Classes
5	Expanding the User’s Program Text and Breaking
6	Editor Modes
7	Language-Specific Capabilities
8	Check Syntax
9	Teaching Languages
10	drracket: get/ extend
11	drracket: unit
12	drracket: language
13	drracket: language-configuration
14	drracket: debug
15	drracket: rep
16	drracket: frame
17	drracket: help-desk
18	drracket: eval
19	drracket: modes
20	drracket: module-language-tools
21	drracket: module-language
22	Backwards Compatibility
	Index