mcgrew@dartagnan.rutgers.edu (Charles Mcgrew) (09/15/89)
Submitted-by: apctrc!zmls04@uunet.uu.net (Martin L. Smith)
Posting-number: Volume 1, Issue 62
Archive-name: hype/part02
#! /bin/sh
# This is a shell archive, meaning:
# 1. Remove everything above the #! /bin/sh line.
# 2. Save the resulting text in a file.
# 3. Execute the file with /bin/sh (not csh) to create the files:
# Guide
# This archive created: Thu Sep 14 20:46:42 1989
export PATH; PATH=/bin:$PATH
if test ! -d 'Guide'
then
echo shar: creating directory "'Guide'"
mkdir 'Guide'
fi
echo shar: entering directory "'Guide'"
cd 'Guide'
echo shar: extracting "'Makefile'" '(915 characters)'
if test -f 'Makefile'
then
echo shar: will not over-write existing file "'Makefile'"
else
sed 's/^ X//' << \SHAR_EOF > 'Makefile'
X#
X# We used Frame to prepare the figures. I've added postscript
X# versions of the Frame figures and modified the makefile to
X# simply send them to the printer.
X#
X
XFILES = macros \
X title \
X preface \
X introduction \
X tree \
X menus \
X messages \
X script \
X builtins \
X startup \
X conventions \
X content
X
XFRAMEFILES = figure1.doc figure2.doc figure3.doc
X
XPSFILES = figure1.ps figure2.ps figure3.ps
X
Xcrt:
X tbl $(FILES) | nroff -ms | col -b | more -f
X
Xtroff:
X tbl $(FILES) | troff -t -ms | lpr -t
X
Xpostscript:
X lpr ${PSFILES}
X
Xframe:
X csh -c "setenv PRODUCT frame; \
X source /usr/local/bin/product.csh; \
X fmbook figure1.doc -p -g figure2.doc -p -g figure3.doc -p"
X
Xlpr:
X make troff
X make postscript
X
Xspell:
X deroff $(FILES) | spell | more
X
Xsafe:
X rm -rf .safe
X ar rv .safe $(FILES) $(FRAMEFILES)
X chmod ugo-w .safe
X
Xtest:
X tbl macros title introduction builtins content | \
X troff -t -ms | lpr -t
X
SHAR_EOF
if test 915 -ne "`wc -c < 'Makefile'`"
then
echo shar: error transmitting "'Makefile'" '(should have been 915 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'builtins'" '(18326 characters)'
if test -f 'builtins'
then
echo shar: will not over-write existing file "'builtins'"
else
sed 's/^ X//' << \SHAR_EOF > 'builtins'
X.ds RH Builtin Functions
X.bp
X.SH
X.LG
X.LG
XBuiltin Functions
X.Xs "Builtin Functions"
X.SM
X.SM
X.SH
XPreliminaries
X.PP
XIn general,
Xvalues which are interpreted as numbers can be anything.
XStrings which cannot be interpreted as having leading numeric
Xvalues are assigned the value 0.
X.PP
XFunctions which are said to return entities
X(such as objects)
Xactually
X(unless otherwise indicated)
Xreturn the absolute pathname of an entity.
XThe pathname may be in numeric (indexed) form.
X.NH 0
X.LG
XOpen, Close, and Redraw Objects
X.Xn "Open, Close, and Redraw Objects"
X.SM
X.LP
X\fIOpening\fR an object causes it to become visible.
X\fIClosing\fR an object causes it to disappear.
X.I Failure
Xfor the following functions means specifying a non-existent
Xor impossible path.
X.RS
X.IP "\fBopen(\fIa\fB)\fR" 10
Xopens the object \fIa\fR.
XIt returns \fIa\fR on success or an empty string on failure.
XIt is not an error to open an opened object.
X.IP "\fBclose(\fIa\fB)\fR" 10
Xcloses the object \fIa\fR.
XIt returns \fIa\fR on success or an empty string on failure.
XIt is not an error to close a closed object.
X.IP "\fBrefresh(\fIa\fB)\fR" 10
Xcauses \fIa\fR to redraw itself.
XIt is not an error to refresh an object which is not opened
X(but it is a no-op).
XIt returns \fIa\fR on success or an empty string on failure.
X.RE
X.NH
X.LG
XObject and Object Data Manipulation
X.Xn "Object and Object Data Manipulation"
X.SM
X.LP
X.RS
X.IP "\fBgetnthobject(\fIobject, n\fB)\fR" 10
Xreturns the absolute path name
Xfor the \fIn\fRth child object of \fIobject\fR
Xon success
Xor an empty string on any error.
X.IP "\fBsetobjname(\fIobject, name\fB)\fR" 10
Xchanges the name string of \fIobject\fR to \fIname\fR.
XIt returns \fIname\fR on success and an empty string on any error.
X.IP "\fBgetobjname(\fIobject\fB)\fR" 10
Xreturns the name string of
X.I object
Xon success
Xor an empty string on any error.
X.IP "\fBsetobjcolor(\fIobject, color\fB)\fR" 10
Xsets the color of \fIobject\fR to \fIcolor\fR.
X\fBColor\fR is a string containing the red, green, and blue color values,
Xrespectively,
Xeach in the range [0..255] and separated by whitespace.
XIt returns \fIcolor\fR on success and an empty string on any error.
X.IP "\fBgetobjcolor(\fIobject\fB)\fR" 10
Xreturns the color string associated with \fIobject\fR
Xon success
Xor an empty string on any error.
X.IP "\fBsetobjlabel(\fIobject, label\fB)\fR" 10
Xsets the label of \fIobject\fR to \fIlabel\fR.
XIt returns \fIlabel\fR
Xon success
Xor an empty string on any error.
XIf \fIlabel\fR is the empty string,
Xthe object's path becomes its label.
XIf \fIlabel\fR has the special value ".",
Xthe object has no label.
X.IP "\fBgetobjlabel(\fIobject)\fR" 10
Xreturns the label of \fIobject\fR
Xon success
Xor an empty string on any error.
X.IP "\fBdelobject(\fIobject\fB)\fR" 10
Xdeletes \fIobject\fR.
XIt returns \fIobject\fR on success
Xor an empty string on any error.
XThis action deletes everything below
X.I object
Xin the tree.
X.IP "\fBnumchildren(\fIobject\fB)\fR" 10
Xreturns the number of children (child objects) of \fIobject\fR
Xon success and an empty string on any error.
X.IP "\fBnumpanes(\fIobject\fB)\fR" 10
Xreturns the number of panes in \fIobject\fR
Xon success and an empty string on any error.
X.IP "\fBgetnthpane(\fIobject, n\fB)\fR" 10
Xreturns the absolute path name
Xfor the \fIn\fRth pane of \fIobject\fR
Xon success
Xor an empty string on any error.
X.IP "\fBnumtls(\fIobject\fB)\fR" 10
Xreturns the number of templates in \fIobject\fR
Xon success and an empty string on any error.
X.IP "\fBgetnthtl(\fIobject, n\fB)\fR" 10
Xreturns the absolute path name
Xfor the \fIn\fRth template of \fIobject\fR
Xon success
Xor an empty string on any error.
X.IP "\fBmakenewchild(\fIobject\fB)\fR" 10
Xadds a child object to \fIobject\fR.
XIt returns the path of the new object on success
Xand an empty string on failure.
X.IP "\fBmakenewsibling(\fIobject\fB)\fR" 10
Xcreates a sibling object for \fIobject\fR in the latter's parent.
XIt returns the path of the new object on success
Xand an empty string on failure.
X.RE
X.NH
X.LG
XTemplate and Pane Configuration
X.Xn "Template and Pane Configuration"
X.SM
X.RS
X.IP "\fBgetnthitem(\fItemplate, n\fB)\fR" 10
Xreturns the absolute path name of the \fIn\fRth item
Xin template on success
Xor an empty string.
XNote that item numbering starts at 0.
X.IP "\fBnumitems(\fItemplate\fB)\fR" 10
Xreturns the number of items in \fItemplate\fR
Xon success
Xor an empty string on any error.
X.KS
X.IP "\fBaddtext(\fItemplate\fB)\fR \(em" 10
X.IP "\fBaddbutton(\fItemplate\fB)\fR \(em" 10
X.IP "\fBaddslider(\fItemplate\fB)\fR \(em" 10
X.IP "\fBaddtoggle(\fItemplate\fB)\fR \(em" 10
X.IP "\fBaddtextsw(\fItemplate\fB)\fR \(em" 10
XEach adds a new item to \fItemplate\fR
Xand
Xreturns the path of the new item
Xor an empty string on any error.
X\fBAddtextsw\fR and \fBaddtoggle\fR do not yet exist.
X.KE
X.IP "\fBdelitem(\fIitem\fB)\fR" 10
Xdeletes \fIitem\fR.
XIt returns its argument
Xon success
Xor an empty string on any error.
X.KS
X.IP "\fBsettlcolor(\fItemplate, color\fB)\fR \(em" 10
X.IP "\fBgettlcolor(\fItemplate\fB)\fR \(em" 10
XSets/gets \fItemplate\fR's color attribute.
XTemplate and pane colors are not presently supported
Xbut the attributes exist.
X.KE
X.KS
X.IP "\fBsettlscript(\fItemplate, script\fB)\fR \(em" 10
X.IP "\fBgettlscript(\fItemplate\fB)\fR \(em" 10
X.IP "\fBsettlbgtext(\fItemplate, text\fB)\fR \(em" 10
X.IP "\fBgettlbgtext(\fItemplate\fB)\fR \(em" 10
XThese functions manipulate the
X.I "background text"
Xon a template (or pane).
XThis feature (\fBbgtext\fR) is flaky in Sunview.
X.KE
X.RE
X.NH
X.LG
XItem Data Extraction
X.Xn "Item Data Extraction"
X.SM
X.LP
XEach of these functions
Xreturns the appropriate string
Xfor its \fIitem\fR argument
Xon success
Xor an empty string on any error.
X.RS
X.IP "\fBgetitemval(\fIitem\fB)\fR" 10
X.IP "\fBgetitemname(\fIitem\fB)\fR" 10
X.IP "\fBgetitemmin(\fIitem\fB)\fR" 10
X.IP "\fBgetitemmax(\fIitem\fB)\fR" 10
X.IP "\fBgetitemicon(\fIitem\fB)\fR" 10
X(\fIIcons\fR are not currently supported.)
X.IP "\fBgetitemform(\fIitem\fB)\fR" 10
X.IP "\fBgetitemdef(\fIitem\fB)\fR" 10
XThe item's default value.
X.IP "\fBgetitemlabel(\fIitem\fB)\fR" 10
X.IP "\fBgetitemtoggles(\fIitem\fB)\fR" 10
X.IP "\fBgetitemlux(\fIitem\fB)\fR \(em" 10
X.IP "\fBgetitemluy(\fIitem\fB)\fR \(em" 10
X.B Lux
Xand
X.B luy
Xare the item's
X.I "left-upper x"
Xand
X.I "left-upper y"
Xcoordinates;
Xthey are specified in pixels relative to the pane's origin.
X.IP "\fBgetitemtype(\fIitem\fB)\fR" 10
XReturns one of the strings
X"button", "slider", "text", "textsw", or "toggle".
X.IP "\fBgetitemscript(\fIitem\fB)\fR" 10
XReturns the item's \fIentire\fR script as a string.
X(Recall we said that strings could be of arbitrary size.)
X.RE
X.NH
X.LG
XItem Data Insertion
X.Xn "Item Data Insertion"
X.SM
X.LP
XEach returns \fIvalue\fR
Xon success
Xor any empty string on any error.
X.RS
X.IP "\fBsetitemval(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemname(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemmin(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemmax(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemicon(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemform(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemdef(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemlabel(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemtoggles(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemlux(\fIitem, value\fB)\fR \(em" 10
X.IP "\fBsetitemluy(\fIitem, value\fB)\fR \(em" 10
XThese two functions may be used to move the item about.
X(See
X.B getitemlux
Xabove.)
X.IP "\fBsetitemtype(\fIitem, value\fB)\fR" 10
X.IP "\fBsetitemscript(\fIitem, value\fB)\fR" 10
X.IP "\fBrefreshitem(\fIitem\fB)\fR" 10
XCauses the \fIitem\fR's display to be redrawn.
XRefreshing is often necessary to cause a change to appear on the screen.
X.RE
X.NH
X.LG
XTalking to the World
X.Xn "Talking to the World"
X.SM
X.LP
XThe functions in this category support a variety
Xof ways of interacting with the user.
XIt is useful to try them out in simple scripts
Xto see what they do before plunging on.
X.RS
X.IP "\fBask(\fIstring\fB)\fR" 10
Xdisplays \fIstring\fR above a text item into which
Xthe user can type.
XIt also provides "cancel" and "ok" buttons.
XIt returns the user's input or an empty string.
X.IP "\fBchoose(\fImessage, leftbutton, rightbutton\fB)\fR" 10
Xopens a pop-up menu with \fImessage\fR underneath
Xwhich are two buttons labeled with the contents of
X\fIleftbutton\fR and \fIrightbutton\fR, respectively.
XIt returns the label of the selected button.
X.IP "\fBstdout(\fIstring\fB)\fR" 10
Xsends \fIstring\fR
Xfollowed by a newline to \fBhype\fR's \fIstdout\fR.
XIt returns \fIstring\fR.
X.IP "\fBstderr(\fIstring\fB)\fR" 10
Xsends \fIstring\fR
Xfollowed by a newline to \fBhype\fR's \fIstderr\fR.
XIt returns \fIstring\fR.
X.IP "\fBmenu(\fImenustring\fB)\fR" 10
Xposts a menu containing the choices in \fImenustring\fR and
Xreturns the user's selection.
X.IP "" 10
X.B Menustring
Xis a complete specification of a family of walking menus.
XMembers associated with a given level are enclosed in parentheses
Xand separated by white space.
XA sub-menu is specified by appending a ":" followed by the
Xsub-menu specification to the menu item from which the sub-menu
Xdescends.
XThe menu is posted in the upper lefthand corner of the current window.
X.B Hype
Xblocks (the rest of the screen is frozen)
Xuntil an item is selected.
XAn example of a menustring is:
X.RS
X\fB"(a b:(b1 b2) c d:(d1:(d11 d12) d2) e)"\fR
X.RE
XNote that the outer-level of the menustring must include
Xparentheses.
XThe return value (selection) is specified, bottom-up,
Xas a series of space-separated names.
XIn the above example,
Xselecting the item \fBd12\fR would return the string
X.RS
X\fB"d12 d1 d"\fR
X.RE
X.IP "\fBselect(\fIselectstring\fB)\fR" 10
Xposts a selection box formed from the white-space separated items
Xin the argument.
XThe (\fIpossibly multiple\fR) items selected are returned.
XThe box has "OK" and "Cancel" buttons.
X.RE
X.NH
X.LG
XClipboard Manipulation
X.Xn "Clipboard Manipulation"
X.SM
X.LP
XThe \fIclipboard\fR (\fBCB\fR)
Xis a feature to which entities of any type
Xcan be written and from which
Xthey can be pasted onto a new owning entity.
X\fICopying\fR replaces the current contents of
X.B CB
Xwith some new entity.
X.I Pasting
Xadds the current contents of
X.B CB
Xto some entity but doesn't change the contents of
X.B CB .
X.B Hype
Xenforces consistency in use of
X.B CB :
X.I pasting
Xis only allowed if there is an entity
Xcurrently in
X.B CB
Xand if the entity is of the appropriate type; an
X.I item ,
Xfor instance, cannot be pasted
Xonto an
X.I object
Xonly onto a
X.I template .
X.RS
X.KS
X.IP "\fBcopyitem(\fIitem\fB)\fR \(em" 10
X.IP "\fBcopytl(\fItemplate\fB)\fR \(em" 10
X.IP "\fBcopyobj(\fIobject\fB)\fR \(em" 10
XEach on success
Xreplaces the current contents of
X.B CB
Xwith the indicated entity.
XEach returns the absolute path name of the new entity
Xor an empty string on failure.
X.KE
X.RE
X.RS
X.KS
X.IP "\fBpasteitem(\fItemplate\fB)\fR \(em" 10
X.IP "\fBpastetl(\fIobject\fB)\fR \(em" 10
X.IP "\fBpasteobj(\fIobject\fB)\fR \(em" 10
X.IP "\fBpasteobjtree(\fIobject\fB)\fR \(em" 10
XEach pastes
X.B CB
Xas an entity of the indicated type
Xat the requested location.
XReturns an absolute path to the
Xnew entity on success
Xor an empty string on failure.
XThe contents of the clipboard are not changed.
X.KE
X.RE
X
X.NH
X.LG
XMiscellaneous Functions
X.Xn "Miscellaneous Functions"
X.SM
X.RS
X.IP "\fBsaveobj(\fIobject, filename\fB)\fR" 10
Xwrites the hierarchy at and below \fIobject\fR
Xto the file \fIfilename\fR.
XAny existing contents of \fIfilename\fR are destroyed.
XReturns \fIobject\fR on success and an empty string on failure.
X.IP "\fBloadover(\fIobject, filename\fB)\fR" 10
Xloads the contents of \fIfilename\fR onto the slot
Xwhere \fIobject\fR resides.
X.I Object
Xis obliterated by this action.
XReturns \fIobject\fR on success and an empty string on failure.
X.IP "\fBloadbelow(\fIobject, filename\fB)\fR" 10
Xloads the contents of \fIfilename\fR as a child of \fIobject\fR.
XReturns the newly added object on success.
X.IP "\fBexectext(\fItext\fB)\fR" 10
Xcompiles the script \fItext\fR and executes it in the current context
X(that is, the script executes at the current entity).
X.I Text
Xmust be a single (\fIpossibly compound\fR) statement.
XReturns the \fBreturn\fRed value of \fItext\fR on success
Xor an empty string on failure.
X.IP "\fBsavestate()\fR" 10
Xcauses the current
X.B hype
Xstate to be written to the current state file.
X(We don't know what this does if the current state file is not defined.)
X.IP "\fBsetglob(\fIname, value\fB)\fR" 10
Xcauses the global variable
X.I name
Xto be created (if it did not already exist)
Xand for it to be given the value
X.I value .
X.IP "\fBgetglob(\fIname\fB)\fR" 10
Xreturns the value of the global variable
X.I name
Xif it exists, or an empty string if it does not.
X.RE
X.NH
X.LG
XMessages and Awareness
X.Xn "Messages and Awareness"
X.SM
X.RS
X.IP "\fBself(\fI\fB)\fR" 10
Xreturns an absolute path name of the current entity.
XOften used as the target of a message meant to propagate upward.
X.IP "\fBsend(\fImessage, target, parameter\fB)\fR"
Xreturns the value \fBreturn\fRed by the script which intercepted
X\fImessage\fR,
Xor an empty string in the case of uncaught messages
Xor caught messages for which the catching script
Xmakes no explicit \fBreturn\fR.
X.IP "\fBparam(\fI\fB)\fR" 10
Xreturns the \fIparameter\fR to the message which awakened the current script.
X.IP "\fBtarget(\fI\fB)\fR" 10
Xreturns the \fItarget\fR argument of the originating \fBsend\fR.
XThis value may be different from \fBself()\fR (above)
Xif the original target did not intercept the message.
X.IP "\fBpass(\fI\fB)\fR" 10
Xcauses the current message to resume propagation up the hierarchy
Xas though it had never been caught;
Xin particular, the message keeps its original \fItarget\fR.
XIt returns the return value of the next intercepting script.
X.IP "\fBbroadcast(\fImessage, firstobject, parameter\fB)\fR" 10
Xdistributes
X.I message
Xto
X.I firstobject
Xand every object below it in the
X.B hype
Xtree
X(panes and items are skipped).
XThe order of visitation is depth-first pre-order.
XIt returns an empty string.
X.I Firstobject
Xreceives the message first.
XThe
X.B target()
Xof such a message is
X.B self()
Xfor each receiver.
X.RE
X.NH
X.LG
XString Manipulation
X.Xn "String Manipulation"
X.SM
X.LP
XMost of these functions do not have error conditions.
X.LP
XA string is a sequence of characters.
XEvery string has zero or more characters.
XThe
X.I "empty string" ,
X"",
Xhas zero characters.
XThere is no notion of a
X.B NULL
Xstring
Xas there is in C.
X.LP
XWords are components of a string separated by whitespace
X(space, tab, and newline).
XA string has zero or more words.
XThe empty string and all strings having only whitespace
Xhave zero words.
X.LP
XLines are components of a string separated by newlines
Xor terminated by the end of the string.
XEvery string except the empty string has at least one line.
XA string consisting \fIonly\fR of newlines has as many lines
Xas it has characters.
XThere is no end-of-string `character' as there is in C ('\\\^0' in C),
Xso the end of the string does not add an additional line.
X.LP
XClauses are components of a string separated by commas
Xor terminated by the end of the string.
XThe rules for clause-counting are identical to those
Xfor line-counting using commas instead of newlines.
X.RS
X.IP "\fBnumval(\fIs\fB)\fR" 10
Xreturns its argument as a number.
XIf \fIs\fR does not start with a sensible numeric value,
X.B numval
Xreturns 0.
X.IP "\fBstrlen(\fIs\fB)\fR" 10
Xreturns the number of characters in its argument.
X.IP "\fBsubstring(\fIstring, n, m\fB)\fR" 10
Xreturns the substring of
X.I string
Xformed from characters numbered
X.I n
Xthrough
X.I m .
XNote that character indexing begins with 0.
X.IP "\fBnumchars(\fIs\fB)\fR\ \ \ " 10
Xreturns the number of characters in its argument.
XIt is the same as
X.B strlen() .
X.IP "\fBnumwords(\fIs\fB)\fR" 10
Xreturns the number of white-space separated words in its argument.
X.IP "\fBnumlines(\fIs\fB)\fR\ \ \ " 10
Xreturns the number of newline-separated or end-of-string-terminated
Xgroups of characters in its argument.
X.IP "\fBnumclauses(\fIs\fB)\fR" 10
Xreturns the number of comma-separated elements in its argument.
X.RE
X.RS
X.KS
X.IP "\fBnthchar(\fIs, n\fB)\fR \(em" 10
X.IP "\fBnthword(\fIs, n\fB)\fR \(em" 10
X.IP "\fBnthline(\fIs, n\fB)\fR \(em" 10
X.IP "\fBnthclause(\fIs, n\fB)\fR \(em" 10
XEach returns the
X.I n th
Xcharacter, word, line
Xor clause in
X.I s
Xor an empty string.
X.KE
X.RE
X.RS
X.IP "\fBsformat(\fIformat, args...\fB)\fR" 10
Xreturns a formatted string using (\fIonly\fR) the \fI%s\fR
Xformat type of \fBsprintf(3)\fR
Xor an empty string on any error.
XIt is an error to not have enough arguments.
X.RE
X.NH
X.LG
XOperating System Commands
X.Xn "Operating System Commands"
X.SM
X.LP
XFunctions which spawn other processes
Xand wait for child process completion
Xwill result in the \fBhype\fR interpreter blocking
Xuntil the child process completes.
X.RS
X.IP "\fBputenv(\fIstring\fB)\fR" 10
Xinserts \fIstring\fR into \fBhype\fR's environment.
X.IP "\fBgetenv(\fIname\fB)\fR" 10
Xreturns the value of the environment variable \fIname\fR,
Xor an empty string if the variable is not present.
X.IP "\fBunix(\fIcmd\fB)\fR" 10
Xruns \fIcmd\fR a subshell.
XIt returns \fIcmd\fR.
X.IP "\fBunixbg(\fIcmd\fB)\fR\ \ " 10
Xis like
X.B unix()
Xbut \fIcmd\fR is run in the background.
XIt also broadcasts the message "jobStartedBg" to the entire tree
Xwith the child process id and the command (separated by a comma)
Xas the parameter.
XUpon child termination, "jobDone" is broadcast to root
Xwith the child process id as a parameter.
X.IP "\fBexit(\fI\fB)\fR" 10
Xsaves the current state and exits.
X.IP "\fBabort(\fI\fB)\fR" 10
Xexits without saving the current state.
X.IP "\fBgetcwd(\fI\fB)\fR" 10
Xreturns the current working directory.
X.IP "\fBchdir(\fInewdir\fB)\fR" 10
Xchanges the current directory to \fInewdir\fR.
XIt returns
X.B 0
Xon success or the value of
X.B errno(2)
Xon any failure.
X.IP "\fBpwrite(\fIcmd, string\fB)\fR" 10
Xopens the process
X.I cmd
Xas a writable pipe and sends
X.I string
Xto its stdin.
XIt returns
X.I string .
XFor example,
Xto send e-mail from within a script,
Xtry
X.DS C
X\fBpwrite("mail zxxx01", "mail works");\fR
X.DE
Xand to add the contents of a variable,
X.B newstuff ,
Xto the end of a file,
X.B stuff_log ,
Xuse
X.DS C
X\fBpwrite("cat >> stuff_log", newstuff);\fR
X.DE
X.IP "\fBpread(\fIcmd\fB)\fR" 10
Xopens \fIcmd\fR as a readable pipe and
Xreturns the output as \fBpread\fR's return value.
XFor example,
Xto get a list of all the files in the current directory,
Xuse
X.DS C
X\fBfiles = pread("ls");\fR
X.DE
Xwhich assigns the output of \fBls\fR to \fBfiles\fR.
X.RE
SHAR_EOF
if test 18326 -ne "`wc -c < 'builtins'`"
then
echo shar: error transmitting "'builtins'" '(should have been 18326 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'introduction'" '(4381 characters)'
if test -f 'introduction'
then
echo shar: will not over-write existing file "'introduction'"
else
sed 's/^ X//' << \SHAR_EOF > 'introduction'
X.ds RH Introduction
X.bp
X.SH
X.LG
X.LG
XIntroduction
X.Xs Introduction
X.NL
X.NH 0
X.LG
XAbout Hype
X.Xn "About Hype"
X.NL
X.PP
X\fBHype\fR
Xis an object-oriented system
Xwhich can be extensively customized
Xto provide an interactive visual interface
Xfor other programs.
XIt supports a hierarchical tree of windows
Xwhich can open (appear) and close (disappear)
Xand which can communicate with each other by sending messages.
XWindows can contain a selection of \fIwidgets\fR,
Xsuch as buttons, slider bars, choice lists, and text items.
X.PP
XWindows and widgets respond to user input.
XThe response of all of the entities in a \fBhype\fR system
Xto both external stimuli (mouse clicks, keystrokes, \fIetc\fR.)
Xand to internal stimuli (messages) can be specified by the
Xbuilder of a \fBhype\fR machine through program snippets
Xwritten in an internal scripting language
Xand attached to the entity.
X.PP
XThe script language is a powerful interpreted language
Xwhich is a significant subset of \fBC\fR.
XIt supports numeric and string computation,
Xas well as a variety of control-flow mechanisms.
XAn extensive library of built-in functions
Xsupports
Xinteraction between a \fBhype\fR application and the
Xoperating system.
XA \fBhype\fR application may spawn processes
Xeither as "normal" children or at the end of an input
Xor output pipe.
XIt may spawn processes in background and still
Xrespond to child process completion.
X.PP
XA \fBhype\fR application is created by building an appropriate
Xwindow structure,
Xpopulating the windows with interactive items (widgets),
Xand attaching scripts to some of the windows and items.
X.B Hype
Xprovides an interactive environment for application development
Xwhich greatly simplifies widget construction and placement
Xand provides an effective prototyping environment.
X.NH
X.LG
XWhy Hype Was Created
X.Xn "Why Hype Was Created"
X.SM
X.PP
XModern computer workstations with bit-mapped displays
Xfeature sophisticated user-interface systems
Xwhich are characterized by a high degree of interactivity
Xbetween user actions (such as moving a mouse or pressing a key)
Xand the display.
XThe user interfaces these systems make possible is a great improvement
Xover those which have been widely available in the past.
X.PP
XThis potential has a price:
Xthe programmatic interfaces to these systems is complex
Xand the experience needed to use them well is not yet widely available.
XEven when experienced programmers are available,
Xmaking an application interactive requires substantial effort.
XThe more mature of these systems are vendor-specific
Xand thus sacrifice portability,
Xhowever, there is strong reason to think that
X.B X11
Xmay remove this drawback.
X.PP
XFor many families of applications,
Xuser-interactions are restricted to fairly simple types.
XThe user may want to choose several sources of input
X(such as existing files),
Xselect a variety of run-time parameters
X(which we may want to check for reasonableness),
Xexecute the application,
Xand view the results
X(usually from files generated by the program).
XA common characteristic of these applications
Xis that the user does not interact with the central computation:
Xhe only sets it up and views the results.
X.PP
XWe believe that this type of application is quite common.
XWe also believe that it is practical to address the needs
Xfor non-intimate interaction by building a specialized
Xprogrammable interface interpreter, a \fImachine\fR,
Xwhich can be easily customized for various applications.
XWe have explored this notion by writing a program, \fBhype\fR,
Xwhich supports a simple but versatile model of user-interaction
Xand which can be easily tailored for applications
Xor families of applications.
XIn our experience (which is still modest),
Xthis approach has several advantages:
X.RS
X.IP \(bu
XWriting customizing programs for \fBhype\fR is much faster
Xand easier than writing programs for, say, \fBsuntools\fR.
X.IP \(bu
XAll existing \fBhype\fR programs can be ported to a new windowing system,
Xsuch as \fBX11\fR,
Xby porting only \fBhype\fR itself.
XWe have tried to take precautions to make the latter task reasonable.
X.IP \(bu
XApplications have no windowing code.
XThey are entirely command-line and data driven.
XThey can be substantially more naive in trusting their input.
XThese considerations remove a significant distraction from
Xapplication programming.
X.IP \(bu
XThe hierarchical-object model used in \fBhype\fR makes prototyping
Xeasy.
X.RE
SHAR_EOF
if test 4381 -ne "`wc -c < 'introduction'`"
then
echo shar: error transmitting "'introduction'" '(should have been 4381 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'macros'" '(501 characters)'
if test -f 'macros'
then
echo shar: will not over-write existing file "'macros'"
else
sed 's/^ X//' << \SHAR_EOF > 'macros'
X.nr PS 11
X.nr VS 13
X.nr LL 6.5i
X.\" put number heading in table of contents
X.\" use: .Xn string
X.de Xn
X.if \\n(NS=0 .ds Sp " \" 4 spaces
X.if \\n(NS=1 .ds Sp " \" 4 spaces
X.if \\n(NS=2 .ds Sp " \" 8 spaces
X.if \\n(NS=3 .ds Sp " \" 15 spaces
X.if \\n(NS=4 .ds Sp " \" 21 spaces
X.if \\n(NS=5 .ds Sp " \" 27 spaces
X.XS
X\\*(Sp\\*(SN \\$1
X.XE
X..
X.\" put section heading in table of contents
X.\" use: .Xs string
X.de Xs
X.XS
X\\$1
X.XE
X..
SHAR_EOF
if test 501 -ne "`wc -c < 'macros'`"
then
echo shar: error transmitting "'macros'" '(should have been 501 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'menus'" '(12120 characters)'
if test -f 'menus'
then
echo shar: will not over-write existing file "'menus'"
else
sed 's/^ X//' << \SHAR_EOF > 'menus'
X.ds RH Menus and Navigation
X.bp
X.SH
X.LG
X.LG
XMenus and Navigation
X.Xs "Menus and Navigation"
X.NL
X.PP
XCreating and programming \fBhype\fR states
Xis accomplished in part through menu-driven interaction with \fBhype\fR.
XMenus are used to create entities,
Xassign properties to them,
Xand program them.
X.PP
XThe tables below detail the contents of the \fBhype\fR menu system
Xand the function performed by the various entries.
XFigures 2 and 3
Xsummarize the structure of the menu system schematically.
X.NH 0
X.LG
XClipboard and Textboard
X.Xn "Clipboard and Textboard"
X.NL
X.PP
X\fBClipboard\fR and \fBTextboard\fR
Xare global variables which are accessible
Xeverywhere in \fBhype\fR.
XThey are referred to below as
X.B CB
Xand
X.B TB ,
Xrespectively.
X.PP
X.B Clipboard
Xcan hold a copy of an entity and its sub-entities.
XIt can be used to copy an entity or an entire portion of a
X.B hype
Xtree to a new location.
X.B Hype
Xwill prevent you from using CB inconsistently:
Xyou cannot copy an entity of one type
Xinto a slot that requires an entity of another type.
X.PP
X.B Textboard
Xcan hold text.
XIt can be used to copy scripts from one entity to another
X(which is very helpful)
Xand to copy a template's background text (\fBBG\fR).
X.PP
XBoth of these items can be manipulated by scripts
Xas well as the menus discussed below.
X.KS
X.NH
X.LG
XObject Border Menu
X.Xn "Object Border Menu"
X.NL
X.PP
XThis menu family is activated from the border
X(including the title-bar)
Xof an object.
XThis is the master menu of this family.
X.TS
Xcenter box;
Xc s s
Xlbw(0.8i)0 lbw(1.1i) lw(3.6i) .
X\fBObject Border Menu
X_
XWindow \(rh \fBWindow Sub-menu
XFile \(rh \fBFile Sub-menu
XObject \(rh \fBObject Sub-menu
XTemplate \(rh \fBTemplate Sub-menu
XPane \(rh \fBPane Sub-menu
XTest Script \fRopen an execution window for one line of script
XQuit Object \fRclose the object
X.TE
X.KE
X.KS
X.NH 2
XWindow Sub-menu
X.Xn "Window Sub-menu"
X.PP
XThis menu is activated from the Object Border Menu.
X.TS
Xcenter box;
Xc s s
Xlbw(0.8i)0 lbw(1.1i) lw(3.6i) .
X\fBWindow Sub-menu
X_
XClose/Open \fRmake object iconic/window
XMove \(rh \fRMove Sub-menu (sunview options)
XResize \(rh \fRResize Sub-Menu (sunview options)
XFront \fRmove window to front of desktop (show)
XBack \fRmove window to back of desktop (hide)
XRefresh \fRredraw the window
XFit Window \fRshrink-wrap the object/template around its panes/items
X.TE
X.KE
X.KS
X.NH 2
XFile Sub-menu
X.Xn "File Sub-menu"
X.PP
XThis menu is activated from the Object Border Menu.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBFile Sub-menu
X_
XSave State \fRsave state to the current state file
XSave & Quit \fRsave state to current state file and exit
XFile State \fRsave state to a new named file
XFile Subtree \fRsave the state at and below the current context to a file
XLoad Subtree \fRload the state from a file below the current context
XQuit, No Save \fRexit without saving state
XPretty Print \fRwrite a readable version of state to a file
X.TE
X.KE
X.KS
X.NH 2
XObject Sub-menu
X.Xn "Object Sub-menu"
X.PP
XThis menu is activated from the Object Border Menu.
X.TS
Xcenter box;
Xc s s
Xlbw(0.85i)0 lbw(1.05i) lw(3.6i) .
X\fBObject Sub-menu
X_
XObject Info \fRopen an \fIinfo\fR box for this object
XObj Script \(rh \fBObject Script Sub-menu
XClipboard \(rh \fBObject Clipboard Sub-menu
XCreate Child \fRcreate a new child object of the current object
XOpen Child \(rh \fRopen a child (from a pop-up)
XOpen Parent \fRopen the parent of the object
XDelete Obj \fRdelete this object
XClose Tree \fRclose the object and its descendants
XQuit Object \fRclose the object
X.TE
X.KE
X.KS
X.NH 3
XObject Script Sub-menu
X.Xn "Object Script Sub-menu"
X.PP
XThis menu is activated from the Object Sub-menu.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBObject Script Sub-menu
X_
XEdit Script \fRopen an editor on the object's script
XAppend TB to Script \fRappend the contents of TB to the object's script
XPrepend TB to Script \fRprepend the contents of TB to the object's script
XCopy Script to TB \fRcopy the object's script to TB
XEdit Textboard \fRedit TB
X.TE
X.KE
X.KS
X.NH 3
XObject Clipboard Sub-menu
X.Xn "Object Clipboard Sub-menu"
X.PP
XThis menu is activated from the Object Sub-menu.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBObject Clipboard Sub-menu
X_
XCopy Object to CB \fRcopy the object to the CB
XAdd CB Object as Child \fRadd object on CB as child of current object
XAdd CB Obj Tree as Child \fRadd object tree on CB as child of current object
XClipboard Holds ... \fRtell the current contents of the CB
X.TE
X.KE
X.KS
X.NH 2
XTemplate Sub-menu
X.Xn "Template Sub-menu"
X.PP
XThis menu is activated from the Object Border Menu.
X.TS
Xcenter box;
Xc s s
Xlbw(1.1i)0 lbw(0.8i) lw(3.6i) .
X\fBTemplate Sub-menu
X_
XOpen Template \(rh \fRopen a template of the object (from a pop-up)
XClipboard \(rh \fBTemplate Clipboard Sub-menu
XCreate Template \fRcreate a new blank template for this object
XClose All \fRclose all of the object's templates
X.TE
X.KE
X.KS
X.NH 3
XTemplate Clipboard Sub-menu
X.Xn "Template Clipboard Sub-menu"
X.PP
XThis menu is activated from the Template Sub-menu.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBTemplate Clipboard Sub-menu
X_
XAdd Template From CB \fRadd template from the CB as a new template
XClipboard Holds ... \fRtell the current contents of the CB
X.TE
X.KE
X.KS
X.NH 2
XPane Sub-menu
X.Xn "Pane Sub-menu"
X.PP
XThis menu is activated from the Object Border Menu.
X.TS
Xcenter box;
Xc s s
Xlbw(0.8i)0 lbw(1.1i) lw(3.6i) .
X\fBPane Sub-menu
X_
XAdd Pane \(rh \fRadd a specific pane (from a pop-up)
XDelete Pane \(rh \fRdelete a specific pane (from a pop-up)
X.TE
X.KE
X.bp
X.SH
XFIG 2
X.Xs " Fig. 2. Object Border Menu Hierarchy"
X.LP
XReplace this page with Figure 2.
X.bp
X.KS
X.NH
X.LG
XTemplate Border Menu
X.Xn "Template Border Menu"
X.NL
X.PP
XThis menu family is activated from the border
X(including the title bar)
Xof a template.
XThis menu is the master menu of the
XTemplate Border Menu family.
X.TS
Xcenter box;
Xc s s
Xlbw(1.2i)0 lbw(0.7i) lw(3.6i) .
X\fBTemplate Border Menu
X_
XWindow \(rh \fBWindow Sub-menu \fR
XTemplate Info \fRopen an \fIinfo\fR box for this template
XTemplate Script \(rh \fBTemplate Script Sub-menu
XBackground Text \(rh \fBTemplate BG Text Sub-Menu
XClipboard \(rh \fBTemplate Border Clipboard Sub-menu
XScroll Bars \(rh \fBScroll Bar Sub-menu
XAlter Grid Size \fRview or change the current grid size
XDelete Template \fRdelete this template
XOpen Owner Obj \fRopen the object that owns this template
XQuit Template \fRclose this template
X.TE
X.KE
X.KS
X.NH 2
XWindow Sub-menu
X.Xn "Window Sub-menu"
X.PP
XThis menu is activated from the Template Border Menu.
XIt is the same as the
X.B "Window Sub-menu"
Xactivated from the Object Border Menu.
X.TS
Xcenter box;
Xc s s
Xlbw(0.8i)0 lbw(1.1i) lw(3.6i) .
X\fBWindow Sub-menu
X_
XClose/Open \fRmake object iconic/window
XMove \(rh \fRMove Sub-menu (sunview options)
XResize \(rh \fRResize Sub-Menu (sunview options)
XFront \fRmove window to front of desktop (show)
XBack \fRmove window to back of desktop (hide)
XRefresh \fRredraw the window
XFit Window \fRshrink-wrap the object/template around its panes/items
X.TE
X.KE
X.KS
X.NH 2
XTemplate Script Sub-menu
X.Xn "Template Script Sub-menu"
X.PP
XThis menu is activated from the Template Border Menu.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBTemplate Script Sub-menu
X_
XEdit Script \fRopen an editor on the template's script
XAppend TB to Script \fRappend the contents of TB to the template's script
XPrepend TB to Script \fRprepend the contents of TB to the template's script
XCopy Script to TB \fRcopy the template's script to TB
XEdit Textboard \fRedit TB
X.TE
X.KE
X.KS
X.NH 2
XTemplate BG Text Sub-menu
X.Xn "Template BG Text Sub-menu"
X.PP
XThis menu is activated from the Template Border Menu.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBTemplate BG Text Sub-menu
X_
XEdit BG Text \fRopen an editor on background text
XAppend TB to BG Text \fRappend the contents of TB to background text
XPrepend TB to BG Text \fRprepend the contents of TB to background text
XCopy BG Text to TB \fRcopy background text to TB
X.TE
X.KE
X.KS
X.NH 2
XTemplate Border Clipboard Sub-menu
X.Xn "Template Border Clipboard Sub-menu"
X.PP
XThis menu is activated from the Template Border Menu.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBTemplate Border Clipboard Sub-menu
X_
XCopy Template to CB \fRcopy the current template to the CB
XClipboard Holds ... \fRtell the current contents of the CB
X.TE
X.KE
X.KS
X.NH 2
XScroll Bar Sub-menu
X.Xn "Scroll Bar Sub-menu"
X.PP
XThis menu is activated from the Template Border Menu.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBScroll Bar Sub-menu
X_
XToggle Vert Bar \fRadd/remove vertical scroll bars to template
XToggle Horiz Bar \fRadd/remove horizontal scroll bars to template
X.TE
X.KE
X.KS
X.NH
X.LG
XTemplate Contents Menu
X.Xn "Template Contents Menu"
X.NL
X.PP
XThis menu is activated from the interior of a template,
Xbut not over an item.
XSome entries in this menu lead to a pop-up
Xhaving the names of all of the template's items.
X.TS
Xcenter box;
Xc s s
Xlbw(0.8i)0 lbw(1.1i) lw(3.6i) .
X\fBTemplate Contents Menu
X_
XItem Info \(rh \fRopen an \fIinfo\fR box for an item (from a pop-up)
XEdit Script \(rh \fRopen an editor on an item's script (from a pop-up)
XTextBoard \(rh \fBTB Sub-menu
XClipboard \(rh \fBItem Clipboard Sub-menu
XCreate Item \fRadd a new item to the template
XDelete Item \(rh delete an item (from a pop-up)
X.TE
X.KE
X.KS
X.NH 2
XTB Sub-menu
X.Xn "TB Sub-menu"
X.PP
XThis menu is activated from the Template Contents Menu.
XEach entry leads to a pop-up having the names of all the items.
X.TS
Xcenter box;
Xc s s
Xlbw(1.45i)0 lbw(0.45i) lw(3.6i) .
X\fBTB Sub-menu
X_
XAppend TB to Script \(rh \fRappend the contents of TB to an item's script
XPrepend TB to Script \(rh \fRprepend the contents of TB to an item's script
XCopy Script to TB \(rh \fRcopy an item's script to TB
XEdit Textboard \fRedit TB
X.TE
X.KE
X.KS
X.NH 2
XItem Clipboard Sub-menu
X.Xn "Item Clipboard Sub-menu"
X.PP
XThis menu is activated from the Template Contents Menu.
X.TS
Xcenter box;
Xc s s
Xlbw(1.35i)0 lbw(0.55i) lw(3.6i) .
X\fBItem Clipboard Sub-menu
X_
XCopy Item to CB \(rh \fRcopy an item to CB (from pop-up)
XAdd Item From CB \fRadd item on CB to template
XClipboard Holds ... \fRtell the current contents of the CB
X.TE
X.KE
X.bp
X.SH
XFIG 3
X.Xs " Fig. 3. Template Menu Hierarchies"
X.LP
XReplace this page with Figure 3.
X.bp
X.KS
X.NH
X.LG
XInfo Boxes
X.Xn "Info Boxes"
X.NL
X.PP
XObjects, templates, and items have \fIinfo\fR boxes
Xwhich may be used to view or set the entity's
Xattributes
X(such as name, color,
X.I etc .).
XInfo boxes are accessible thru the menus.
X.NH 2
XObject Info
X.Xn "Object Info"
X.PP
XThe object's name, color, and label
X(a string which appears in the object's title bar)
Xare shown and can be modified.
XThe number of children, panes
Xand templates owned by the object are shown
Xbut cannot be modified.
XColor is specified by a string holding three
Xnumeric values,
Xeach in the range 0-255 inclusive,
Xwhich specify the red, green, and blue amplitudes, respectively.
XThus
X.RS
X\fB"255 0 0"\fR
X.RE
Xis red while
X.RS
X\fB"0 0 255"\fR
X.RE
Xis blue.
X(Keeping a \fBcolortool\fR active when setting colors
Xhelps a lot.)
X.KE
X.KS
X.NH 2
XTemplate Info
X.Xn "Template Info"
X.PP
XThe template's name is shown and can be changed.
XThe number of items the template owns and the name
Xof the object which owns it are shown but cannot be changed.
X.KE
X.KS
X.NH 2
XItem Info
X.Xn "Item Info"
X.PP
XThis box supports the examination or alteration
Xof every attribute of an item except its position
Xand its value.
XPosition is usually determined by dragging the item around
Xon its template with the middle mouse button.
XValue is usually set by interacting with the item.
X.I All
Xof an items attributes can be
Xaltered by script actions.
X.TS
Xcenter box;
Xc s
Xlbw(1.9i) lw(3.6i) .
X\fBItem Info Box
X_
XType \fBText, Button, Slider, Toggle, \fRor \fBText Sw\fR
XName \fRthe \fIreal\fR name of an item
XLabel \fRthe \fIvisible\fR name of an item
XDefault \fRthe initial value of the item
XChoices \fRlist of choices for a \fItoggle\fR
XMin \fRthe minimum value of a slider
XMax \fRthe maximum value of a slider
XForm \fRan internal attribute
XNumber \fRitem's index; can't be changed
XDisplay Length \fRthe length of a text item in \fIcharacters\fR
X \fRor the length of a slider bar in \fIpixels\fR
X.TE
X.KE
SHAR_EOF
if test 12120 -ne "`wc -c < 'menus'`"
then
echo shar: error transmitting "'menus'" '(should have been 12120 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'messages'" '(6346 characters)'
if test -f 'messages'
then
echo shar: will not over-write existing file "'messages'"
else
sed 's/^ X//' << \SHAR_EOF > 'messages'
X.ds RH Messages
X.bp
X.SH
X.LG
X.LG
XMessages
X.Xs Messages
X.SM
X.SM
X.PP
X\fBHype\fR is a message-based object-oriented system.
XA \fImessage\fR is a stimulus sent by one entity to another
Xor originated by an external asynchronous action
Xsuch as clicking on a mouse button or
Xthe death of a child process signal.
XA message is defined by three strings:
Xa \fIname\fR (such as "mouseUp"),
Xa \fItarget\fR (such as "MyParentObject"),
Xand a \fIparameter\fR string.
XEvery \fBhype\fR entity (object, pane, or item)
Xmay have an associated \fIscript\fR which specifies
Xthe entity's response to various messages.
X.NH 0
X.LG
XMessage Hierarchy
X.Xn "Message Hierarchy"
X.SM
X.PP
X\fBHype\fR supports two modes of message propagation.
XThe standard mode is \fIsend\fR,
Xsupported by the \fBsend\fR library function.
XThe second mode is \fIbroadcast\fR,
Xsupported by the \fBbroadcast\fR library function.
X.NH 2
XSend
X.Xn Send
X.PP
XA \fIsend\fR message is specified by three strings:
Xa message name, a target entity name, and a message parameter.
X\fISend\fR messages are transmitted hierarchically.
XWhen a message is sent,
X\fBhype\fR examines the message's \fItarget\fR entity
Xto determine if the entity will accept the message sent.
XA message is accepted by an entity if that entity's script
Xhas a handler for the message.
X(See the next section for more on scripts.)
XIf the target will accept the message,
Xthe appropriate snippet in the target's script is executed
Xand the snippet's \fIreturn\fR value is passed to the
Xmessage originator.
XNote that a script responding to a message
Xmay originate its own messages;
Xmessages are stacked by
X.B hype
Xjust as subroutine calls are in
Xconventional languages.
X.PP
XIf the target does not accept the message,
X\fBhype\fR conducts a hierarchical search for an entity that
Xwill handle it.
XFirst the target entity's \fIowner\fR is examined
Xto see if it will accept the message.
XIf it will not,
Xthen the owner's owner is examined, \fIetc\fR.
XIf \fBhype\fR reaches the tree's \fBroot\fR object
Xwithout successfully delivering the message,
Xthe message is discarded and an empty result is returned
Xto the message sender.
X.NH 2
XBroadcast
X.Xn Broadcast
X.PP
XA \fIbroadcast\fR message is specified by three strings:
Xthe message name,
Xthe \fIobject\fR on the \fBhype\fR tree
Xbelow which the message is to be broadcast
X(the message target),
Xand a message parameter.
XA broadcast message is sent to its target
Xand to every \fIobject\fR below the target.
X\fIBroadcast\fR messages are only sent to \fIobjects\fR,
Xnot to panes or items.
X.NH
X.LG
XMessage Names
X.Xn "Message Names"
X.SM
X.PP
XA message name is an arbitrary string.
XBy convention message names always begin with a lower-case
Xletter.
XEvery character within the message which would normally be
Xat the start of a word is capitalized, for example,
X.B mouseDown.
X\fBHype\fR does not expect or enforce this convention;
Xwe use it because it makes message names easy to reconstruct.
X.NH
X.LG
XBuiltin Messages
X.Xn "Builtin Messages"
X.SM
X.PP
X.B Hype
Xprovides a number of predefined messages
Xwhich are sent automatically on the occurrence
Xof certain events.
XNote that there is nothing to prohibit a script
Xfrom sending the same messages
X(and thus simulating an event).
X.RS
X.IP \fBmouseDown\fR
Xis sent to an \fIitem\fR or \fIpane\fR if the left mouse
Xbutton is depressed while the cursor is over
Xthat entity.
XThe parameter for this message is the string "\fBnull\fR".
X.IP \fBmouseUp\fR
Xis sent to an \fIitem\fR or \fIpane\fR if the left mouse
Xbutton is released while the cursor is over
Xthat entity.
XThe parameter for this message is the string "\fBnull\fR".
X.IP \fBinitHype\fR
Xis \fIbroadcast\fR from the root object of the \fBhype\fR tree
Xwhen \fBhype\fR begins execution.
XThe parameter for this message consists of the last
Xargument (if any) on the command line that invoked \fBhype\fR
Xand which was not an intrinsic \fBhype\fR argument.
X(There are some restrictions on actions which may be
Xtaken at start-up time:
Xthe windowing system is not active at this time
Xand it is not generally safe to pop up menus, \fIetc.\fR,
Xfrom within a script;
Xyou can \fBopen\fR objects safely.)
X.IP \fBexitHype\fR
Xis \fIbroadcast\fR from the root object of the hype tree
Xwhen \fBhype\fR halts.
X.IP \fBopenObject\fR
Xis sent to an object immediately after it is opened.
X.IP \fBcloseObject\fR
Xis sent to an object immediately before it is closed.
X.IP \fBjobStartedBg\fR
Xis broadcast from the root object of the \fBhype\fR tree
Xwhenever a job is started
Xin background mode
X(with \fBunixbg(\fIcmd\fB)\fR).
XThe message parameter consists of the child process id,
Xfollowed by a comma,
Xfollowed by a copy of \fIcmd\fR
X(the command that was run in background).
X.IP \fBjobDone\fR
Xis broadcast from the root object of the \fBhype\fR tree
Xwhenever a job running
Xin background exits.
XThe message parameter consists of the child process id,
Xfollowed by a comma,
Xfollowed by the value returned by the job.
XBecause of the structure of Sunview,
X\fBhype\fR will not actually respond to
Xthe death of a child until some user action
Xstimulates \fBhype\fR into awareness.
XUser actions can be as simple as moving the cursor from
Xone window to another.
X.RE
X.NH
X.LG
XUsing Messages
X.Xn "Using Messages"
X.SM
X.PP
XOne of the virtues of \fBhype\fR's
Xhierarchical message-handling is that
Xa script may take advantage of message-handlers
Xin hierarchically higher objects without knowing,
Xor caring,
Xwhere the desired handlers reside.
XIf, for example,
Xan object in a \fBhype\fR tree has a message handler of the form
X.RS
X.DS
X.B
X# "translateToFrench" is the name of the message.
X# It returns the French translation of param(), the
X# message's arguments.
X# note: param() returns the received message's parameter string
XtranslateToFrench:
X{
X englishtext = param();
X#
X# put code in here to translate englishtext to frenchtext.
X#
X return frenchtext;
X}.
X.DE
X.RE
X.LP
XThen any entity on the tree on or below this object can access this code
Xby knowing only the name of the message
X(and not necessarily where the message handler resides)
Xby sending a message to itself.
X.KS
XTo wit:
X.RS
X.DS
X.B
X# warn the (presumably french) user of a draft.
X# note: self() returns the name of the current entity,
X# and stderr() writes its argument to standard error.
X
X french = send("translateToFrench", self(), "Sir, your fly is open.");
X stderr( french );
X
X#
X# etc.
X#
X.DE
X.RE
X.KE
SHAR_EOF
if test 6346 -ne "`wc -c < 'messages'`"
then
echo shar: error transmitting "'messages'" '(should have been 6346 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'newtitle'" '(536 characters)'
if test -f 'newtitle'
then
echo shar: will not over-write existing file "'newtitle'"
else
sed 's/^ X//' << \SHAR_EOF > 'newtitle'
X.RP
X.TL
X.LG
X.LG
X.LG
XHype: A Programmer's Guide
X.NL
X.sp 3
X.AU
X.LG
X.LG
XThe Mutants of
XIntegrated Geophysics
X
XNovember 28, 1988
X.NL
X.ds LH Hype Programmer's Guide \(em Version 1.2
X.ds CH
X.ds CF
X.SH
X.LG
X.LG
XPreface
X.NL
X.PP
X\fBHype\fR is a tool for the construction
Xof event-activated programs
X(particularly user interfaces for \fIother\fR programs)
Xon window-oriented
X.UX
Xsystems.
XIt was written by Robert L. Read in 1988
Xat Amoco's Tulsa Research Center.
XInquiries or comments should be directed
Xto Martin L. Smith (\fBzmls04\fR) at TRC.
X
SHAR_EOF
if test 536 -ne "`wc -c < 'newtitle'`"
then
echo shar: error transmitting "'newtitle'" '(should have been 536 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'preface'" '(457 characters)'
if test -f 'preface'
then
echo shar: will not over-write existing file "'preface'"
else
sed 's/^ X//' << \SHAR_EOF > 'preface'
X.ds RH Preface
X.bp 1
X.ds CF -%-
X.SH
X.LG
X.LG
XPreface
X.Xs Preface
X.NL
X.PP
X\fBHype\fR is a tool for the construction
Xof event-activated programs
X(particularly user interfaces for \fIother\fR programs)
Xon window-oriented
X.UX
Xsystems.
XIt was written by Robert L. Read in 1988
Xat Amoco's Tulsa Research Center.
XInquiries or comments should be directed
Xto
XTerri L. Fischer (\fBztlf0a\fR),
XMartin L. Smith (\fBzmls04\fR),
Xor
XKim K. Dill (\fBzkkd0a\fR),
Xall at TRC.
SHAR_EOF
if test 457 -ne "`wc -c < 'preface'`"
then
echo shar: error transmitting "'preface'" '(should have been 457 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'script'" '(4713 characters)'
if test -f 'script'
then
echo shar: will not over-write existing file "'script'"
else
sed 's/^ X//' << \SHAR_EOF > 'script'
X.ds RH Scripts
X.bp
X.SH
X.LG
X.LG
XScripts
X.Xs Scripts
X.NL
X.NH 0
X.LG
XStructure of a Hype Script
X.Xn "Structure of a Hype Script"
X.SM
X.PP
XA \fBhype\fR entity's script consists of a series of message
Xnames each followed by a script language program,
Xor \fIsnippet\fR.
XComments are allowed anywhere except between a message name
Xdeclaration and the left brace which denotes the beginning
Xof the message's script program.
XComments consist of everything between a pound sign (which does not
Xlie within a quoted string,
Xand the end of the line in which the delimiter appears.
X.PP
XEach message name must be the first non-white entry on a line
Xand must be followed by a colon.
XThe next line must begin with a left brace.
XThe script \fBmust\fR be terminated by a left brace in column one
Xfollowed by a period in column two.
X(These peculiar restrictions exist only to make the separation
Xof an entity's script into separate message handlers easy.
XThey could be lifted.)
X.PP
XAn example of an entity's script is:
X.RS
X.SM
X.DS
X.B
X# fileList:
X# parameter: the directory of interest.
X# return: a list of the files in the directory.
X#
X# This handler opens a 'read' pipe to "ls" and
X# returns the result.
XfileList:
X{
X return pread( "ls " $$ param() );
X}.
X# selectFile:
X# parameter: directory of interest.
X# return: a file selected by the user.
XselectFile:
X{
X files = send("fileList", self(), param());
X selection = menu( "( " $$ files $$ " )" );
X return selection;
X}.
X.R
X.DE
X.LG
X.RE
X.PP
X.NH
X.LG
XHype Script Language
X.Xn "Hype Script Language"
X.SM
X.PP
X\fBHype\fR's script language is similar to C
Xin syntax and control structures;
Xit differs significantly in data representation
Xand variable types and declarations.
X.NH 2
XVariables and Types
X.Xn "Variables and Types"
X.PP
XAll variables are strings of potentially unlimited length.
XNumeric constants are converted to strings before use.
XWhen variables are used in a numeric context,
Xfloating-point numeric values are extracted on the fly.
XThis is done in a very simple way and strings with no leading
Xnumeric content (such as "Gadzooks442") evaluate to zero.
X.PP
XAll variables are automatic
X(local to the script in which they are used)
Xand there are no explicit declarations;
Xa variable is created when something is assigned to it.
XVariables must be created before they are referenced.
XVariable names may be of any length and are case-sensitive.
X.PP
XIn a boolean test,
Xan expression is considered to be \fIfalse\fR
Xif it is an empty string, "",
Xthe numeric value \fB0\fR,
Xor the string \fI"false"\fR,
Xotherwise it is \fItrue\fR.
X.NH 2
XOperators, Expressions, and Statements
X.Xn "Operators, Expressions, and Statements"
X.PP
X.B Hype
Xsupports most of the "common" C operators.
X.RS
X.RS
X.IP "++, --" 10
XThe familiar unary increment and decrement operators
Xof C;
Xthese work properly as both pre- and post- operators.
X.IP "+, -, *, /" 10
XConventional binary arithmetic operators.
X.IP "<, <=, >, >=, ==, !=" 10
XConventional relational operators.
XWork for both numbers and strings;
Xcomparison is numeric if both operands
Xappear to be numeric.
X.IP "&&, ||" 10
XLogical \fIand\fR and \fIor\fR.
XNote that these always evaluate
X.I both
Xelements in a relational expression, unlike C.
X.IP "=" 10
XThe assignment operator, "=", is an operator like
Xany other, thus expressions such as
X.RS
X.DS
X.B
Xa = (b = c + 27);
X.DE
X.RE
X.IP
Xare legal
X(and confusing, just as in C).
X.RE
X.RE
X.PP
X.B Hype
Xadds a string concatenation operator.
X.RS
X.RS
X.IP "$$" 10
Xstring concatenation.
X.RE
X.RE
X.PP
X.B Hype
Xstatements are terminated by a semicolon, ";".
XParentheses may be used freely.
XCompound statements can be formed by grouping
Xsimple statements
X(or other compound statements)
Xin braces, "{" and "}";
Xthere should be no ";" after a closing "}".
XThis is correct:
X.DS C
X\fBif(param() == "now") open(self());\fR
X.DE
XSo is this:
X.DS C
X\fBif(param() == "now") { open(self()); }\fR
X.DE
X.NH 2
XFlow of Control
X.Xn "Flow of Control"
X.PP
X.B Hype
Xsupports all of C's control structures except
X\fIswitch\fR and \fIdo-while\fR.
XIn particular it supports
X.RS
X.DS
X.B
X if(\fIcond\fB)
X \fIstatement\fB;
X [else [if...] \fIstatement\fB; ]
X
X while(\fIcond\fB)
X \fIstatement\fB;
X
X for(\fIexpression\fB; \fIcond\fB; \fIexpression\fB)
X \fIstatement\fB;
X
X break;
X
X continue;
X.R
X.DE
X.RE
Xwhere \fIstatement\fB;\fR can be replaced by a compound statement.
X.KS
X.NH 2
XReturn
X.Xn Return
X.PP
XThe \fIreturn\fR statement has the form
X.RS
X.DS
X \fBreturn \fIreturnvalue\fB;\fR
X.DE
X.RE
Xwhich causes the \fBsend\fR which originated the message
Xto return the value
X\fIreturnvalue\fR.
XAn explicit return must always have a parameter.
XA message handler which returns by running off the end of the script
Xreturns an
X.I "empty string" ,
X"\^".
X.KE
SHAR_EOF
if test 4713 -ne "`wc -c < 'script'`"
then
echo shar: error transmitting "'script'" '(should have been 4713 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'startup'" '(3957 characters)'
if test -f 'startup'
then
echo shar: will not over-write existing file "'startup'"
else
sed 's/^ X//' << \SHAR_EOF > 'startup'
X.ds RH Startup
X.bp
X.SH
X.LG
X.LG
XStartup
X.Xs Startup
X.SM
X.SM
X.PP
XHype configures itself at start-up under the
Xcontrol of environment variables,
Xcommand-line arguments,
Xand the contents of several files.
X.NH 0
X.LG
XState Files
X.Xn "State Files"
X.NL
X.PP
X\fBHype\fR has provision for writing a description
Xof its internal state to a \fIstate \fIfile\fR.
XThis file contains a complete description of the object
Xtree,
Xthe contents of each object,
Xall of the scripts in the system,
Xand information about the size, color, and placement
Xof all of the system's entities.
X\fBHype\fR,
Xreasonably enough,
Xcan read a state file and assume the state it describes.
X(State files are ASCII and slightly readable but they
Xshould
X.SM
XNEVER-NEVER-NEVER
X.NL
Xbe edited.)
X.PP
X\fBHype\fR currently provides optional support for the
Xnotion of a \fIpublic\fR and \fIprivate\fR state file.
XIn this configuration the public state
X(which cannot be modified by a user)
Xcontains the root of the tree and various objects of
Xcommon utility.
XThe private state joins the public state at a point
Xon the latter referred to as \fIhangbelow\fR.
XWhen this two-state configuration is used,
X\fIsaving\fR the state only updates the user's private state file.
XThis system appears to work but we haven't made much use of it
Xto date.
X.NH
X.LG
XOther Start-up features
X.Xn "Other Start-up features"
X.NL
X.PP
X\fBHype\fR offers two other features that are useful
Xwhen the program first begins execution.
XBefore any windows are open,
X\fBhype\fR \fIbroadcasts\fR the message \fBinitHype\fR to all of
Xthe objects in its tree.
XThe parameter of this message
Xis the last unused argument (if any) on \fBhype\fR's command line.
XThis feature is extremely useful for selecting
Xamong initial screen states.
X.PP
XAlso,
Xthe user may specify an \fIinitial \fIscript\fR
X(contained in a file)
Xwhich is interpreted after \fBinitHype\fR
Xhas been sent but before any windows are actually opened.
XThis option has not been well tested.
X.NH
X.LG
XEnvironment Variables
X.Xn "Environment Variables"
X.NL
X.PP
X\fBHype\fR's \fIenvironment\fR variables can be used to
Xspecify private and public state files,
Xthe location of \fIhangbelow\fR,
Xthe name of an initial script file,
Xand the user's privilege state.
XThe names to set in the environment are:
X.RS
X.IP \fBHYPE_PUBLIC=\fIpublicstate\fR 10
XThe name of a public state file.
X.IP \fBHYPE_STATE=\fIprivatestate\fR 10
XThe name of a private state file.
X.IP \fBHYPE_HANGBELOW=\fIhangbelow\fR 10
XThe point in the public state
X(if there is a public state)
Xat which the private state hangs.
X.IP \fBHYPE_INIT_SCRIPT=\fIscriptfile\fR 10
XThe name of a file containing a script to be
Xexecuted at start-up.
X.IP \fBHYPE_PRIVILEGE\fR 10
XIf this variable exists in the environment,
Xthe user will be allowed to modify the contents
Xof a public state (and its file).
XShould not normally be set.
X.RE
X.NH
X.LG
XCommand-line Arguments
X.Xn "Command-line Arguments"
X.NL
X.PP
XCommand-line arguments can be used to set
Xall of the features that can be set with
Xenvironment variables.
XCommand-line arguments override environment settings.
X.RS
X.IP \fB-P\fIpublicfile\fR 15
X\fIPublicfile\fR is the path of a public state file.
X.IP \fB-p\fR 15
XPrevents use of a public state file.
X.IP \fB-S\fIstatefile\fR 15
X\fIStatefile\fR is the path of a private state file.
X.IP \fB-s\fR 15
XPrevents use of a private state file.
X.IP \fB-B\fIhangbelow\fR 15
X\fIHangbelow\fR is the junction of public and private
Xstates,
Xspecified as a node in the public state.
X.IP \fB-b\fR 15
XUnsets \fIhangbelow\fR.
X.IP \fB-I\fIinitialscriptfile\fR 15
XThe path of an initial script file.
X.IP \fB-i\fR 15
XUnsets the initial script file option.
X.IP \fB-W\fR 15
XTurns on privileged access.
X(\fBW\fR stands for \fIwizard\fR.)
X.IP \fB-w\fR 15
XTurns off privileged access.
X.IP \fIinitHypeArg\fR 15
XThe first argument which is not one of the known options
X(above)
Xis passed to the object tree as the parameter to the
Xstart-up message
X.nh
X\fBinitHype\fR.
X.hy
X.RE
SHAR_EOF
if test 3957 -ne "`wc -c < 'startup'`"
then
echo shar: error transmitting "'startup'" '(should have been 3957 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'title'" '(200 characters)'
if test -f 'title'
then
echo shar: will not over-write existing file "'title'"
else
sed 's/^ X//' << \SHAR_EOF > 'title'
X.TL
X.LG
X.LG
X.LG
XHype: A Programmer's Guide
X.NL
X.sp 3
X.AU
X.LG
X.LG
XMartin Smith
XKim Dill
XTerri Fischer
XRob Read
X
XJanuary 10, 1989
X.NL
X.PP
X
X
X.ds LH Hype Programmer's Guide \(em Version 1.2
X.ds CH
X.ds CF
SHAR_EOF
if test 200 -ne "`wc -c < 'title'`"
then
echo shar: error transmitting "'title'" '(should have been 200 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'tree'" '(7940 characters)'
if test -f 'tree'
then
echo shar: will not over-write existing file "'tree'"
else
sed 's/^ X//' << \SHAR_EOF > 'tree'
X.ds RH Objects, Panes, and Items
X.bp
X.SH
X.LG
X.LG
XObjects, Panes, and Items
X.Xs "Objects, Panes, and Items"
X.SM
X.SM
X.PP
X\fBHype\fR supports a tree-structured hierarchy
Xof \fIobjects\fR.
XAn object contains zero or more \fIpanes\fR.
XA pane is a visual sub-region of an object and may contain
Xone or more \fIitems\fR (widgets),
Xthrough which a user may interact with \fBhype\fR.
XA \fItemplate\fR is a pattern on which widgets are arranged;
Xwhen a template is added to an object for display it becomes a pane.
XThe class of objects, panes, items, and templates are
X\fBhype\fR's \fIentities\fR.
X.NH 0
X.LG
XObjects
X.Xn Objects
X.SM
X.PP
X\fIObjects\fR are the entities at the nodes of
Xa \fBhype\fR tree and are its fundamental
Xstructural components.
XAn object is a viewable entity
Xand may be opened (visible) or closed (invisible).
X(\fIClosed\fR, here, is different from the iconic state
Xcalled \fIclosed\fR in Sunview.)
XObjects hold the panes and items through which
Xusers interact with the system.
X.PP
XAn object has a name,
Xa label,
Xand a color.
XIt may own panes, templates,
Xand other objects.
XObjects other than the root object are always owned by other objects.
XAn object may have a script
Xand thus may respond to messages.
X.NH
X.LG
XPanes and Templates
X.Xn "Panes and Templates"
X.SM
X.PP
XA \fIpane\fR is the visual
Xinstantiation of a \fItemplate\fR.
XThis distinction is only significant
Xduring programming:
Xtemplates are manipulated during programming;
Xpanes are interacted with during execution.
X.PP
XA pane has a name
X(which is the same as the name of the template
Xfrom which the pane is constructed)
Xand
Xa color
X(although the Sunview implementation of \fBhype\fR
Xdoes not support pane colors).
XIt does not have a label.
XIt may have background text,
Xwhich appears on the pane but cannot be altered
Xother than through script action,
Xand it may have a script.
XIt may own items.
XIt is owned by an object.
X.NH
X.LG
XItems
X.Xn Items
X.SM
X.PP
X\fIItems\fR
Xare the fundamental interactive entities of \fBhype\fR.
XItems are sometimes called \fIwidgets\fR.
XThe \fItypes\fR of items currently supported are:
X.RS
X.IP \fBbutton\fR 10
Xa place to click
X.IP \fBtext\fR 10
Xa field that can be typed into
X(such as the name of a file) or clicked
X.IP \fBslider\fR 10
Xa "thermometer bar" that can be set or clicked
X.IP \fBtoggle\fR 10
Xa list of labels that can be individually selected
X.IP "\fBtext sub-window\fR" 10
Xa multiline text field that can be edited or clicked
X.RE
X.LP
XThis list will be extended
Xas time allows.
X.PP
XEvery item has a \fItype\fR
X(one of the above),
Xa name,
Xand a label.
XIt also has seven additional variables,
Xenumerated below,
Xwhich contain additional information about the item
Xsuch as the current value of a slider bar
Xor the contents of a text field.
XA particular item type may use certain of these variables
Xin a fixed way, for example
Xa slider bar uses the \fImin\fR and \fImax\fR variables
Xto set the bar's endpoints.
XValues may be assigned to most of these variables
Xduring programming through the \fBitem \fBinfo\fR menu.
X.PP
XAny variable which is not used in a specified way
Xby a particular item
Xmay be used for general purpose storage,
Xthus since a button does not require the
X.I max
Xvariable, a button can store whatever it wishes into
X.I max
Xwith no ill effects.
XThe contents of these variables are static
Xbetween script invocations and are also stored
Xin the \fBhype\fR state file;
Xthus they are static across invocations of \fBhype\fR itself.
XThis is, at present,
Xthe only static storage mechanism available in hype.
X.LP
XThe item variables,
Xand their nominal functions,
Xare:
X.RS
X.IP \fBdefault\fR 10
Xthe default value of a text, text sub-window,
Xtoggle or slider item.
X.IP \fBchoices\fR 10
Xthe list of labels in a toggle.
X.IP \fBmin\fR 10
Xthe minimum value of a slider.
X.IP \fBmax\fR 10
Xthe maximum value of a slider.
X.IP \fBform\fR 10
Xfor \fIformat\fR.
XHas no fixed usage.
XIntended application is to specify the format
Xan item uses in responding to the user defined message \fIthyValue\fR.
X.IP \fBlength\fR 10
Xthe length of a text item in characters
Xor the length of a slider bar in pixels.
X.IP \fBval\fR 10
Xthe current value of a text, text sub-window,
Xtoggle or slider item.
X.RE
X.LP
XSee also the section on Item Info Boxes.
X.PP
X.B "Note: "
XA \fItoggle\fR's choices take the form
Xof a list of words separated by white space.
XEach word becomes a toggle field
Xso, at present, there can be no white space
Xin an individual field's label.
XThe current and default values of a toggle
Xconsists of a list of white-space separated
X\fB1\fR's and \fB0\fR's
Xfor selected and not-selected respectively.
X.NH
X.LG
XNaming Entities
X.Xn "Naming Entities"
X.SM
X.PP
XEach entity in \fBhype\fR has a \fIname\fR
Xwhich is distinct from, but often the same as,
Xthe entity's visible
X.I label .
X\fBHype\fR names are reminiscent of
X.UX
Xfile names,
Xconsisting of a \fIpath\fR part and an \fIentity\fR part.
XThe path part can be either
X.I absolute :
Xstarting from the top or \fIroot\fR of the tree,
Xor
X.I relative :
Xstarting from the context of the current object.
X.PP
X\fBHype\fR's naming conventions differ from file system conventions
Xin several important ways:
X.PP
XFirst,
Xthe syntax is more complicated.
XThe separator "/" is used before an \fIobject\fR;
Xthe separator "!" is used before a \fIpane\fR;
Xthe separator "#" is used before an \fIitem\fR.
XFor example,
X.DS
X\fB/Heaven/Hell/TRC\fR
X.DE
Xis the absolute path name for the object \fBTRC\fR
Xwhich is a child of \fBHell\fR.
X.DS
X\fB/Heaven/Hell/TRC!Ecstasy\fR
X.DE
Xis the absolute path name of the \fIpane\fR \fBEcstasy\fR
Xwhich belongs to the \fIobject\fR \fBTRC\fR.
X.DS
X\fB/Heaven/Hell/TRC!Ecstasy#Despair\fR
X.DE
Xis the absolute path name of the \fIitem\fR \fBDespair\fR
Xwhich belongs to the \fIpane\fR \fBEcstasy\fR.
XIf the current context were \fBHell\fR
X(as would be the case if an object script associated
Xwith \fBHell\fR were executing)
Xwe could interrogate the current value of \fBDespair\fR
Xby either
X.DS
X\fBgetitemval("/Heaven/Hell/TRC!Ecstasy#Despair")\fR
X.DE
Xor
X.DS
X\fBgetitemval("TRC!Ecstasy#Despair")\fR
X.DE
X.PP
XSecond,
Xthe root object of a \fBhype\fR tree has an explicit name
X(while the root of a file system is just "/").
XIn the above example,
Xwe would refer to the root object as
X.DS
X\fB/Heaven\fR
X.DE
Xor, if we are in \fBHell\fR, as
X.DS
X\fB ..\fR
X.DE
X(that's dot-dot) meaning, of course, the parent of the current object.
X.PP
XThird,
X\fBHype\fR supports an entity \fInumbering\fR convention.
XIf, for example, the pane \fBEcstasy\fR has six items,
Xwe may refer to them without knowing their true names.
XSpecifically,
Xthe enumerated path names are
X.DS
X\fBTRC!Ecstasy#0\fR \fIthrough\fB \fBTRC!Ecstasy#5\fR
X.DE
XThis (bizarre) convention makes it possible to interrogate
Xall of the sub-entities of an entity without having to know
Xin advance their true names
Xor how many there are,
Xsince there are
Xstandard
X.B hype
Xlibrary calls to gather that information.
XThis convention has the side-effect that
X.B "no hype name can start with a numeral" .
X.NH
X.LG
XThe Hype Tree
X.Xn "The Hype Tree"
X.SM
X.PP
XThe multitude of types, attributes, and relations in
X.B hype
Xcan be bewildering.
XWe offer here a reasonably unified and coherent
Xway to picture the structure of a given application.
XThis scheme is based on an analogy with the
X.UX
Xfile system tree.
X.PP
XFigure 1
Xdepicts an imaginary
X.B hype
Xstate as a hierarchical tree.
XIn this tree,
Xobjects, panes, and items act as directory files do in the file system.
XEvery directory entry
X(or \fBhype\fR entity)
Xcontains at least an
X.I info
Xentry.
XThis corresponds to the set of attributes
Xestablished for the owning entity during programming.
XEvery directory entry
X.I may
Xcontain a
X.I script
Xentry.
XThis corresponds to the script for the owning entity.
X.PP
XAn \fBitem\fR
Xcannot own any other entities.
XA \fBpane\fR
Xmay own items.
XAn \fBobject\fR may own panes or other objects.
X.bp
X.SH
XFIG 1
X.Xs " Fig. 1. A Hype Tree"
X.LP
XReplace this page with Figure 1.
SHAR_EOF
if test 7940 -ne "`wc -c < 'tree'`"
then
echo shar: error transmitting "'tree'" '(should have been 7940 characters)'
fi
fi # end of overwriting check
echo shar: done with directory "'Guide'"
cd ..
# End of shell archive
exit 0