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

access bookmark soups directly
Import/Export bookmarks from/to Newt's Cape
access http: URL via Newt's Cape

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.

dispatchFile
fetchURL
GetPictAsBits
GetSound
getURL
installHelperApp
installHTMLApp

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

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

Version 2.1. Last updated: Dec 2000