Newt's Cape API

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)

in Notes

[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

in 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.

Names

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.

Paperback

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

Newt's Paper

tap on news: link
URL is passed to Newt's Paper
[in Newt's Paper, http: URL encountered]
Newt's Cape:getURL

Bookmark Managers

HyperNewt

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)

:openNewtlet(viewBounds,params)

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

Newt's Cape's Use by Other Applications

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.

Files (helper apps), e.g., text/html

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.

HTML tags (HTML apps), e.g., viewing tags

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.

options

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

:getURL(URL,options)

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 /* convert to a bitmap using user prefs (for gray, animation) */
		  GetRoot().|NewtsCape:NewtsCape|:convertImage(type, href, content, options, nil);
	return TRUE; /* this "handled" it */
	end},
InetStatus: nil,
noStatus: true,	
})

:fetchURL(URL,options)

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".

:installHTMLApp(appSymbol, htmlApp)

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.

:installHelperApp(contentType,appSymbol,helperApp)

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.

:dispatchFile(contentType, url, content, options)

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]
dispatchFile checks more generic MIME types (e.g., text/* or application/*) and */* after failing to match a specific MIME type; a pattern could be useful for helperApps to install when specific file extensions are required and when servers vary widely in which MIME types they return
url [string or nil]
content [string or binary]
options [frame or nil]

:GetNamedResource(src, names, values)

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]).

:GetPictAsBits(src)

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.

:GetSound(src)

returns a sound from a soup entry (typically created via Sloup)

src [string]
soupName/soundName
For example,
<META NAME="DATA.sound1" CONTENT=":GetSound(&quot;sounds/foo.snd&quot;)">
<META NAME="DATA.playsound1" CONTENT="func(x1,y1,href,item) PlaySound(sound1)">
...
<A HREF="playsound1">play the sound</A>

For More Info

This document (in all its formats) is © 1997-2007. Steve Weyer, Greg Simon. All Rights Reserved Worldwide

Version 2.1. Last updated: Dec 2000