misc rackety docs

This commit is contained in:
Matthew Flatt 2010-05-05 12:09:14 -06:00
parent 947bf8e109
commit c13d65d23d
8 changed files with 175 additions and 175 deletions

View File

@ -7,52 +7,52 @@
browser/htmltext browser/htmltext
browser/external browser/external
browser/tool browser/tool
scheme/base racket/base
scheme/contract racket/contract
scheme/class racket/class
scheme/gui/base racket/gui/base
net/url net/url
framework/framework)) framework/framework))
@(define-syntax-rule (def-ext id) @(define-syntax-rule (def-ext id)
(begin (begin
(require (for-label net/sendurl)) (require (for-label net/sendurl))
(define id (scheme send-url)))) (define id (racket send-url))))
@(def-ext net-send-url) @(def-ext net-send-url)
@title{@bold{Browser}: Simple HTML Rendering} @title{@bold{Browser}: Simple HTML Rendering}
The @schememodname[browser] library provides the following procedures The @racketmodname[browser] library provides the following procedures
and classes for parsing and viewing HTML files. The and classes for parsing and viewing HTML files. The
@schememodname[browser/htmltext] library provides a simplified interface @racketmodname[browser/htmltext] library provides a simplified interface
for rendering to a subclass of the MrEd @scheme[text%] class. The for rendering to a subclass of the GRacket @racket[text%] class. The
@schememodname[browser/external] library provides utilities for @racketmodname[browser/external] library provides utilities for
launching an external browser (such as Firefox). launching an external browser (such as Firefox).
@section[#:tag "browser"]{Browser} @section[#:tag "browser"]{Browser}
@defmodule[browser] @defmodule[browser]
The browser supports basic HTML commands, plus special Scheme hyperlinks The browser supports basic HTML commands, plus special Racket hyperlinks
of the form @litchar{<A MZSCHEME=sexpr>...</A>}. When the user clicks of the form @litchar{<A MZSCHEME=sexpr>...</A>}. When the user clicks
on such a link, the string @scheme[sexpr] is parsed as a Scheme program on such a link, the string @racket[sexpr] is parsed as a Racket program
and evaluated. Since @scheme[sexpr] is likely to contain Scheme and evaluated. Since @racket[sexpr] is likely to contain Racket
strings, and since escape characters are difficult for people to read, a strings, and since escape characters are difficult for people to read, a
@litchar{|} character in @scheme[sexpr] is converted to a @litchar{"} @litchar{|} character in @racket[sexpr] is converted to a @litchar{"}
character before it is parsed. Thus, character before it is parsed. Thus,
@verbatim[#:indent 2]{ @verbatim[#:indent 2]{
<A MZSCHEME="|This goes nowhere.|">Nowhere</A> <A MZSCHEME="|This goes nowhere.|">Nowhere</A>
} }
creates a ``Nowhere'' hyperlink, which executes the Scheme program creates a ``Nowhere'' hyperlink, which executes the Racket program
@schemeblock[ @racketblock[
"This goes nowhere." "This goes nowhere."
] ]
The value of that program is a string. When a Scheme hyperlink returns The value of that program is a string. When a Racket hyperlink returns
a string, it is parsed as a new HTML document. Thus, where the use a string, it is parsed as a new HTML document. Thus, where the use
clicks on ``Nowhere,'' the result is a new page that says ``This goes clicks on ``Nowhere,'' the result is a new page that says ``This goes
nowhere.'' nowhere.''
@ -75,16 +75,16 @@ of a string, it replaces the comment in the document. Other types of
return values are ignored. return values are ignored.
If the html file is being accessed as a @litchar{file:} url, the If the html file is being accessed as a @litchar{file:} url, the
@scheme[current-load-relative-directory] parameter is set to the @racket[current-load-relative-directory] parameter is set to the
directory during the evaluation of the mzscheme code (in both directory during the evaluation of the mzracket code (in both
examples). The Scheme code is executed through @scheme[eval]. examples). The Racket code is executed through @racket[eval].
The @litchar{MZSCHEME} forms are disabled unless the web page is a The @litchar{MZSCHEME} forms are disabled unless the web page is a
@litchar{file:} url that points into the @scheme[doc] collection. @litchar{file:} url that points into the @racket[doc] collection.
@defproc[(open-url [url (or/c url? string? input-port?)]) (is-a?/c hyper-frame%)]{ @defproc[(open-url [url (or/c url? string? input-port?)]) (is-a?/c hyper-frame%)]{
Opens the given url in a vanilla browser frame and returns the Opens the given url in a vanilla browser frame and returns the
frame. The frame is an instance of @scheme[hyper-frame%]. frame. The frame is an instance of @racket[hyper-frame%].
} }
@defboolparam[html-img-ok ok?]{ @defboolparam[html-img-ok ok?]{
@ -102,13 +102,13 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmixin[hyper-frame-mixin (frame%) ()]{ @defmixin[hyper-frame-mixin (frame%) ()]{
@defconstructor/auto-super[([url (or/c url? string? input-port?)])]{ @defconstructor/auto-super[([url (or/c url? string? input-port?)])]{
Shows the frame and visits @scheme[url]. Shows the frame and visits @racket[url].
} }
@defmethod[(get-hyper-panel%) (subclass?/c panel%)]{ @defmethod[(get-hyper-panel%) (subclass?/c panel%)]{
Returns the class that is instantiated when the frame is created. Returns the class that is instantiated when the frame is created.
Must be a panel with hyper-panel-mixin mixed in. Defaults to just Must be a panel with hyper-panel-mixin mixed in. Defaults to just
returning @scheme[hyper-panel%]. returning @racket[hyper-panel%].
} }
@defmethod[(get-hyper-panel) (is-a?/c panel%)]{ @defmethod[(get-hyper-panel) (is-a?/c panel%)]{
@ -125,7 +125,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------
@defmixin[hyper-no-show-frame-mixin (frame%) ()]{ @defmixin[hyper-no-show-frame-mixin (frame%) ()]{
The same as the @scheme[hyper-frame-mixin], except that it doesn't The same as the @racket[hyper-frame-mixin], except that it doesn't
show the frame and the initialization arguments are unchanged. show the frame and the initialization arguments are unchanged.
} }
@ -139,21 +139,21 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmixin[hyper-text-mixin (text%) ()]{ @defmixin[hyper-text-mixin (text%) ()]{
An instance of a @scheme[hyper-text-mixin]-extended class should be An instance of a @racket[hyper-text-mixin]-extended class should be
displayed only in an instance of a class created with displayed only in an instance of a class created with
@scheme[hyper-canvas-mixin]. @racket[hyper-canvas-mixin].
@defconstructor/auto-super[([url (or/c url? string? input-port?)] @defconstructor/auto-super[([url (or/c url? string? input-port?)]
[status-frame [status-frame
(or/c (is-a?/c top-level-window<%>) false/c)] (or/c (is-a?/c top-level-window<%>) false/c)]
[post-data (or/c false/c bytes?)])]{ [post-data (or/c false/c bytes?)])]{
The @scheme[url] is loaded into the @scheme[text%] object (using the The @racket[url] is loaded into the @racket[text%] object (using the
@method[hyper-text-mixin reload] method), a top-level window for @method[hyper-text-mixin reload] method), a top-level window for
status messages and dialogs, a progress procedure used as for status messages and dialogs, a progress procedure used as for
@scheme[get-url], and either @scheme[#f] or a post string to be sent @racket[get-url], and either @racket[#f] or a post string to be sent
to a web server (technically changing the GET to a POST). to a web server (technically changing the GET to a POST).
Sets the autowrap-bitmap to @scheme[#f]. Sets the autowrap-bitmap to @racket[#f].
} }
@defmethod[(map-shift-style [start exact-nonnegative-integer?] @defmethod[(map-shift-style [start exact-nonnegative-integer?]
@ -170,7 +170,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
} }
@defmethod[(get-url) (or/c url? string? input-port? false/c)]{ @defmethod[(get-url) (or/c url? string? input-port? false/c)]{
Returns the URL displayed by the editor, or @scheme[#f] if there is Returns the URL displayed by the editor, or @racket[#f] if there is
none. none.
} }
@ -194,9 +194,9 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
(or/c exact-nonnegative-integer? false/c)]{ (or/c exact-nonnegative-integer? false/c)]{
Finds the location of a tag in the buffer (where tags are installed Finds the location of a tag in the buffer (where tags are installed
in HTML with @litchar{<A NAME="name">}) and returns its position. in HTML with @litchar{<A NAME="name">}) and returns its position.
If @scheme[name] is a number, the number is returned (assumed to be If @racket[name] is a number, the number is returned (assumed to be
an offset rather than a tag). Otherwise, if the tag is not found, an offset rather than a tag). Otherwise, if the tag is not found,
@scheme[#f] is returned. @racket[#f] is returned.
} }
@defmethod[(remove-tag [name string?]) void?]{ @defmethod[(remove-tag [name string?]) void?]{
@ -215,11 +215,11 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
Installs a hyperlink. Installs a hyperlink.
} }
@defmethod[(add-scheme-callback [start exact-nonnegative-integer?] @defmethod[(add-racket-callback [start exact-nonnegative-integer?]
[end exact-nonnegative-integer?] [end exact-nonnegative-integer?]
[scheme-expr string?]) [racket-expr string?])
void?]{ void?]{
Installs a Scheme evaluation hyperlink. Installs a Racket evaluation hyperlink.
} }
@defmethod[(add-thunk-callback [start exact-nonnegative-integer?] @defmethod[(add-thunk-callback [start exact-nonnegative-integer?]
@ -229,7 +229,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
Installs a thunk-based hyperlink. Installs a thunk-based hyperlink.
} }
@defmethod[(eval-scheme-string [str string?]) any]{ @defmethod[(eval-racket-string [str string?]) any]{
Called to handle the @litchar{<A MZSCHEME="expr">...</A>} tag and Called to handle the @litchar{<A MZSCHEME="expr">...</A>} tag and
@litchar{<! MZSCHEME="expr">} comments (see above). Evaluates the @litchar{<! MZSCHEME="expr">} comments (see above). Evaluates the
string; if the result is a string, it is opened as an HTML page. string; if the result is a string, it is opened as an HTML page.
@ -239,13 +239,13 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
Reloads the current page. Reloads the current page.
The text defaultly uses the basic style named The text defaultly uses the basic style named
@scheme["Html Standard"] in the editor (if it exists). @racket["Html Standard"] in the editor (if it exists).
} }
@defmethod[(remap-url [url (or/c url? string?)]) (or/c url? string?)]{ @defmethod[(remap-url [url (or/c url? string?)]) (or/c url? string?)]{
When visiting a new page, this method is called to remap the url. When visiting a new page, this method is called to remap the url.
The remapped url is used in place of the original url. If this The remapped url is used in place of the original url. If this
method returns @scheme[#f], the page doesn't go anywhere. method returns @racket[#f], the page doesn't go anywhere.
This method may be killed (if the user clicks the ``stop'' button). This method may be killed (if the user clicks the ``stop'' button).
} }
@ -261,7 +261,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defclass[hyper-text% (hyper-text-mixin text:keymap%) ()]{ @defclass[hyper-text% (hyper-text-mixin text:keymap%) ()]{
Extends the @scheme[text:keymap%] class to support standard key Extends the @racket[text:keymap%] class to support standard key
bindings in the browser window. bindings in the browser window.
} }
@ -270,8 +270,8 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmixin[hyper-canvas-mixin (editor-canvas%) ()]{ @defmixin[hyper-canvas-mixin (editor-canvas%) ()]{
A @scheme[hyper-can-mixin]-extended canvas's parent should be an A @racket[hyper-can-mixin]-extended canvas's parent should be an
instance of a class derived with @scheme[hyper-panel-mixin]. instance of a class derived with @racket[hyper-panel-mixin].
@defconstructor/auto-super[()]{ @defconstructor/auto-super[()]{
} }
@ -279,8 +279,8 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmethod[(get-editor%) (subclass?/c text%)]{ @defmethod[(get-editor%) (subclass?/c text%)]{
Returns the class used to implement the editor in the browser Returns the class used to implement the editor in the browser
window. It should be derived from @scheme[hyper-text%] and should window. It should be derived from @racket[hyper-text%] and should
pass on the initialization arguments to @scheme[hyper-text%]. pass on the initialization arguments to @racket[hyper-text%].
The dynamic extent of the initialization of this editor is called on The dynamic extent of the initialization of this editor is called on
a thread that may be killed (via a custodian shutdown). In that a thread that may be killed (via a custodian shutdown). In that
@ -299,30 +299,30 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
[post-data (or/c bytes? false/c) #f]) [post-data (or/c bytes? false/c) #f])
void?]{ void?]{
Changes to the given url, loading it by calling the Changes to the given url, loading it by calling the
@scheme[make-editor] method. If @scheme[relative-to-url] is not @racket[make-editor] method. If @racket[relative-to-url] is not
@scheme[#f], it must be a URL for resolving @scheme[url] as a @racket[#f], it must be a URL for resolving @racket[url] as a
relative URL. @scheme[url] may also be a port, in which case, relative URL. @racket[url] may also be a port, in which case,
@scheme[relative-to-url] must be @scheme[#f]. @racket[relative-to-url] must be @racket[#f].
The @scheme[progress-proc] procedure is called with a boolean at the The @racket[progress-proc] procedure is called with a boolean at the
point where the URL has been resolved and enough progress has been point where the URL has been resolved and enough progress has been
made to dismiss any message that the URL is being resolved. The made to dismiss any message that the URL is being resolved. The
procedure is called with @scheme[#t] if the URL will be loaded into procedure is called with @racket[#t] if the URL will be loaded into
a browser window, @scheme[#f] otherwise (e.g., the user will save a browser window, @racket[#f] otherwise (e.g., the user will save
the URL content to a file). the URL content to a file).
If @scheme[post-data-bytes] is a byte string instead of false, the If @racket[post-data-bytes] is a byte string instead of false, the
URL GET is changed to a POST with the given data. URL GET is changed to a POST with the given data.
} }
@defmethod[(set-page [page any/c] [notify? any/c]) void?]{ @defmethod[(set-page [page any/c] [notify? any/c]) void?]{
Changes to the given page. If @scheme[notify?] is not @scheme[#f], Changes to the given page. If @racket[notify?] is not @racket[#f],
the canvas's parent is notified about the change by calling its the canvas's parent is notified about the change by calling its
@scheme[leaving-page] method. @racket[leaving-page] method.
} }
@defmethod[(after-set-page) void?]{ @defmethod[(after-set-page) void?]{
Called during @scheme[set-page]. Defaultly does nothing. Called during @racket[set-page]. Defaultly does nothing.
} }
} }
@ -334,28 +334,28 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
Creates controls and a hyper text canvas. The controls permit a Creates controls and a hyper text canvas. The controls permit a
user to move back and forth in the hypertext history. user to move back and forth in the hypertext history.
The @scheme[info-line?] argument indicates whether the browser The @racket[info-line?] argument indicates whether the browser
should contain a line to display special @litchar{DOCNOTE} tags in a should contain a line to display special @litchar{DOCNOTE} tags in a
page. Such tags are used primarily by the PLT documentation. page. Such tags are used primarily by the PLT documentation.
} }
@defmethod[(make-canvas [container (is-a?/c area-container<%>)]) void?]{ @defmethod[(make-canvas [container (is-a?/c area-container<%>)]) void?]{
Creates the panel's hypertext canvas, an instance of a class derived Creates the panel's hypertext canvas, an instance of a class derived
using @scheme[hyper-canvas-mixin]. This method is called during using @racket[hyper-canvas-mixin]. This method is called during
initialization. initialization.
} }
@defmethod[(get-canvas%) (subclass?/c editor-canvas%)]{ @defmethod[(get-canvas%) (subclass?/c editor-canvas%)]{
Returns the class instantiated by make-canvas. It must be derived Returns the class instantiated by make-canvas. It must be derived
from @scheme[hyper-canvas-mixin]. from @racket[hyper-canvas-mixin].
} }
@defmethod[(make-control-bar-panel [container (is-a?/c area-container<%>)]) @defmethod[(make-control-bar-panel [container (is-a?/c area-container<%>)])
any/c]{ any/c]{
Creates the panel's sub-container for the control bar containing the Creates the panel's sub-container for the control bar containing the
navigation buttons. If @scheme[#f] is returned, the panel will have navigation buttons. If @racket[#f] is returned, the panel will have
no control bar. The default method instantiates no control bar. The default method instantiates
@scheme[horizontal-panel%]. @racket[horizontal-panel%].
} }
@defmethod[(rewind) void?]{ @defmethod[(rewind) void?]{
@ -373,15 +373,15 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmethod[(on-navigate) void?]{ @defmethod[(on-navigate) void?]{
Callback that is invoked any time the displayed hypertext page Callback that is invoked any time the displayed hypertext page
changes (either by clicking on a link in the canvas or by changes (either by clicking on a link in the canvas or by
@scheme[rewind] or @scheme[forward] calls). @racket[rewind] or @racket[forward] calls).
} }
@defmethod[(leaving-page [page any/c] [new-page any/c]) @defmethod[(leaving-page [page any/c] [new-page any/c])
any]{ any]{
This method is called by the hypertext canvas to notify the panel This method is called by the hypertext canvas to notify the panel
that the hypertext page changed. The @scheme[page] is @scheme[#f] that the hypertext page changed. The @racket[page] is @racket[#f]
if @scheme[new-page] is the first page for the canvas. See also if @racket[new-page] is the first page for the canvas. See also
@scheme[page->editor]. @racket[page->editor].
} }
@defmethod[(filter-notes [notes (listof string?)]) @defmethod[(filter-notes [notes (listof string?)])
@ -391,7 +391,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
} }
@defmethod[(reload) void?]{ @defmethod[(reload) void?]{
Reloads the currently visible page by calling the @scheme[reload] Reloads the currently visible page by calling the @racket[reload]
method of the currently displayed hyper-text. method of the currently displayed hyper-text.
} }
} }
@ -404,7 +404,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defproc[(editor->page [editor (is-a?/c text%)]) any/c]{ @defproc[(editor->page [editor (is-a?/c text%)]) any/c]{
Creates a page record for the given editor, suitable for use with the Creates a page record for the given editor, suitable for use with the
@scheme[set-page] method of @scheme[hyper-canvas-mixin]. @racket[set-page] method of @racket[hyper-canvas-mixin].
} }
@defproc[(page->editor [page any/c]) (is-a?/c text%)]{ @defproc[(page->editor [page any/c]) (is-a?/c text%)]{
@ -416,7 +416,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
} }
@defclass[image-map-snip% snip% ()]{ @defclass[image-map-snip% snip% ()]{
Instances of this class behave like @scheme[image-snip%] objects, Instances of this class behave like @racket[image-snip%] objects,
except they have a @litchar{<map> ... </map>} associated with them and except they have a @litchar{<map> ... </map>} associated with them and
when clicking on them (in the map) they will cause their init arg text when clicking on them (in the map) they will cause their init arg text
to follow the corresponding link. to follow the corresponding link.
@ -425,7 +425,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
} }
@defmethod[(set-key [key string?]) void?]{ @defmethod[(set-key [key string?]) void?]{
Sets the key for the image map (eg, @scheme["#key"]). Sets the key for the image map (eg, @racket["#key"]).
} }
@defmethod[(get-key) string?]{ @defmethod[(get-key) string?]{
@ -436,8 +436,8 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
[region (listof number?)] [region (listof number?)]
[href string?]) [href string?])
void?]{ void?]{
Registers the shape named by @scheme[shape] whose coordinates are Registers the shape named by @racket[shape] whose coordinates are
specified by @scheme[region] to go to @scheme[href] when that region specified by @racket[region] to go to @racket[href] when that region
of the image is clicked on. of the image is clicked on.
} }
} }
@ -449,8 +449,8 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmodule[browser/browser-unit] @defmodule[browser/browser-unit]
@defthing[browser@ unit?]{ @defthing[browser@ unit?]{
Imports @scheme[mred^], @scheme[tcp^], and @scheme[url^], and exports Imports @racket[mred^], @racket[tcp^], and @racket[url^], and exports
@scheme[browser^]. @racket[browser^].
} }
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------
@ -460,7 +460,7 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmodule[browser/browser-sig] @defmodule[browser/browser-sig]
@defsignature[browser^ ()]{ @defsignature[browser^ ()]{
Includes all of the bindings of the @schememodname[browser] library. Includes all of the bindings of the @racketmodname[browser] library.
} }
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------
@ -472,12 +472,12 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@definterface[html-text<%> (text%)]{ @definterface[html-text<%> (text%)]{
@defmethod[(get-url) (or/c url? string? false/c)]{ @defmethod[(get-url) (or/c url? string? false/c)]{
Returns a base URL used for building relative URLs, or @scheme[#f] Returns a base URL used for building relative URLs, or @racket[#f]
if no base is available. if no base is available.
} }
@defmethod[(set-title [str string?]) void?]{ @defmethod[(set-title [str string?]) void?]{
Registers the title @scheme[str] for the rendered page. Registers the title @racket[str] for the rendered page.
} }
@defmethod[(add-link [start exact-nonnegative-integer?] @defmethod[(add-link [start exact-nonnegative-integer?]
@ -497,11 +497,11 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
Changes the style for the given range to the link style. Changes the style for the given range to the link style.
} }
@defmethod[(add-scheme-callback [start exact-nonnegative-integer?] @defmethod[(add-racket-callback [start exact-nonnegative-integer?]
[end exact-nonnegative-integer?] [end exact-nonnegative-integer?]
[scheme-expr string?]) [racket-expr string?])
void?]{ void?]{
Installs a Scheme evaluation hyperlink. Installs a Racket evaluation hyperlink.
} }
@defmethod[(add-thunk-callback [start exact-nonnegative-integer?] @defmethod[(add-thunk-callback [start exact-nonnegative-integer?]
@ -519,9 +519,9 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmixin[html-text-mixin (text%) ()]{ @defmixin[html-text-mixin (text%) ()]{
Extends the given @scheme[text%] class with implementations of the Extends the given @racket[text%] class with implementations of the
@scheme[html-text<%>] methods. Hyperlinks are attached to clickbacks @racket[html-text<%>] methods. Hyperlinks are attached to clickbacks
that use @net-send-url from @schememodname[net/sendurl]. that use @net-send-url from @racketmodname[net/sendurl].
} }
@defproc[(render-html-to-text [in input-port?] @defproc[(render-html-to-text [in input-port?]
@ -529,12 +529,12 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
[load-img? any/c] [load-img? any/c]
[eval-mz? any/c]) [eval-mz? any/c])
void?]{ void?]{
Reads HTML from @scheme[in] and renders it to @scheme[dest]. If Reads HTML from @racket[in] and renders it to @racket[dest]. If
@scheme[load-img?] is @scheme[#f], then images are rendered as Xed-out @racket[load-img?] is @racket[#f], then images are rendered as Xed-out
boxes. If @scheme[eval-mz?] is @scheme[#f], then @litchar{MZSCHEME} boxes. If @racket[eval-mz?] is @racket[#f], then @litchar{MZSCHEME}
hyperlink expressions and comments are not evaluated. hyperlink expressions and comments are not evaluated.
Uses the style named @scheme["Html Standard"] in the editor's Uses the style named @racket["Html Standard"] in the editor's
style-list (if it exists) for all of the inserted text's default style-list (if it exists) for all of the inserted text's default
style. style.
} }
@ -546,21 +546,21 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defmodule[browser/external] @defmodule[browser/external]
@defproc[(send-url [str null] [separate-window? void #t]) null]{ @defproc[(send-url [str null] [separate-window? void #t]) null]{
Like @net-send-url from @scheme[net/sendurl], but under Unix, the user Like @net-send-url from @racket[net/sendurl], but under Unix, the user
is prompted for a browser to use if none is recorded in the is prompted for a browser to use if none is recorded in the
preferences file. preferences file.
} }
@defproc[(browser-preference? [v any/c]) boolean?]{ @defproc[(browser-preference? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a valid browser preference. Returns @racket[#t] if @racket[v] is a valid browser preference.
} }
@defproc[(update-browser-preference [url (or/c string? false/c)]) void?]{ @defproc[(update-browser-preference [url (or/c string? false/c)]) void?]{
Under Unix, prompts the user for a browser preference and records the Under Unix, prompts the user for a browser preference and records the
user choice as a framework preference (even if one is already user choice as a framework preference (even if one is already
recorded). If @scheme[url] is not @scheme[#f], it is used in the recorded). If @racket[url] is not @racket[#f], it is used in the
dialog to explain which URL is to be opened; if it is @scheme[#f], the dialog to explain which URL is to be opened; if it is @racket[#f], the
@scheme['internal] will be one of the options for the user. @racket['internal] will be one of the options for the user.
} }
@defproc[(install-help-browser-preference-panel) void?]{ @defproc[(install-help-browser-preference-panel) void?]{
@ -569,19 +569,19 @@ The @litchar{MZSCHEME} forms are disabled unless the web page is a
@defproc[(add-to-browser-prefs-panel [proc ((is-a?/c panel%) . -> . any)]) @defproc[(add-to-browser-prefs-panel [proc ((is-a?/c panel%) . -> . any)])
void?]{ void?]{
The @scheme[proc] is called when the ``Browser'' panel is constructed The @racket[proc] is called when the ``Browser'' panel is constructed
for preferences. The supplied argument is the panel, so @scheme[proc] for preferences. The supplied argument is the panel, so @racket[proc]
can add additional option controls. If the panel is already created, can add additional option controls. If the panel is already created,
@scheme[proc] is called immediately. @racket[proc] is called immediately.
} }
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------
@section[#:tag "tool"]{DrScheme Browser Preference Panel} @section[#:tag "tool"]{DrRacket Browser Preference Panel}
@defmodule[browser/tool] @defmodule[browser/tool]
@defthing[tool@ unit?]{ @defthing[tool@ unit?]{
A unit that implements a DrScheme tool to add the ``Browser'' A unit that implements a DrRacket tool to add the ``Browser''
preference panel. preference panel.
} }

View File

@ -260,7 +260,7 @@ plots, fit curves to data, and some useful miscellaneous functions.
@subsection{Plotting} @subsection{Plotting}
The @scheme[plot] and @scheme[plot3d] functions generate plots that can be The @scheme[plot] and @scheme[plot3d] functions generate plots that can be
viewed in the DrScheme interactions window. viewed in the DrRacket interactions window.
@defproc[(plot [data ((is-a?/c 2d-view%) . -> . void?)] @defproc[(plot [data ((is-a?/c 2d-view%) . -> . void?)]
[#:width width real? 400] [#:width width real? 400]

View File

@ -1,6 +1,6 @@
#lang scribble/doc #lang scribble/doc
@(require "common.ss" @(require "common.ss"
(for-label scheme/class)) (for-label racket/class))
@title[#:tag "bitmaps"]{Bitmaps} @title[#:tag "bitmaps"]{Bitmaps}
@ -15,14 +15,14 @@
exact-integer?]{ exact-integer?]{
Converts the given bitmap into an OpenGL list that can be rendered Converts the given bitmap into an OpenGL list that can be rendered
with @scheme[gl-call-list] or @scheme[glCallList]. The rendered object with @racket[gl-call-list] or @racket[glCallList]. The rendered object
is a square on the @math{z=0} plane with corners at @math{(0,0)} and is a square on the @math{z=0} plane with corners at @math{(0,0)} and
@math{(1,1)}. @math{(1,1)}.
The @scheme[with-gl-proc] must accept a thunk and call it while the The @racket[with-gl-proc] must accept a thunk and call it while the
relevant OpenGL context is selected. Otherwise, the relevant OpenGL relevant OpenGL context is selected. Otherwise, the relevant OpenGL
context must be selected already. context must be selected already.
If @scheme[mask] is not @scheme[#f], it is used as the mask bitmap for If @racket[mask] is not @racket[#f], it is used as the mask bitmap for
extracting alpha values.} extracting alpha values.}

View File

@ -1,18 +1,18 @@
#lang scribble/doc #lang scribble/doc
@(require "common.ss" @(require "common.ss"
scribble/bnf scribble/bnf
(for-syntax scheme/base)) (for-syntax racket/base))
@title[#:tag "gl-vectors"]{OpenGL Vectors} @title[#:tag "gl-vectors"]{OpenGL Vectors}
@defmodule[sgl/gl-vectors] @defmodule[sgl/gl-vectors]
The @schememodname[sgl/gl-vectors] module supports OpenGL programming The @racketmodname[sgl/gl-vectors] module supports OpenGL programming
with @scheme[cvector]s. In this document and in the error messages, a with @racket[cvector]s. In this document and in the error messages, a
``gl-vector'' is just a @scheme[cvector], while a ``gl-vector'' is just a @racket[cvector], while a
``gl-@nonterm{type}-vector'' is a @scheme[cvector] with an appropriate ``gl-@nonterm{type}-vector'' is a @racket[cvector] with an appropriate
type. Using the @schememodname[sgl/gl-vectors] module instead of using type. Using the @racketmodname[sgl/gl-vectors] module instead of using
@scheme[cvector] directly because these functions are specialized to @racket[cvector] directly because these functions are specialized to
handling the OpenGL types correctly. handling the OpenGL types correctly.
@deftogether[( @deftogether[(
@ -24,7 +24,7 @@ handling the OpenGL types correctly.
@defproc[(gl-vector-set! [vec cvector?][pos exact-nonnegative-integer?][v any/v]) void?] @defproc[(gl-vector-set! [vec cvector?][pos exact-nonnegative-integer?][v any/v]) void?]
)]{ )]{
Synonyms for @scheme[cvector?], @scheme[cvector->vector], @scheme[cvector-length], etc.} Synonyms for @racket[cvector?], @racket[cvector->vector], @racket[cvector-length], etc.}
@(define-syntax (define-gl-vector stx) @(define-syntax (define-gl-vector stx)
(syntax-case stx () (syntax-case stx ()
@ -66,10 +66,10 @@ Synonyms for @scheme[cvector?], @scheme[cvector->vector], @scheme[cvector-length
@defproc[(gl-<type>-vector* [x real?][vec gl-<type>-vector?]) gl-<type>-vector?] @defproc[(gl-<type>-vector* [x real?][vec gl-<type>-vector?]) gl-<type>-vector?]
)]{ )]{
Operations on vectors of @scheme[<type>] elements. The @scheme[gl-<type>-vector+] Operations on vectors of @racket[<type>] elements. The @racket[gl-<type>-vector+]
and @scheme[gl-<type>-vector-] functions compute the element-by-element sum and and @racket[gl-<type>-vector-] functions compute the element-by-element sum and
difference of the given vectors, respectively. The @scheme[gl-<type>-vector*] function difference of the given vectors, respectively. The @racket[gl-<type>-vector*] function
multiplies each element of @scheme[vec] by @scheme[x].})))])) multiplies each element of @racket[vec] by @racket[x].})))]))
@(define-gl-vector byte) @(define-gl-vector byte)
@(define-gl-vector ubyte) @(define-gl-vector ubyte)
@ -84,5 +84,5 @@ Synonyms for @scheme[cvector?], @scheme[cvector->vector], @scheme[cvector-length
@defproc[(gl-vector-norm [vec gl-vector?]) real?]{ @defproc[(gl-vector-norm [vec gl-vector?]) real?]{
Returns the square root of the sum of the squares of the elements Returns the square root of the sum of the squares of the elements
of @scheme[vec].} of @racket[vec].}

View File

@ -2,16 +2,16 @@
@(require "common.ss" @(require "common.ss"
scribble/bnf scribble/bnf
scribble/eval scribble/eval
(for-syntax scheme/base)) (for-syntax racket/base))
@title[#:tag "gl"]{C-Style OpenGL} @title[#:tag "gl"]{C-Style OpenGL}
@defmodule[sgl/gl] @defmodule[sgl/gl]
The @schememodname[sgl/gl] module provides a direct interface to the The @racketmodname[sgl/gl] module provides a direct interface to the
system's GL library closely following the conventions of the system's GL library closely following the conventions of the
C-language OpenGL API. It provides a binding for each @tt{#defined} C-language OpenGL API. It provides a binding for each @tt{#defined}
constant (these start with @schemeidfont{GL_}) and for the functions constant (these start with @racketidfont{GL_}) and for the functions
in the GL 1.5 and GLU 1.3 specifications, except for the following: in the GL 1.5 and GLU 1.3 specifications, except for the following:
@itemize[#:style 'compact @itemize[#:style 'compact
@ -26,13 +26,13 @@ in the GL 1.5 and GLU 1.3 specifications, except for the following:
If one of the provided functions is not present on your system If one of the provided functions is not present on your system
(e.g. if your system supports only GL 1.3), then the corresponding (e.g. if your system supports only GL 1.3), then the corresponding
@schememodname[sgl/gl] function raises a run-time exception when @racketmodname[sgl/gl] function raises a run-time exception when
invoked. invoked.
The functions provided by @schememodname[sgl/gl] perform comparable The functions provided by @racketmodname[sgl/gl] perform comparable
checking to their C-language counterparts; they check the types of checking to their C-language counterparts; they check the types of
their arguments, but do not check the length of array arguments. The their arguments, but do not check the length of array arguments. The
following details the kinds of Scheme values that can be provided for following details the kinds of Racket values that can be provided for
each primitive OpenGL type: each primitive OpenGL type:
@itemize[ @itemize[
@ -60,24 +60,24 @@ each primitive OpenGL type:
@as-index{@tt{GLclampd}}: @as-index{@tt{GLclampd}}:
real number} real number}
@item{@as-index{@tt{GLboolean}}: any value, where @scheme[#f] means @item{@as-index{@tt{GLboolean}}: any value, where @racket[#f] means
@as-index{@tt{GL_FALSE}} and all other values mean @as-index{@tt{GL_FALSE}} and all other values mean
@as-index{@tt{GL_TRUE}}; do not use @scheme[GL_FALSE] or @as-index{@tt{GL_TRUE}}; do not use @racket[GL_FALSE] or
@scheme[GL_TRUE], since they are bound to integers, both will @racket[GL_TRUE], since they are bound to integers, both will
end up being converted to GL_TRUE.} end up being converted to GL_TRUE.}
] ]
OpenGL functions that take vector arguments accept @scheme[cvector] OpenGL functions that take vector arguments accept @racket[cvector]
values. The type of the @scheme[cvector] is checked; for example, values. The type of the @racket[cvector] is checked; for example,
@tt{glVertex3fv} expects a vector of @tt{GLfloats}, so @tt{glVertex3fv} expects a vector of @tt{GLfloats}, so
@scheme[glVertex3fv] accepts only a @scheme[cvector] containing reals. @racket[glVertex3fv] accepts only a @racket[cvector] containing reals.
See also @schememodname[sgl/gl-vectors]. Functions that accept arrays See also @racketmodname[sgl/gl-vectors]. Functions that accept arrays
of type @tt{void*} accept any @scheme[cvector]; you must ensure that of type @tt{void*} accept any @racket[cvector]; you must ensure that
you supply the proper kind of vector, as in the C-language OpenGL API. you supply the proper kind of vector, as in the C-language OpenGL API.
@as-examples[ @as-examples[
@schemeblock[ @racketblock[
(require sgl/gl (require sgl/gl
sgl/gl-vectors) sgl/gl-vectors)
(glBegin GL_TRIANGLES) (glBegin GL_TRIANGLES)
@ -187,16 +187,16 @@ function directly return @tt{GLdouble} vectors.}
)]{ )]{
These functions do not take vectors, instead they return a These functions do not take vectors, instead they return a
@scheme[selection-buffer-object] or @scheme[feedback-buffer-object]. @racket[selection-buffer-object] or @racket[feedback-buffer-object].
The @scheme[select-buffer->gl-uint-vector] and The @racket[select-buffer->gl-uint-vector] and
@scheme[feedback-buffer->gl-float-vector] functions copy the contents @racket[feedback-buffer->gl-float-vector] functions copy the contents
of the buffer into a vector. Because the OpenGL library writes to the of the buffer into a vector. Because the OpenGL library writes to the
buffer-object on OpenGL function calls after @tt{glSelectBuffer} or buffer-object on OpenGL function calls after @tt{glSelectBuffer} or
@tt{glFeedbackBuffer} has returned, if the buffer is garbage collected @tt{glFeedbackBuffer} has returned, if the buffer is garbage collected
before OpenGL is finished writing to it, the entire Scheme system can before OpenGL is finished writing to it, the entire Racket system can
crash. The @scheme[gl-process-selection] function in crash. The @racket[gl-process-selection] function in
@schememodname[sgl] helps interpret the results of @tt{glSelectBuffer} @racketmodname[sgl] helps interpret the results of @tt{glSelectBuffer}
in a Scheme-friendly format.} in a Racket-friendly format.}
@def-C-gl[( @def-C-gl[(
glAccum glAccum
@ -1633,9 +1633,9 @@ All OpenGL-defined constants.}
@defproc[(feedback-buffer->gl-float-vector [buf feedback-buffer-object?]) @defproc[(feedback-buffer->gl-float-vector [buf feedback-buffer-object?])
gl-float-vector?]{ gl-float-vector?]{
Converts a result from @scheme[glFeedbackBuffer] to a vector.} Converts a result from @racket[glFeedbackBuffer] to a vector.}
@defproc[(select-buffer->gl-uint-vector [buf select-buffer-object?]) @defproc[(select-buffer->gl-uint-vector [buf select-buffer-object?])
gl-uint-vector?]{ gl-uint-vector?]{
Converts a result from @scheme[glSelectBuffer] to a vector.} Converts a result from @racket[glSelectBuffer] to a vector.}

View File

@ -1,42 +1,42 @@
#lang scribble/doc #lang scribble/doc
@(require "common.ss" @(require "common.ss"
scribble/eval scribble/eval
(for-syntax scheme/base)) (for-syntax racket/base))
@title[#:tag "main"]{Scheme-Style OpenGL} @title[#:tag "main"]{Racket-Style OpenGL}
@defmodule[sgl] @defmodule[sgl]
The functions in @schememodname[sgl] use Scheme style names instead of The functions in @racketmodname[sgl] use Racket style names instead of
C style names. To convert a C OpenGL name to a Scheme OpenGL name, C style names. To convert a C OpenGL name to a Racket OpenGL name,
change the @tt{gl} prefix to @schemeidfont{gl-}, separate adjacent change the @tt{gl} prefix to @racketidfont{gl-}, separate adjacent
words with hyphens, and convert to all lower case. Functions that words with hyphens, and convert to all lower case. Functions that
have several variants to accommodate different numbers and types of have several variants to accommodate different numbers and types of
arguments are collapsed into one or two functions in arguments are collapsed into one or two functions in
@schememodname[sgl]. For example, @schememodname[sgl] provides two @racketmodname[sgl]. For example, @racketmodname[sgl] provides two
vertex functions: @scheme[vertex] and @scheme[vertex-v]. The vertex functions: @racket[vertex] and @racket[vertex-v]. The
@scheme[vertex] function accepts 2, 3 or 4 numerical arguments, and @racket[vertex] function accepts 2, 3 or 4 numerical arguments, and
the @scheme[vertex-v] function accepts @scheme[gl-vector]s of length the @racket[vertex-v] function accepts @racket[gl-vector]s of length
2, 3 or 4. The C language OpenGL interface, in contrast, has 24 2, 3 or 4. The C language OpenGL interface, in contrast, has 24
vertex functions: @tt{glVertex3i}, @tt{glVertex4fv}, etc. vertex functions: @tt{glVertex3i}, @tt{glVertex4fv}, etc.
Functions in @schememodname[sgl] take symbols instead of integers for Functions in @racketmodname[sgl] take symbols instead of integers for
@tt{GLenum} arguments. Each function checks that the given symbol is @tt{GLenum} arguments. Each function checks that the given symbol is
an acceptable argument and raises an exception if it is not. Given an acceptable argument and raises an exception if it is not. Given
the name of a C-language @tt{#define} constant, determine the the name of a C-language @tt{#define} constant, determine the
corresponding symbolic argument by removing the leading @tt{GL_}, corresponding symbolic argument by removing the leading @tt{GL_},
converting the letters to lower-case and replacing each @tt{_} with converting the letters to lower-case and replacing each @tt{_} with
@schemeidfont{-}. For example, @tt{GL_TRIANGLES} becomes @racketidfont{-}. For example, @tt{GL_TRIANGLES} becomes
@scheme['triangles], and @tt{GL_TRIANGLE_STRIP} becomes @racket['triangles], and @tt{GL_TRIANGLE_STRIP} becomes
@scheme['triangle-strip]. Additionally, the functions check the @racket['triangle-strip]. Additionally, the functions check the
length of any array arguments to ensure that OpenGL does not attempt length of any array arguments to ensure that OpenGL does not attempt
to write or read after the array. to write or read after the array.
The @schememodname[sgl] module is not as complete as the The @racketmodname[sgl] module is not as complete as the
@schememodname[sgl/gl] module. @racketmodname[sgl/gl] module.
@as-examples[ @as-examples[
@schemeblock[ @racketblock[
(require sgl sgl/gl-vectors) (require sgl sgl/gl-vectors)
(gl-begin 'triangles) (gl-begin 'triangles)
(gl-vertex 1 2 3) (gl-vertex 1 2 3)
@ -48,12 +48,12 @@ The @schememodname[sgl] module is not as complete as the
Represents a selection.} Represents a selection.}
@(define-syntax-rule (def-scheme-gl (id ...) body ...) @(define-syntax-rule (def-racket-gl (id ...) body ...)
@deftogether[( @deftogether[(
@defthing[id procedure?] ... @defthing[id procedure?] ...
) body ...]) ) body ...])
@def-scheme-gl[( @def-racket-gl[(
gl-accum gl-accum
gl-active-texture gl-active-texture
gl-alpha-func gl-alpha-func
@ -192,25 +192,25 @@ gl-window-pos
gl-window-pos-v gl-window-pos-v
)]{ )]{
Scheme-style variants of the OpenGL functions.} Racket-style variants of the OpenGL functions.}
@defproc[(gl-process-selection [vec gl-uint-vector?] @defproc[(gl-process-selection [vec gl-uint-vector?]
[hits exact-nonnegative-integer?]) [hits exact-nonnegative-integer?])
(listof gl-selection-record?)]{ (listof gl-selection-record?)]{
Parses the contents of @scheme[vec] from the format used by Parses the contents of @racket[vec] from the format used by
@scheme[glSelectBuffer]. The second argument should be the number of @racket[glSelectBuffer]. The second argument should be the number of
hits as returned by @scheme[glRenderMode].} hits as returned by @racket[glRenderMode].}
@defproc[(gl-get-gl-version-number) exact-nonnegative-integer?]{ @defproc[(gl-get-gl-version-number) exact-nonnegative-integer?]{
Returns the run-time OpenGL version number as an integer: @scheme[10], Returns the run-time OpenGL version number as an integer: @racket[10],
@scheme[11], @scheme[12], @scheme[13], @scheme[14], @scheme[15], or @racket[11], @racket[12], @racket[13], @racket[14], @racket[15], or
@scheme[20].} @racket[20].}
@defproc[(gl-get-glu-version-number) exact-nonnegative-integer?]{ @defproc[(gl-get-glu-version-number) exact-nonnegative-integer?]{
Returns the run-time GLU version number as an integer: @scheme[10], Returns the run-time GLU version number as an integer: @racket[10],
@scheme[11], @scheme[12], or @scheme[13].} @racket[11], @racket[12], or @racket[13].}

View File

@ -3,29 +3,29 @@
@title[#:tag "overview"]{Using OpenGL} @title[#:tag "overview"]{Using OpenGL}
The @schememodname[sgl/gl] library provides direct access to the The @racketmodname[sgl/gl] library provides direct access to the
C-style OpenGL API, whereas the @schememodname[sgl] library provides a C-style OpenGL API, whereas the @racketmodname[sgl] library provides a
more Scheme-like interface. The @schememodname[sgl/gl] library more Racket-like interface. The @racketmodname[sgl/gl] library
provides a binding for each @tt{#defined} constant and for most provides a binding for each @tt{#defined} constant and for most
functions in OpenGL 1.5 and GLU 1.3. The functions perform comparable functions in OpenGL 1.5 and GLU 1.3. The functions perform comparable
checking to their C-language counterparts; they check the types of checking to their C-language counterparts; they check the types of
their arguments, but do not check the length of array arguments. The their arguments, but do not check the length of array arguments. The
@schememodname[sgl] library provides wrappers around many of the @racketmodname[sgl] library provides wrappers around many of the
functions in the @schememodname[sgl/gl] library to present a more functions in the @racketmodname[sgl/gl] library to present a more
Scheme-friendly interface, including function names that follow Scheme Racket-friendly interface, including function names that follow Racket
conventions, and checked, symbolic enumeration arguments, and conventions, and checked, symbolic enumeration arguments, and
array-length checks. array-length checks.
@bold{Warning on Safety:} OpenGL programming is inherently unsafe, @bold{Warning on Safety:} OpenGL programming is inherently unsafe,
even when using only the @schememodname[sgl] library. Although even when using only the @racketmodname[sgl] library. Although
@schememodname[sgl] checks the arguments to each function call, @racketmodname[sgl] checks the arguments to each function call,
violation of higher-level assumptions of the system's OpenGL library violation of higher-level assumptions of the system's OpenGL library
can cause it to crash, bringing the entire Scheme system down. For can cause it to crash, bringing the entire Racket system down. For
example, sending a large number of vertices in a single @tt{glBegin} example, sending a large number of vertices in a single @tt{glBegin}
causes at least some GL implementations to crash. causes at least some GL implementations to crash.
Some examples are available in the @filepath{examples} directory of Some examples are available in the @filepath{examples} directory of
the @filepath{sgl} collection in the PLT Scheme installation. For the @filepath{sgl} collection in the Racket installation. For
@filepath{alpha.ss}, try choosing the @filepath{sk.jpg} image distritbuted @filepath{alpha.ss}, try choosing the @filepath{sk.jpg} image distritbuted
with PLT Scheme in the @filepath{icons} collection; you may have to with Racket in the @filepath{icons} collection; you may have to
press the ``t'' key a few times if the spinning cube is blank. press the ``t'' key a few times if the spinning cube is blank.

View File

@ -9,7 +9,7 @@ The @schememodname[sgl] libraries provide access to the rendering
functions of @as-index{OpenGL} 1.5 and @as-index{GLU} 1.3 functions of @as-index{OpenGL} 1.5 and @as-index{GLU} 1.3
libraries. The @schememodname[sgl] libraries to not address libraries. The @schememodname[sgl] libraries to not address
system-level concerns, such as the attachment of GL rendering contexts system-level concerns, such as the attachment of GL rendering contexts
to displays. Instead, the libraries should work with any PLT Scheme to displays. Instead, the libraries should work with any Racket
extension that provides GL with access to the system (such as a extension that provides GL with access to the system (such as a
binding for @tt{glx}). Notably, the @schememodname[scheme/gui/base] binding for @tt{glx}). Notably, the @schememodname[scheme/gui/base]
library provides support for rendering contexts via the library provides support for rendering contexts via the