458 lines
16 KiB
Plaintext
458 lines
16 KiB
Plaintext
|
|
The _browser.ss_ library in the "browser" collection provides the
|
|
following procedures and classes for parsing and viewing _HTML_ files.
|
|
The "htmltext.ss" library (described further below) provides a
|
|
simplified interface for rendering to a subclass of the MrEd text%
|
|
class. The "external.ss" library (described even further below)
|
|
provides utilities for launching an external browser (such as
|
|
Mozilla).
|
|
|
|
The browser (and htmltext) supports basic HTML commands, plus special
|
|
Scheme hyperlinks of the form <A MZSCHEME=sexpr>...</A>. When the user
|
|
clicks on such a link, the string `sexpr' is parsed as a Scheme
|
|
program and evaluated. Since `sexpr' is likely to contain Scheme
|
|
strings, and since escape characters are difficult for people to read,
|
|
a vertical bar (|) character in sexpr is converted to a double-quote
|
|
(") character before it is parsed. Thus,
|
|
|
|
<A MZSCHEME="|This goes nowhere.|">Nowhere</A>
|
|
|
|
creates a "Nowhere" hyperlink, which executes the Scheme program
|
|
|
|
"This goes nowhere."
|
|
|
|
The value of that program is a string. When a Scheme hyperlink returns
|
|
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
|
|
nowhere."
|
|
|
|
The browser also treats comment forms containing MZSCHEME=sexpr
|
|
specially. Whereas the <A MZSCHEME=sexpr>...</A> form executes the
|
|
expression when the user clicks, the MZSCHEME expression in a comment
|
|
is executed immediately during HTML rendering. If the result is a
|
|
string, the comment is replaced in the input HTML stream with the
|
|
content of the string. Thus,
|
|
|
|
<!-- MZSCHEME="(format |<B>Here</B>: ~a| (current-directory))" -->
|
|
|
|
inserts the path of the current working directory into the containing
|
|
document (and "Here" is boldfaced). If the result is a snip instead of
|
|
a string, it replaces the comment in the document. Other types of
|
|
return values are ignored.
|
|
|
|
If the html file is being accessed as a "file:" url, the
|
|
current-load-relative-directory parameter is set to the directory
|
|
during the evaluation of the mzscheme code (in both examples). The
|
|
Scheme code is executed through `eval'.
|
|
|
|
The MZSCHEME forms are disabled unless the web page is a
|
|
file: url that points into the `doc' collection.
|
|
|
|
----------------------------------------
|
|
|
|
> (open-url url) - Opens the given url
|
|
(either a string, url record, or port)
|
|
in a vanilla browser frame and returns
|
|
the frame. The frame is an instance of
|
|
hyper-frame%.
|
|
|
|
-----------------------------------------
|
|
|
|
The html-img-ok parameter controls image rendering for the browser.
|
|
|
|
> (html-img-ok on?) - Sets the value of the parameter to on?
|
|
> (html-img-ok) - Returns the current value of the parameter
|
|
|
|
The html-eval-ok parameter controls the evaluation of
|
|
`MZSCHEME=' tags. If the parameter is #f, they are disabled.
|
|
|
|
> (html-eval-ok on?) - Sets the value of the parameter to on?
|
|
> (html-eval-ok) - Returns the current value of the parameter
|
|
|
|
|
|
------------------------------------------------------------
|
|
|
|
> (hyper-frame-mixin frame%) - Extends the given frame% class.
|
|
|
|
The result of this mixin takes one argument, a url
|
|
string. During the initialization of objects created from
|
|
this mixin, the code shows the frame and visits the url.
|
|
|
|
> get-hyper-panel% :: (send hyper-frame get-hyper-panel%)
|
|
returns the class that is instantiated with the frame is created.
|
|
Must be a panel with hyper-panel-mixin mixed in. Defaults to
|
|
just returning hyper-panel%.
|
|
|
|
> get-hyper-panel :: (send hyper-frame get-hyper-panel) - returns the hyper panel
|
|
in this frame
|
|
|
|
----------------------------------------
|
|
|
|
> hyper-frame% = (hyper-frame-mixin frame%)
|
|
|
|
------------------------------------------------------------
|
|
|
|
> (hyper-no-show-frame-mixin frame%) - Extends the given frame% class.
|
|
|
|
This is the same as the hyper-frame-mixin, except that it
|
|
doesn't show the frame and the initialization arguments
|
|
are unchanged.
|
|
|
|
----------------------------------------
|
|
|
|
> hyper-no-show-frame% = (hyper-frame-no-show-mixin frame%)
|
|
|
|
----------------------------------------
|
|
|
|
> (hyper-text-mixin text%) - Extends the given text%
|
|
class. The initialization arguments are extended with a
|
|
four new first arguments: a url or a port to be loaded
|
|
into the text% object (using the `reload' method,
|
|
described below), a top-level-window or #f to use as a
|
|
parent for status dialogs, a progress procedure used as
|
|
for `get-url', and either #f or a post string to be sent
|
|
to a web server (technically changing the GET to a POST).
|
|
|
|
Sets the autowrap-bitmap to #f.
|
|
|
|
An instance of a (hyper-text-mixin text%) class should be displayed
|
|
only in an instance of a class created with `hyper-canvas-mixin'
|
|
(described below).
|
|
|
|
The mixin adds the following methods:
|
|
|
|
> map-shift-style :: (send o map-shift-style start end shift-style)
|
|
Maps the given style over the given range
|
|
|
|
> make-link-style :: (send o make-link-style start end)
|
|
Changes the style for the given range to the link style
|
|
|
|
> get-url :: (send o get-url)
|
|
Returns the URL displayed by the editor, or #f if there
|
|
is none.
|
|
|
|
> get-title :: (send o get-title)
|
|
> set-title :: (send o set-title string)
|
|
Gets or sets the page's title
|
|
|
|
> hyper-delta
|
|
A style-delta% object; override it to set the link style
|
|
|
|
> add-tag ::(send o add-tag name-string pos)
|
|
Installs a tag.
|
|
|
|
> find-tag :: (send o find-tag name-string/number)
|
|
Finds the location of a tag in the buffer (where tags are
|
|
installed in HTML with <A NAME="name">) and returns its
|
|
position. If `name' is a number, the number is returned (assumed
|
|
to be an offset rather than a tag). Otherwise, if the tag is not
|
|
found, #f is returned.
|
|
|
|
> remove-tag :: (send o remove-tag name)
|
|
Removes a tag.
|
|
|
|
> post-url :: (send o post-url string[url] post-data-bytes)
|
|
Follows the link in the string. post-data-bytes defaults to #f
|
|
|
|
> add-link :: (send o add-link start end url-string)
|
|
Installs a hyperlink.
|
|
|
|
> add-scheme-callback :: (send o add-scheme-callback start end scheme-string)
|
|
Installs a Scheme evaluation hyperlink.
|
|
|
|
> add-scheme-callback :: (send o add-thunk-callback start end thunk)
|
|
Installs a thunk-based hyperlink.
|
|
|
|
> eval-scheme-string :: (send o eval-scheme-string string)
|
|
Called to handle the <A MZSCHEME="expr">...</A> tag and <!
|
|
MZSCHEME="expr"> comments (see above). Evaluates the string; if
|
|
the result is a string, it is opened as an HTML page.
|
|
|
|
> reload :: (send o reload)
|
|
|
|
Reloads the current page.
|
|
|
|
The text defaultly uses the basic style named "Html
|
|
Standard" in the editor (if it exists).
|
|
|
|
> remap-url :: (send o remap-url url) -> url or string or #f
|
|
|
|
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 method returns #f, the page doesn't
|
|
go anywhere.
|
|
|
|
This method may be killed (if the user clicks the
|
|
``stop'' button)
|
|
|
|
----------------------------------------
|
|
|
|
> hyper-text% = (hyper-text-mixin text:keymap%)
|
|
|
|
This is an extension of the keymap class, to support standard key bindings
|
|
in the browser window. It adds the following method:
|
|
|
|
> get-hyper-keymap :: (send o get-hyper-keymap) -> keymap% object
|
|
Returns a keymap suitable for frame-level handling of events to
|
|
redirect page-up, etc. to the browser canvas.
|
|
|
|
----------------------------------------
|
|
|
|
> (hyper-canvas-mixin editor-canvas%) - Extends the given
|
|
editor-canvas% class. The initialization arguments are unchanged.
|
|
|
|
The canvas's parent should be an instance of a class derived with
|
|
`hyper-panel-mixin' (described below).
|
|
|
|
The mixin adds the following methods:
|
|
|
|
> get-editor% :: (send o get-editor%)
|
|
Returns the class used to implement the editor in the browser
|
|
window. It should be derived from hyper-text% and should pass on the
|
|
initialization arguments to hyper-text%
|
|
|
|
The dynamic extent of the initialization of this
|
|
editor is called on a thread that may be killed (via a
|
|
custodian shutdown)
|
|
|
|
In that case, the editor in the browser's
|
|
editor-canvas may not be an instance of this class.
|
|
|
|
> current-page :: (send o current-page)
|
|
Returns a representation of the currently displayed page, which
|
|
includes a particular editor and a visible range within the
|
|
editor.
|
|
|
|
> goto-url :: (send o goto-url url relative-to-url [progress-proc] [post-data-bytes #f])
|
|
Changes to the given url, loading it by calling the `make-editor'
|
|
method. If `relative-to-url' is not #f, it must be a URL for
|
|
resolving `url' as a relative URL. `url' may also be a port, in
|
|
which case, `relative-to-url' must be #f.
|
|
|
|
The `progress-proc' procedure is called with a boolean at the
|
|
point where the URL has been resolved and enough progress has
|
|
been made to dismiss any message that the URL is being
|
|
resolved. The procedure is called with #t if the URL will be
|
|
loaded into a browser window, #f otherwise (e.g., the user will
|
|
save the URL content to a file).
|
|
|
|
If `post-data-bytes' is a byte string instead of false, the URL
|
|
GET is changed to a POST with the given data.
|
|
|
|
> set-page :: (send o set-page page notify?)
|
|
Changes to the given page. If `notify?' is not #f, the canvas's
|
|
parent is notified about the change by calling its `leaving-page'
|
|
method.
|
|
|
|
> after-set-page :: (send o after-set-page)
|
|
Called during `set-page'. Defaultly does nothing.
|
|
|
|
----------------------------------------
|
|
|
|
> hyper-canvas% = (hyper-canvas-mixin editor-canvas%)
|
|
|
|
----------------------------------------
|
|
|
|
> (hyper-panel-mixin area-container%) - Extends the given area
|
|
container class. The initialization arguments are unchanged, but
|
|
initialization creates controls and a hyper text canvas. The
|
|
controls permit a user to move back and forth in the hypertext
|
|
history.
|
|
|
|
The mixin adds a initialization argument, info-line?, which is a
|
|
boolean indicating whether the browser should contain a line to
|
|
display special "DOCNOTE" tags in a page. Such tags are used
|
|
primarily by the PLT documentation.
|
|
|
|
The mixin adds the following instance variables:
|
|
|
|
> make-canvas :: (send o make-canvas container)
|
|
Creates the panel's hypertext canvas, an instance of a class
|
|
derived using `hyper-canvas-mixin' (described above). This
|
|
method is called during initialization.
|
|
|
|
> get-canvas% :: (send o get-canvas%)
|
|
Returns the class instantiated by make-canvas. It must be derived from
|
|
hyper-canvas%
|
|
|
|
|
|
> make-control-bar-panel :: (send o make-control-bar-panel container)
|
|
Creates the panel's sub-container for the control bar containing
|
|
the navigation buttons. If #f is returned, the panel will have no
|
|
control bar. The default method instantiates horizontal-panel%.
|
|
|
|
> rewind :: (send o rewind)
|
|
Goes back one page, if possible.
|
|
|
|
> forward :: (send o forward)
|
|
Goes forward one page, if possible.
|
|
|
|
> get-canvas :: (send o get-canvas)
|
|
Gets the hypertext canvas.
|
|
|
|
> on-navigate :: (send o on-navigate)
|
|
Callback that is invoked any time the displayed hypertext page
|
|
changes (either by clicking on a link in the canvas or by
|
|
`rewind' or `forward' calls).
|
|
|
|
> leaving-page :: (send o leaving-page page new-page)
|
|
This method is called by the hypertext canvas to notify the
|
|
panel that the hypertext page changed. The `page' is #f
|
|
if `new-page' is the first page for the canvas. See also
|
|
`page->editor' (described below).
|
|
|
|
> filter-notes :: (send o filter-notes list-of-strings)
|
|
Given the notes from a page as a list of strings (where
|
|
each string is a note), returns a single string to print
|
|
above the page.
|
|
|
|
> reload :: (send o reload)
|
|
|
|
Reloads the currently visible page by calling the reload method of
|
|
the currently displayed hyper-text.
|
|
----------------------------------------
|
|
|
|
> hyper-panel% = (hyper-panel-mixin vertical-panel%)
|
|
|
|
----------------------------------------
|
|
|
|
> (editor->page editor) - Creates a page record for the given editor,
|
|
suitable for use with the `set-page' method of hyper-canvas-mixin.
|
|
|
|
> (page->editor page) - Extracts the editor from a page record.
|
|
|
|
> (on-installer-run [proc]) - Parameter for a procedure to be invoked
|
|
after the installer is run on a .plt file
|
|
|
|
> (bullet-size [n]) - Parameter controlling the point size of a
|
|
bullet
|
|
|
|
-----------------------------------------
|
|
|
|
> image-map-snip% extends image-snip%
|
|
init: html-text : (is-a?/c html-text<%>)
|
|
|
|
Instances of this class behave like image-snip% objects,
|
|
except they have a <map> ... </map> associated with them and
|
|
when clicking on them (in the map) they will cause their
|
|
init arg text to follow the corresponding link.
|
|
|
|
> (send an-image-map-snip set-key key-string)
|
|
|
|
Sets the key for the image map (eg, "#key").
|
|
|
|
> (send an-image-map-snip get-key)
|
|
|
|
Returns the current key.
|
|
|
|
> (send an-image-map-snip add-area shape-string list-of-numbers href-string)
|
|
|
|
Registers the shape named by the shape-string whose
|
|
coordinates are specified by the list-of-numbers to go to
|
|
the href named href-string when that region of the image
|
|
is clicked on.
|
|
|
|
-----------------------------------------
|
|
|
|
The _browser-unit.ss_ library in the "browser" collection is a
|
|
unitized version of the code documented above. It imports unit
|
|
matching the following signatures:
|
|
|
|
setup:plt-installer^
|
|
mred^
|
|
net:tcp^ (see "tcp-sig.ss" in the "net" collection)
|
|
net:url^ (see "url-sig.ss" in the "url" collection)
|
|
|
|
It exports the browser^ signature.
|
|
|
|
-----------------------------------------
|
|
|
|
The _browser-sig.ss_ library in the "browser" collection defines
|
|
the browser^ signature with all of the names listed above.
|
|
|
|
|
|
========================================
|
|
_htmltext.ss_
|
|
========================================
|
|
|
|
> html-text<%>
|
|
|
|
An interface that extends text% with the following methods:
|
|
|
|
> get-url :: (send t get-url) --- returns a base URL used for building
|
|
relative URLs, or #f if no base is available
|
|
|
|
> set-title :: (send t set-title str) --- registers the title `str'
|
|
for the rendered page
|
|
|
|
> add-link :: (send t add-link start-pos end-pos url-string) ---
|
|
registers a hyperlink for the given region in rendered page
|
|
|
|
> add-tag :: (send t label pos) --- registers a tag at the given
|
|
position in the rendered page
|
|
|
|
> make-link-style :: (send t make-link-style start-pos end-pos) ---
|
|
modifies the style of the rendered page from start-pos to end-pos to
|
|
look like a hyperlink
|
|
|
|
> add-scheme-callback :: (send t add-scheme-callback pos endpos code-string)
|
|
--- registers a code-evaluating hyperlink for the given region
|
|
|
|
> add-thunk-callback :: (send t add-scheme-callback pos endpos thunk)
|
|
--- registers a thunk-invoking hyperlink for the given region
|
|
|
|
> post-url :: (send t post-url url post-data-bytes)
|
|
--- performs a post to the given `url' with the given post data
|
|
|
|
----------------------------------------
|
|
|
|
> (html-text-mixin text%-subclass) -> html-text<%> implementation
|
|
|
|
Extends the given text% class with implementations of the html-text<%>
|
|
methods. Hyperlinks are attached to clickbacks that use `send-url'
|
|
(from the "sendurl.ss" library of the "net" collection).
|
|
|
|
> (render-html-to-text input-port html-text<%>-obj load-img? eval-mz?)
|
|
|
|
Reads HTML from `input-port' and renders it to `html-text<%>-obj'. If
|
|
`load-img?' is false, then images are rendered as Xed-out boxes. If
|
|
`eval-mz?' is false, then MZSCHEME hyperlink expressions and comments
|
|
are not evaluated.
|
|
|
|
Uses the style named "Html Standard" in the editor's
|
|
style-list (if it exists) for all of the inserted text's
|
|
default style.
|
|
|
|
========================================
|
|
_external.ss_
|
|
========================================
|
|
|
|
> (send-url str [separate-window? #t])
|
|
Like 'send-url' in (lib "sendurl.ss" "net"), but under Unix,
|
|
the user is prompted for a browser to use if none is recorded
|
|
in the preferences file.
|
|
|
|
> (browser-preference? v)
|
|
Returns #t if v is a valid browser preference
|
|
|
|
> (update-browser-preference url-or-#f)
|
|
Under Unix, prompts the user for a browser preference and records
|
|
the user choice as a framework preference (even if one is already
|
|
recorded). If `url-or-#f' is not #f, it is used in the dialog to
|
|
explain which URL is to be opened; if it is #f, the 'internal will
|
|
be one of the options for the user.
|
|
|
|
> (install-help-browser-preference-panel)
|
|
Installs a framework preference panel for "Browser" options.
|
|
|
|
> (add-to-browser-prefs-panel proc)
|
|
The `proc' must be a procedure that takes a panel% argument. It
|
|
will be called when the "Browser" panel is constructed for
|
|
preferences. The supplied argument is the panel, so `proc' can add
|
|
additional option controls. If the panel is already created, `proc'
|
|
is called immediately.
|
|
|
|
> tool@
|
|
A unit that implements a DrScheme tool to add the "Browser"
|
|
preference panel.
|