This document describes Newt's Cape's interface with other applications: both
how it makes use ofother applications,
and also how it can be used by other
applications via its API (application program interface).
Newt's Cape's Use of Other Applications
Generally, the situations described below are initiated in Newt's Cape.
Notes
in Newt's Cape
- File:Open Notes
- reads HTML source
- File:Save HTML/Image to Notes
- copies cached HTML/Image to Notes
- <LINK HREF="Notes/...>
- includes source in another document
- <FORM ACTION="Notes">
- writes form data to Notes
- Bookmarks:Save as Outline
- saves bookmarks (URLs and titles) to a Notes outline for access
(getURL) or editing/import (if HTMList installed)
- [text contains <HTML>...<TITLE>] Newt's Cape:Open
- reads HTML source
- [http:/mailto:/news: URL highlighted] Newt's Cape:getURL
- gets HTML document from cache or net
- [2.x. other text selected] Newt's Cape:Find
- performs query (see Find.Title etc.
- [in outline or checklist stationery, HTMList installed] Export to HTML
- generates HTML source in separate note (to be viewed via Newt's Cape:Open)
- [in outline or checklist stationery, HTMList installed; items contain URLs] Newt's Cape:Add Bookmarks
- adds bookmarks to Newt's Cape
NewtWorks
in Newt's Cape
- File:Open NewtWorks
- reads HTML source
- File:Save HTML/Image to NewtWorks
- copies cached HTML/Image to NewtWorks
- [text contains <HTML>...<TITLE>] Tools:Newt's Cape
- reads HTML source
- [http:/mailto:/news: URL highlighted] Tools:Newt's Cape
- gets HTML document from cache or net
- [other text selected] Tools:Newt's Cape
- performs query (see Find.Title etc.
Similar to Notepad and NewtWorks,
process a URL (:getURL) that is in a custom "URL" field,
or in the Notes field of Names (it ignores any <!-- HTML comments --> in Notes),
or process a short HTML source document (:Open) in Notes field.
- File:Open Paperback
- reads HTML source
Note: File:Open WabumiUni (a Paperback-like application) is available in the Japanese version.
Inbox/Outbox
- File:Open Inbox
- reads HTML source from email or beamed entries
- tap on mailto: link
- msg goes into Outbox using default mail transport
- tap on http: link (if no NIE)
- msg to "WebMail proxy" goes into Outbox using default mail transport
- tap on news: link
- URL is passed to Newt's Paper
- [in Newt's Paper, http: URL encountered]
- Newt's Cape:getURL
- access bookmark soups directly
- Import/Export bookmarks from/to Newt's Cape
- access http: URL via Newt's Cape
- in a book's action button, select HyperLink
- saves a link/bookmark to the current document (URL, isbn and page number)
- in HyperNewt, select a Newt's Cape link
- opens book (package) or HTML source (cache or web)
Normally, a newtlet's (a Newton
application APPLET) viewBounds and
other parameters (via PARAM)
are set directly before Newt's Cape calls :open(). If you don't like the
idea of another application messing around with your viewBounds and other
slots, your newtlet can provide an openNewtlet method which initializes
itself based on the following parameters:
- viewBounds [frame]
- viewBounds in relative coordinates for the book page
- params [frame]
- PARAM slots and values
Other applications can call the following methods in Newt's Cape's API.
getURL and fetchURL
are similar to a proposed standard
by Flash Sheridan but implement different options.
The details below will change from user and developer feedback.
Needs work in area of error feedback. There are numerous examples -- see the
regular Examples page.
The helpurl example (NTK and
NewtDevEnv formats) provides
- protoAboutText
- recognizes and reformats <A HREF="mailto:/http:..."> references
and uses :getURL
- dynamic help books
- using :dispatchFile on HTML help source
Extending Protocols, Files, HTML
You can extend/modify how Newt's Cape processes URLs and files in several ways.
Protocols (NIE apps), e.g., http:
When Newt's Cape processes a URL, it checks with
urlCop whether an application is
registered for that type. To include support for ftp:, mailto: or other internet
protocols, just make sure that your application registers with urlCop. By default,
Newt's Cape registers for http, but dispatches on http:,
mailto: and news: URLs even if urlCop
is not installed.
Newt's Cape completes the transfer of a text or binary file via http:
if a "helperApp" is
registered with Newt's Cape for that media/MIME type, e.g., text/plain (and
possibly for specific file extensions for that type). The helperApp receives
the entire file. By default, Newt's Cape handles http types: text/html,
image/gif, x-newton-compatible-pkg, and text/plain. It also handles image/jpeg
if JPEG plugin is installed.
You can install a helperApp so that it is
always available; or specify it as an option for
:getURL.
While parsing an HTML document, Newt's Cape passes the results to the
current "htmlApp". The htmlApp receives a parsed representation of the file
(not raw HTML), and implements a subset of tags, for example, to display
the information via a "browser" or add data to a soup or other application.
By default, Newt's Cape displays HTML as a Newton book or saves it directly as a package.
You can install an htmlApp so that it is
available to the user in the Process picker menu; or specify it as an
option for :getURL.
Several methods (dispatchFile, fetchURL, getURL)
use an options frame. Values will default to user preferences/settings where applicable
(these have links below).
It can currently contain the following slots (these
might change, and there are more than documented here;
please let us know if you start to rely on them or would like more info):
- agentPrefix [string]
- string to prefix to User-Agent request field
- agentSizeRes [string or nil]
- this might be used by a proxy server that automatically converted graphics, for example.
if non-empty string, supply header fields:
- UA-color
- with value (based on bitsPerPixel preference): mono1,mono4, mono16
- UA-pixels
- with value (based on page size, and rotation for full):
206x216 (help), 240x320 (portrait), 320x240 (landscape), currentScreenWidth&Height (full)
- autoLogin [boolean]
- automatically connect (i.e., dial) without prompting user to confirm setup.
this might be used by an agent that automatically checked/downloaded web pages.
- base [string]
- url. normally set automatically when invoked via :getURL or with source frame
- bitsPerPixel [integer]
- 1 = B&W, 2 = 4-gray;, 4 = 16-gray
- body [string]
- for mailto:, email text message. default: "I saw this cool document in Newt's Cape"
- cacheHTML [string]
- a soupName to store an HTML document.
(default: HTMLCache:NewtsCape unless "no cache").
- cacheImages [string]
- a soupName to store a bitmap object or raw GIF (rawImage).
(default: ImageCache:NewtsCape unless "no cache").
- cacheOnly [boolean]
- store but do not display text or images. (same as processOption=4).
note: to prevent GIFs from being converted, use rawImage
- cookies [array]
- (to be described later)
- cookiesConfirm [symbol]
- 'skip, 'ask, 'keep
- data [frame]
- frame of data to be URLencoded and sent (method: GET/POST) to server.
default print order is undefined, and
internal print names of slots are used as fields unless a dataNames array is supplied.
- dataNames [array]
- optional array of strings to define field order and exact print names
(case may differ from internal slot printname)
- docDoneSound [symbol]
- nil for no sound. or symbol in ROM_soundoff (simpleBeep, wakeupBeep, plinkBeep, funBeep)
- extraHeader [frame]
- additional header fields: names(slot symbols) and values(strings) for an http request, e.g.,
{|X-Foo|: "37", Bar: "x"}, would add:
X-Foo: 37
Bar: x
- helperApp [frame, symbol or nil] (required for fetchURL)
- nil
- defaults to Newt's Cape
- symbol
- refers to an installed application (helperApp) that implements addFile.
- frame
- htmlApp [frame or nil]
- nil
- defaults to Newt's Cape.
- frame
- httpNoProxy [string]
- provide exceptions to current proxy.
- httpProxy [string]
- specify a proxy for this URL.
- icon [bitmap]
- default: Newt's Cape. small icon to use in for NIE status box
- InetStatus [boolean]
- default: true. display NIE messages (status of connection, transfer)
- loadImages [boolean]
- default: nil. if true, loads any images, then re-processes main document
- method [string: "GET","POST", "HEAD", "PUT"?]
- mailto:
- posts message
- http: GET
- URLencoded data is appended to URL
- http: POST
- data is posted to server as a separate text document
see data, dataNames, :getURL.
- name [string]
- for mailto:, email addressee name, e.g., "first last". default: name
of existing person in Names (matching email address) or highlighted text.
- noDelay [boolean]
- default: nil. if true, no pausing (normally, Newt's Cape pauses after each line
while parsing a complete string
(Note, cached file), e.g., for user events and status updating).
- noStatus [boolean]
- default: nil.
if true (and Newt's Cape is not already open), no status info is displayed
during processing (this is separate for now from InetStatus)
- noStop [boolean]
- default NIL. if true, do not terminate processing when encountering
end of string (useful for merging multiple sources into one document). </HTML>
still terminates.
- pageHeight [integer]
- book page height in pixels.
Newt's Cape checks that it's an integer, but otherwise does no bounds checking.
additional book bar buttons may not appear in correct locations. (see pageWidth)
generally, you'd use pageSize rather than create a custom page size.
- pageSize [symbol]
- 'help, 'portrait, 'landscape, 'full
- pageWidth [integer]
- book page width in pixels. (see pageHeight)
- processOption [integer]
- corresponds to initial 5 Process picker values:
0=Display Item, 1=Display Page, 2=Display Page1, 3=Display All, 4=Cache Only (2.x), 5=Save Package (NewtPack).
default: previous picker value or Display Page. for other options, use htmlApp
- rawImage [boolean]
- if true, keep original GIF (or other type) images rather than convert into Newton format.
generally you probably do not want to use this since the raw data is cached
and must be converted each time it is used. it may be useful for
experimenting with different numbers of grays, or threshold level.
- removeComments [boolean]
- if true, removes <!-- comment strings from source before caching or parsing -->
- standAlone [boolean]
- if true (and NewtPack is installed), book includes additional ~25K of code/objects
for overview and back buttons, and simple navigation so that Newt's Cape is not required.
(alternatively, leave off and supply Newt's Cape Lite).
- start [integer]
- string index. default: location of <HTML>
- subject [string]
- for mailto:, email Subject:. (default: TITLE of current document?)
- threshold [integer]
- default: 128. number between 1-254
- trustHTML [boolean]
- default: true (whether to "trust the cache", i.e., query server about recency
of each cached entry)
- trustImages [boolean]
- default: true
Retrieves and processes a document for a http: URL from cache or from the internet.
it immediately returns.
- URL [string]
- url string or array (if array, processes first; queues rest)
- "any type"
- if an application is registered for a protocol with urlCop,
:getURL is re-sent. if not...
- http (HTML)
- default: Newt's Cape parses and displays document.
see installHTMLApp for alternate processing of HTML tags and values.
if options contains data and method, this URLencodes data and submits to the server.
- http (other MIME types)
- default: Newt's Cape displays GIFs, JPEGs and plain text, and installs packages.
see installHelperApp for alternate processing of files.
- mailto:
- posts message to Outbox using current mail transport.
if options contains data and method (and subject), this URLencodes data
in an email message (handy for local testing).
- news:
- invokes Newt's Paper (if installed)
- options [frame or nil]
Here's an example of invoking Newt's Cape "invisibly" for a URL, rechecking that document
is current (and not retrieving otherwise), not displaying any NIE or Newt's Cape status,
caching the HTML document, or converting and caching the GIF image:
GetRoot().|NewtsCape:NewtsCape|:getURL(
"http://www.....",
{cacheHTML: "HTMLCache:NewtsCape",
cacheImages: "ImageCache:NewtsCape",
trustHTML: nil,
trustImages: nil,
cacheOnly: true,
helperApp: {
addFile: func(type, href, content, options)
begin
/* your chance to do something (extract URLs, etc.)
type = MIME type (string)
href = URL (string)
content = string or VBO
options = the options frame
*/
Print(type); Print(href); Print(content);
if StrEqual(type, "image/gif") and not isFrame(content)
then begin /* convert to a bitmap using user prefs (for gray, animation) */
GetRoot().|NewtsCape:NewtsCape|:convertImage(type, href, content, options, nil);
end;
return TRUE; /* this "handled" it */
end},
InetStatus: nil,
noStatus: true,
})
Retrieves a document for a http: URL and return the file.
Since (like :getURL) this returns immediately,
the source is passed to your application asynchronously via a callback,
assuming that you have specified a helperApp option.
- URL [string]
- options [frame]
- be sure to specify helperApp
For example,
GetRoot().|Newtscape:Newtscape|:fetchURL("http://xyz.com/foo.htm",
{helperApp: {
addFile: func(contentType,URL,content,options)
begin Print(content); TRUE; end,
},
})
Note: there is no difference between :getURL and :fetchURL --
fetchURL is provided solely for compatibility
with the urlCop specification, and possibly as a reminder that
source is being "returned".
- appSymbol [symbol]
- unique identifier for this application/viewer
- htmlApp [frame or nil]
- nil
- de-install htmlApp for appSymbol
- frame
- installs htmlApp as a viewer/browser -- this is accessible by user
from the Process menu until next reboot (or de-install).
- item [string] (required for installed version)
- name to appear in Process picker
- addHTMLitem(tag,status) [method] (optional)
- default definition: (supplied by Newt's Cape):
addHTMLitem: func(tag,status)
begin
/* Write("tag: "); Print(tag._tag);
Write("val: "); Print(tag._value);
Print(status); */
/* dispatch on any tags that are defined */
local tag1 := tag._tag;
if HasVariable(self,tag1)
then Perform(self,tag1,tag);
end
- tag [frame]
- _tag
- [symbol] is first element
- _value
- [boolean, string or array] the value, depending on the type of tag
- true
- tag starting
- array
- entire tag with value as alternating "style" tag[array],value[string]
- string
- entire tag with value as string
- nil
- tag ending
- (other attributes)
- string
- status [frame]
- currently, the only interesting/documented slot is bytesSoFar [int],
which indicates current parser location. this could be used to display progress.
- tag methods
- implement a method for each tag you want to process, e.g., HTML: func(tag)...
- other slots,methods
- provide any other internal slots,methods to share code and update state.
Newt's Cape uses htmlApp as a _proto to support run-time modifications
To make persistent, create an autopart plugin with NewtDevEnv or NTK
(use a delayed action in your InstallScript, or contact us about how to
register more directly without installHTMLApp).
Example: htmlappi.htm.
To provide programmatically, e.g., via :getURL,
supply htmlApp option.
- contentType [string]
- the http media/MIME type, e.g., text/plain
- appSymbol [symbol]
- identifier for this application (unique for this contentType)
- helperApp [frame or nil]
- nil
- de-install (unregister) contentType, appSymbol
- frame
- install helperApp as a helper app for this content type
(and optionally, specific file extensions);
helperApp persists until next reboot (or de-install).
- extensions [array] (optional)
- if slot is specified and array is non-empty, process only those files
with matching file extensions, e.g., .txt.
- addFile(contentType,URL,content,options) [method] (required*)
- contentType [string]
- URL [string or nil]
- the filename
- content [string or binary object]
- text/data/"file"
- options [frame or nil]
- process the content "file".
return NIL if file not processed (Newt's Cape will try another helperApp);
otherwise, return true (non-nil)
*Note: if GetRoot().(appSymbol) is an application that defines addFile directly,
the helperApp frame can omit addFile, and even be empty {} if there are no extensions.
To make persistent, create an autopart plugin with NewtDevEnv or NTK
(use a delayed action in your InstallScript, or contact us about how to
register more directly without installHelperApp).
Example: helpappi.htm.
To provide programmatically, e.g., via :getURL,
supply helperApp option.
This is a generic dispatch method for helperApp. Generally, your application
would use :getURL as the main API. However, dispatchFile should be useful
for initial testing (to skip installHelperApp and actual http file transfer
steps) and also to replace parseHTML.
- contentType [string]
- url [string or nil]
- content [string or binary]
- options [frame or nil]
provides more flexibility than GetPictAsBits or GetSound for soup-based URLs.
- src [string]
- soupName/resourceName
- names [array]
- array of name slots
- values [array]
- array of value slots
For example,
:GetPictAsBits(src) is equivalent to :GetNamedResource(src, '[name, title], '[bitmap, icon]);
:GetSound(src) is equivalent to :GetNamedResource(src, '[name], '[sound]).
returns a graphic (for URL, a converted GIF or JPEG; for soup entry, bitmap or PICT)
- src [string]
- a reference for a graphic, in one of several formats:
- URL
- absolute (or relative to current book) url for a graphic (in cache)
- soupName/graphicName
- graphic from a soup entry (from bitmap or icon slot), whose
indexed name (a symbol or string) matches graphicName. typically created via Sloup.
returns a sound from a soup entry (typically created via Sloup)
- src [string]
- soupName/soundName
For example,
<META NAME="DATA.sound1" CONTENT=":GetSound("sounds/foo.snd")">
<META NAME="DATA.playsound1" CONTENT="func(x1,y1,href,item) PlaySound(sound1)">
...
<A HREF="playsound1">play the sound</A>
This document (in all its formats) is © 1997-99.
Steve Weyer, Greg Simon. All Rights Reserved Worldwide
Version 2.0. Last updated: Feb 1999
Steve Weyer - weyer@kagi.com
Greg Simon - greg@accesscom.com