Book
Scripting
Variables | Commands
| Example Scripts
Scripting HELP Read can easily transform it
from a simple reading utility into a publishing tool.
For instance, an electronic text may be distributed
with a simple BOK and a document dictionary containing phonetic misspellings of all works
contained in the etext which HELP Read doesn't, by default, pronounce correctly. A BOK
script can than launch HELP Read, tell it to open the etext and to check the document
dictionary first for custom pronunciations.
Actually, the etext and document dictionary don't even need to be
distributed. The BOK can retrieve them for you. And since BOK scripts are nothing more
than simple text files, their size is very small, generally less than 1K.
Note: at this time, in order for a BOK stored on the Internet to be
processed correctly, the file must be stored on the PixiNet server. Just attach the file to an email and we'll upload it for
you. Otherwise, browsers will consider the file to be text and display rather than execute
it. Your other option would be to contact your Internet Access Provider and ask them to
change the Mime type for files on their server with an extension of BOK from
"Text" to "Application/BOK".
Variables
Ten untyped variables are at your disposal,
named, not so creatively, @0 through @9. The variables are created by HELP Read and you
don't have to declare or dispose of them. The @ identifies the following number as a
variable. When variables are used in a command, the contents of the variable are
substituted for its name. The command to put data into a variable is:
@# data
...where # is the number. For example, to store the word
"hello" in the first variable:
@0 hello
You could then relay the message to the user with the
following command:
message @0
Commands
DownloadFile
Retrieves a
file from the Internet, via HTTP or FTP protocols, and stores it in the HELP Read
directory. The filename cannot contain a drive or directory. You can specify whether the
downloaded file should never overwrite an existing file, whether the user should be asked,
or whether to automatically replace an existing file. If you omit this setting,
"neveroverwrite" is assumed.
Syntax:
downloadfile url filename [neveroverwrite, askoverwrite,
automatic]
Example:
downloadfile http://espnet.sportszone.com/index.html
espn.txt automatic
Open
Opens a given text or html file into HELP Read's
document window for reading. If the file doesn't exist, the command produces an error and
the script stops processing.
Syntax:
open filename
Example:
open espn.txt
LoadWebPage
Grabs the text from Microsoft Internet Explorer or
Netscape Navigator, if either is active, and begins reading.
Syntax:
loadwebpage
Query
Asks the user for some piece of information. If the
user presses the "Cancel" button on the query window, the script terminates.
Syntax:
query "title" "message" @var
Example:
query "Where do you want to go?" "Enter
URL" @0
This example would ask the user for a url and store it in a
variable. You could then use "downloadfile" to retrieve the file and
"open" to load the file for reading.
Message
Tell the user something.
Syntax:
message msgtext
Example:
Message This is a message
Button Commands
These commands simulate the user pressing one of the
toolbar buttons.
Syntax:
openbutton
clipboardbutton
readbutton
nextbutton
previousbutton
searchbutton
fontbutton
helpbutton
CreateUniqueWordList
Compiles and displays a unique list of words
contained in the current document. This is particularly useful in the preparation of
document dictionaries, since this way you only have to listen to each word once.
Syntax:
createuniquewordlist
Voice Commands
A "Voice" consists of a talking head
reading companion bitmap and three settings: volume, pitch, and speed. The value of these
settings can range from 1 to 12. The order of these commands is unimportant.
Syntax:
voicevolume value
voicepitch value
voicespeed value
loadcompanionbitmap filename
Sendkeys
Sends a maximum of 24 keystrokes to a
specified window.
Note: the window title, not program name, is specified.
Also, be careful, HELP is not responisble for any damage caused by an errant BOK script.
The window title is not context sensitive and can be
partial. For example, "word" could send keystrokes Microsoft Word or
WordPerfect. The keystrokes go to the first window that matches the window title.
If there is no matching window, the command generates an
error and the script terminates.
Control keystrokes are as follows:
@ - Alt
^ - CTRL
~ - Shift
Syntax:
sendkeys "windowtitle" "keystrokes"
Example:
sendkeys "Word" "^A^C"
This would cause any program containing "Word" in
the title to copy its contents to the clipboard.
SaveClipboard
Saves any current clipboard text to a text file in
the HELP Read directory.
Syntax:
saveclipboard filename
LoadFileList
Above the sponsor message on the HELP Read screen is
a recent file listbox. You may replace the contents of this box with a custom table of
contents, allowing the user one-click access to many of your etexts. Each entry in the
file list must contain a filename (the file must exist in the HELP Read directory) and may
optionally be preceded by a title, contained in double-quotes. For example:
"Huck Finn" hfinn.txt
Syntax:
loadfilelist filename
Example:
loadfilelist hfinn.txt
DocDict
Applies a document dictionary, which exceeds all
other phonetic dictionaries in importance and remains active so long as the BOK script is
active. Document dictionaries enable you to ensure that jargon and names specific to your
document are pronounced correctly.
Syntax:
docdict filename
SearchFor
Syntax:
searchfor searchtext
LineBreak
Some text files place a carriage return at the end
of each line and two carriage returns at the end of each paragraph. This format causes
reading problems because HELP Read will assume that each line is the end of a paragraph
and pause. This results in a very halting reading. If you tell HELP Read that the file
about to be loaded with the "Open" command is Line Break text, the program will
convert the document to standard text format before each page is loaded.
Syntax:
linebreak [true, false]
Example:
linebreak true
ReadAll
Causes the reading of the active document text until
the end-of-document is reached or the user cancels the reading.
Syntax:
readall
ReadSentence
Same as ReadAll, but stops after reading one
sentence.
Syntax:
readsentence
Define
There are currently two events to which BOK commands
may be applied: "Main" and "LoadPage". The Define Main command is
assumed at the begining of each file and may be omitted. Commands in the Main event is
encountered each time the BOK is loaded. Commands following "Define LoadPage"
would be executed each time
Syntax:
define [main, loadpage]
Example:
define main (this line may be ommitted)
open espnet.txt
define loadpage
replace "era" "earned run average"
The last command is executed each time a new page is loaded
in espn.txt, replacing each occurrence of "era" with "earned run
average" so that the term is pronounced correctly.
Replace
Replaces each occurrence in the document text of one
string with another. This command may only occur in the LoadPage event. See the Define
command for more information about BOK events.
Syntax:
replace "before" "after" ...works with
loaded document text
Example Scripts
WinWord.BOK: retrieves and
reads the contents of the active document in the most recently used application with
"Word" in its window title.
sendkeys "word" "^A^C"
saveclipboard winword.txt
open winword.txt
readall
URL.BOK: asks the user for a url and downloads, loads, and
reads the file. Note that this example uses a variable.
query "Read File From Internet" "Enter a
complete URL" @0
downloadfile @0 url.htm automatic
open url.htm
Sawy210.BOK: downloads "Tom Sawyer" from Project
Gutenberg and loads it into the document window.
downloadfile
ftp://uiarchive.cso.uiuc.edu/pub/etext/gutenberg/etext93/sawy210.txt sawy210.txt
neveroverwrite
linebreak true
open sawy210.txt
FileList.BOK: replaces the recent file list with a custom
table of contents. Message.txt would contain a description of the table of contents and
how to use it to choose an etext to read.
downloadfile http://www.pixi.com/~reader1/contents.txt
contents.txt automatic
downloadfile http://www.pixi.com/~reader1/contents.txt message.txt automatic
loadfilelist contents.txt
open message.txt
CustRead.BOK: downloads an etext and a document dictionary.
Applies the document dictionary, containing custom pronunciations. Opens the etext for
reading.
downloadfile http://www.pixi.com/~reader1/test.dic
document.dic automatic
downloadfile http://www.pixi.com/~reader1/example.txt example.txt automatic
docdict document.dic
open example.txt
|