💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Hypercard › HyperTalk.stuff ›… captured on 2023-01-29 at 08:18:59.
View Raw
More Information
-=-=-=-=-=-=-
For those who will be porting or moving a Mac HyperCard
stack or rather converting it to a HyperCard IIgs stack
the information presented in this file is virtually an
essential reference to have on hand when making such a
HyperCard conversion from the Mac to the IIgs.
This text file conversion of HyperCard HyperTalk
was derived from a Mac DA reference bundle of the same name.
While this file reviews HyperTalk as used with the
Mac Hypercard application program, it still has a great
deal of helpful reference, insight and information for HyperTalk
which is the same scripting language used to create HyperCard
IIgs v1.1 stacks.
Use, Make, Move and Enjoy!
The MacProber
--------------------------------------------------------------------
non-obvious features, behaviours, and shortcuts...
�
Objects and Tools
-TAB-(TAB)-(TAB) for browse/btn/fld tool
-SH-TAB from background layer for browse tool & card layer
-OPT to show visible buttons
-OPT-SH to show visible buttons and fields
--> won't work if the stack is protected with CantPeek = true
-OPT-SH-CLICK on button/field to show script
-CLICK on UNLOCKED FLD to send mouseDown (also copies word to Msg)
OPT-TAB to toggle visibility of tools palette
WHEN USING FIELD/BUTTON TOOL:
-DRAG to create new
(SH)-OPT-DRAG to clone (constrained) [without contents!]
SH-DRAG, SH-RESIZE to constrain
--> SH-RESIZE a round-rect, default, standard, or pop-up button gives it
standard height SH-DOUBLE-CLICK to show script
DOUBLE-CLICK to show info dialog
-T to show font/style dialog
-OPT to show all (even hidden!); and CLICK then shows script
Notes:
Buttons in the background can see thru the cd pict
A field is "list" style if LockText and AutoSelect are both true
A bg fld shows / allows editing of text entered in background if
SharedText is true, and shows/ allows editing of text entered in card
if SharedText is false
�
Navigation and Screen
FIELDS:
TAB to go next fld (or RETURN in last line of fld if it is AutoTab)
SH-TAB to go prev fld
"next" means with next higher number (closer), of same layer (cd/bg), if
there is one; or, if not, field 1 (farthest) of other layer, if there
is one; or, if not, field 1 of same layer
ENTER to leave fld
WINDOWS:
-L to cycle thru windows
-SH-L to cycle backwards thru windows
-SH-E to give card window a resize box
and allow grabber scrolling (hold to maintain)
DBL-CLICK in SCROLL palette to zoom & center
MENUBAR:
-SPACE to toggle menubar
GO:
LEFT-ARROW = prev card
RT-ARROW = next card
-LEFT-ARROW = first card
-RT-ARROW = last card
~ (or ESC) = go back to previously viewed cd (-~ if in paint mode)
SH-ESC = go back without closing
DOWN-ARROW = go back through recently seen cards
UP-ARROW = go forth through recently seen cards
-DOWN-ARROW to push card
-UP-ARROW to pop card
--> OPTION-ARROW accesses arrow-navigation between cards when the
insertion point is in text if the TextArrows is true
FIND:
RETURN after FIND starts find after this instance
-SH-F to find as find whole
--> FIND finds first card containing words starting with all find-words.
It's fastest if all find-words are multiples of three letters in
length. FIND WHOLE finds first card containing all exact find-words in
same field in same order.
�
Text
MSG:
-CLICK or -DRAG in fld (locked or unlocked) to copy word(s) into msg
UP-ARROW to start of msg
DOWN-ARROW to end of msg
-A to select whole msg (but you have to be already in the msg box;
there is still no keyboard command to put the insertion point into the
msg box if it is already showing, you have to use the mouse. Grrrrr.)
FONTS/STYLE shortcuts in fields (all -SH):
P = plain, B = bold, I = italic, U = underline
O = outline, S = shadow, C = condense, X = extend
G = group; ] = next font, [ = prev font
< and > = change font size, - and + = change line space
-A to select all
-SH-Z to revert field
-SH-D to remove styling (default)
�
Menus
ABOUT: OPT-ABOUT for system info
(seems no longer to work in 2.2)
NEW: SH-NEW for new in new window
OPEN: -SH-O or SH-OPEN to open in new window
COMPACT: -OPT-COMPACT to rebuild font table
PROTECT STACK: -choose FILE menu to override low userlevel
PRINT: SH-PRINT for full dialogs
UNDO: just ~ or ESC if in paint mode
PASTE:
-SH-V FIELD/BUTTON pastes field/button with its contents
-SH-V CARD pastes mini-picture of card
(if saved with OPT-COPY CARD, pastes full pict of card)
DELETE CARD: -DELETE
CLOSER/FARTHER: -SH-PLUS/MINUS to move fully
�
Painting
~ (or ESC) to undo
hold OPT-D to show just cd pict
hold OPT-O to show just opaque objects
TAB to toggle visibility of patterns palette
SH-TAB to create new patterns palette
when paint tool selected, menus import/export paint appear
TOOL | |SH |OPT |DBL-CLICK |
select |snap-to | |lasso |all |
lasso |all | |no snap |all indiv |
pencil |fatbits |constrain| |fatbits |
brush |erase | | |brushes |
eraser |white |constrain| |all |
line | |const 15�|pattern |thickness |
spray |erase | |constrain | |
bucket | | | |patterns |
text | | | |font/style|
rect |move |square |border pat|fill |
oval |move |circle |border pat|fill |
reg poly|move |const 15�|border pat|#sides |
poly | |const 15�|border pat|fill |
curve | | |border pat|fill |
patterns| | | |edit |
SH-DRAG selection to constrain movement
OPT-DRAG selection to clone
-OPT-DRAG selection to trail copies (frequ: OPT-1 thru -9)
OPT-1 thru -9 before drawing multiple for spacing
-S after typing paint text to select paint text
OPT-DRAG in FATBITS for grabber
OPT-F in FATBITS to leave fatbits
POWERKEYS:
Select tool; select All; toggle Grid, Centered, Multiple
Opaque; Transparent; Invert; Fill; Darken; Lighten
Black pattern; White pattern; trace Edges; Pickup
[ = rotate left; ] = rotate right; flip Vertical; flip Horizontal
1-8 = line width
Revert
�
Icon Editor
TOOLS: OPT for grabber; for select; OPT-drag clones selection
MENUS: -OPT-V pastes picture instead of whole icon
POWERKEYS:
flip Horizontal; flip Vertical; Mirror horizontal; X = mirror vertical
[ = rotate left; ] = rotate right
Gray; Invert; Shadow; Frame; Opaque selection; Transparent selection
Erase all; Revert
ARROWKEYS:
LEFT-ARROW = prev icon
RT-ARROW = next icon
-LEFT-ARROW = first icon
-RT-ARROW = last icon
�
Reports
DBL-CLICK a CELL to specify report items
IN CELL:
-DRAG to create new item
OPT-DRAG to clone
DBL-CLICK an ITEM to specify that item
-DRAG an ITEM to move/resize precisely
--> note that a text string or HT expression can be its "contents"
--> when the Reports menu is showing you can cut/copy/paste a template
�
Home Stack Handlers
--> you can type these shortcuts into the Msg box
HELP <TOPIC> for hypercard help
HYPERTALK <TOPIC> for hypertalk help
NAV to show navigator palette
VW for variable watcher
MW for message watcher
SE to change script editor defaults
C for card info
B for background info
S for stack info
SS <STR>,<STACKNAME> to seek string in scripts
XY to show mouse coordinates
�
Scripting and Debugging
-OPT-C/B/S to open cd/bg/stack script
(again, to bring to front or close)
-OPT-SH-CLICK on object to open object script
DBL-CLICK " or ( to select text between
TRIPLE-CLICK to select line
OPT-RETURN for soft return
TAB to format
ENTER to close script and save
-. to close script and don't save
-OPT-CLICK IN SCRIPT to close
OPT-CLICK IN CLOSE BOX to close all
OPT-CLICK IN SCRIPT to set/kill checkpoint
OPT-SH-CLICK ON CHECKPOINT to kill all checkpoints
type Debug Checkpoint to set permanent checkpoint
-OPT-. to start debugging
rects in lines of global var ScriptWindowRects determine script window placement
�
Miscellaneous Tips
�Any stack can be "Home": rename or hide "Home", HC will then ask for
"Home" on startup and you can designate any stack.
�When you save as a stand-alone app, the app itself is Home; "go home"
will go to it (but "go stack "Home"" will not), and stacks in use
precede in hierarchy. Default global properties are used, some menus
(including Print) are missing, top level is 4, cantPeek is true.
�Padlock icon in the menu bar? You've got a locked stack. This might be
because: stack was created by earlier version of HC (see if you can
choose "Convert Stack" from the File menu); stack is locked in the
Finder (fix in the Finder); stack is protected (see next item).
�Can't "set the userlevel to 5"? Can't delete stack? Can't peek at
buttons and fields? Padlock? You've got a protected stack. See if you
can choose "Protect Stack" from the File menu. If not, hold and try
it again.
�Periodic cleanup is up to you: Compact your stack; clean the search
paths in the Home stack.
Hidden Hypercard Features
MESSAGES
--> the message hierarchy, and what messages HC sends...
A little terminology: A message can be sent (i) by HC in response to
events ("system" message), or (ii) by a script ("handler" message), or
(iii) from the Message box ("msg" message). A handler message or a msg
message can be made up ("user-defined") or within HC's own known
vocabulary ("pre-defined"); all system messages are pre-defined. A
pre-defined message can be "informational" (it is sent purely to let
handlers know what is happening) or a "command" (HC has a built-in
action response to it). Command messages are marked * below; consult
chapter "Commands" to find out what HC's built-in response is.
�
First Target
The first place a system message is sent (by HyperCard) depends upon
what the message is; it is always a button, field, or card (as
described below).
The first place a message from within a handler is sent is the object
containing the handler -- unless the message is sent with the "send"
command, in which case, you can have it start at any object in the
current stack, or the stack script of another stack. You can also
"send" a message direct "to HyperCard", bypassing the Hierarchy.
The first place message from the message box is sent is the current
card -- unless the message is sent with the "send" command, in which
case, you can have it start at any object in the current stack, or the
stack script of another stack. You can also "send" a message direct "to
HyperCard", bypassing the Hierarchy.
�
The Hierarchy
Static Path:
This is the normal order in which HC seeks a handler for a message or
function call; it runs along this hierarchy looking for a handler, and
stops when it finds one or continues if it finds one and is told to
"pass" the message.
button/field
(Only certain system messages come here: mouse events on a button/field;
messages with Button or Field in the name; and KeyDown, CommandKeyDown,
and TabKey are sent to a field with the insertion point.)
current card
(The recipient for all other system messages.)
current background
current stack
current stack XCMDs
most recently added "start using" stack
most recently added "start using" stack XCMDs
...
first added "start using" stack
first added "start using" stack XCMDs
Home stack
Home stack XCMDs
HyperCard XCMDs
System XCMDs
HyperCard
(At this point, if it's a pre-defined informational message, HC does
nothing; if it's a pre-defined command, HC obeys it; otherwise [ie if
it's a user-defined message], HC complains.)
Dynamic Path:
When HC is executing a handler not on the static path of the current
card, and if a message gets through the first stack level (including
XCMDs) without being handled (or is handled there but "pass"ed), the
"dynamic path" may be invoked, meaning that HC tries again, routing the
message from the bottom of the other hierarchy. (Caution! The HyperTalk
Reference stack states that a message must pass unhandled all the way
to HyperCard before the dynamic path is invoked. This is not true!) The
rule for whether the dynamic path is invoked has to do with whether two
different stacks are involved. If two different stacks are involved,
the dynamic path is invoked either if the first path reaches the stack
unhandled or if the first path is "pass"ed. If only one stack is
involved, the dynamic path is invoked only if the first path reaches
the stack totally unhandled. Here are examples.
Send:
(1) A button has a mouseUp handler 'send "MyMessage" to stack
"OtherStack"'. Here is the hierarchy, whether the message is unhandled
or it is handled but "pass"ed:
other stack
other stack XCMDs
original card
original background
original stack
original stack XCMDs
(etc.)
(2) A button on cd 1 has a mouseUp handler 'send "MyMessage" to cd 2'.
Now things are different from situation (1). If MyMessage is handled at
all, including if it is "pass"ed, on cd 2, or its background, or its
stack (or stack XCMDs), the message just stops or else continues on the
static path. If no handler for it at all is present in any of those
places, it is sent to cd 1 (and then on up from there).
Go:
(1) A button has a mouseUp Handler 'go stack "OtherStack" / MyMessage'.
Here is the hierarchy, whether the message is unhandled or it is
handled but "pass"ed:
original button
original card
original background
original stack
original stack XCMDs
other stack's card
other stack's background
other stack
other stack XCMDs
(etc.)
(2) A button on cd 1 has a mouseUp Handler 'go cd 2 / MyMessage'. Now
things are different from situation (1). If MyMessage is handled at
all, including if it is "pass"ed, on the button, or cd 1, or its
background, or its stack (or stack XCMDs), the message just stops or
else continues on the static path. If no handler for it at all is
present in any of those places, it is sent to cd 2 (and then on up from
there).
�
Button Messages
newButton sent on creation; the button has no script (unless pasted)
deleteButton sent just before the button vanishes
mouseEnter, mouseWithin (sent repeatedly), mouseLeave. With an Oval
button, the "boundary" is the oval.
mouseDown, mouseStillDown (sent repeatedly), mouseUp; mouseDoubleClick
which is sent only after the three messages for the first click have
been sent, and if handlers for these involve dialogs ("answer" etc.)
the MouseDoubleClick is never sent. With a Popup button, no
MouseDoubleClick is sent, no MouseStillDown message is sent, and
MouseUp is sent only if the mouse is released with the "menu". With an
Oval button, the "boundary" is the oval. None of these messages is sent
if the mouse is over a disabled button.
�
Field Messages
newField sent on creation; the field has no script (unless pasted)
deleteField sent just before the field vanishes
mouseEnter, mouseWithin (sent repeatedly), mouseLeave
mouseDown, mouseStillDown (sent repeatedly), mouseUp; mouseDoubleClick
-- all sent only to locked fields, except that MouseDown can be sent to
an unlocked field by -clicking. MouseDoubleClick is sent only after
the three messages for the first click have been sent, and if handlers
for these involve dialogs ("answer" etc.) the MouseDoubleClick is never
sent
openField sent to unlocked field when insertion point comes to be in it
by mouseclick or tabkey, but not by HyperTalk e.g. "select text of..."
exitField sent when user leaves field if no text was changed
closeField sent when user leaves field if text was changed
- keyDown, *commandKeyDown
- tabKey, *enterInField, *returnInField -- a KeyDown is sent before each.
After a ReturnInField a TabKey will be sent if not intercepted and the
insertion point is on the last line of a non-scrolling AutoKey field.
After an EnterInField or TabKey the field will be closed and ExitField
or CloseField will be sent; in the case of TabKey, the same or another
field will then have its text selected, and OpenField will be sent.
�
Card Messages
These twelve are shown in the order of sending (whichever are appropriate):
closeCard, closeBackground, closeStack
deleteCard, deleteBackground, deleteStack but if you are deleting a
stack, DeleteCard and DeleteBackground are not sent
newStack, newBackground, newCard
openStack, openBackground, openCard
startUp sent to first cd to be shown, but before it actually appears
(before all Open... messages). Note that the Home stack performs some
valuable tasks on StartUp (setting userLevel, fetching search paths,
etc.) so it may be useful to Pass StartUp.
quit sent after all Close... messages
moveWindow sent when the card window is moved by user or handler
sizeWindow sent when the card window is resized by user or handler
close sent before all Close... messages when closing this stack's card
window, by user clicking in close box or by handler (but not when Close
is chosen from the File menu); the window will not be closed unless the
message reaches HyperCard. This is a subset of "close" messages
generally, so you need to check the parameter to see if it is "card
window"
suspendStack sent when moving this stack's card window back from the
front (even if screen is locked); no Close... messages are sent
resumeStack sent when bringing this stack's card window to front from
behind (even if screen is locked); no Open... messages are sent
mouseDown, mouseStillDown (sent repeatedly), mouseUp; mouseDoubleClick
which is sent only after the three messages for the first click have
been sent, and if handlers for these involve dialogs ("answer" etc.)
the MouseDoubleClick is never sent
- keyDown, *commandKeyDown -- when it receives a commandKeyDown message,
HC searches its menuItems for a visible, non-deleted equivalent, top to
bottom starting with the rightmost menu; if it finds one it sends a
doMenu, if not it beeps *tabKey, *enterKey, *returnKey, *controlKey,
- arrowKey, *functionKey -- a KeyDown is sent before each. If the
insertion point is in a field, EnterKey and ReturnKey are not sent
(EnterInField and ReturnInField are sent instead); the prior KeyDown
goes to the field, and so does TabKey, but ControlKey, FunctionKey and
ArrowKey are sent to the card, bypassing the field. If F1, F2, F3, or
F4 is pressed and FunctionKey reaches HyperCard, the effect will be the
sending of a DoMenu message for Undo, Cut, Copy, Paste respectively.
- doMenu sent when a menu item is chosen, via mouse or command key (in
the latter case a CommandKeyDown will have preceded). The menu item
will not be responded to unless the DoMenu message reaches HyperCard.
If a menuItem with a menuMessage was chosen, that menuMessage will then
be sent. Some of HC's menu items also have menuMessages which are then
sent, and nothing will happen unless those messages reach HyperCard,
namely: *help sent by the Help menu item *choose sent by any item in
the Tools menu (including -TAB(-TAB-TAB) key shortcuts, which send
CommandKeyDown first)
- show menubar, *hide menubar sent as a result of pressing -space (a
CommandKeyDown precedes); the menubar will not be affected unless the
message reaches HyperCard. These are special cases of the show/hide
commands, so the parameter must be checked to see if it is menubar if
you want to intervene
errorDialog sent if the LockErrorDialogs is true and an error occurs to
which HyperCard would otherwise have responded with a dialog box
appleEvent sent if an Apple Event arrives; the event will not be
executed unless it reaches HyperCard
openPalette, openPicture; mouseDownInPicture, mouseUpInPicture;
closePalette, closePicture (all products of the included Picture and
Palette XCMDs) -- ClosePalette and ClosePicture are sent as byproducts
when the user clicks in the close box, just before the window
disappears (you can handle but not prevent the closing); if a handler
closes with "close window...", though, only Close is sent
idle sent repeatedly when Browse tool is current and no handler is
executing
[resume, suspend sent under System 6 Finder (not MultiFinder) on launch
or and return from another app. Under MultiFinder and System 7, no
message is sent in such cases, nor when the user switches apps; if your
stack needs to know whether HyperCard is backgrounded it can check the
Suspended property in an Idle handler.]
�
Message Parameters
Your messages can include parameters by using the syntax "MyMessage
parameter[,parameter...]" (for a handler message) or
"MyFunction(parameter[,parameter...])" (for a function).
Your handler can receive parameters by starting with syntax "on
MessageName var1[,var2...]", "function FuncName var1[,var2...]". (The
variable names are local and can be anything you like.) Or, you can use
the various Param functions.
Some system messages include parameters, as follows:
errorDialog TextThatWouldHaveAppearedInDialog
appleEvent Class,ID,Sender
doMenu MenuItem,MenuName
show/hide "Menubar"OrWhatever
close "card window"OrWhatever
choose "tool",ToolNumber
open/close-Palette/Picture WindowName,WindowID
mouseDownInPicture / mouseUpInPicture WindowName,Point
arrowKey "left"|"right"|"up"|"down"
keyDown KeyLetter
commandKeyDown KeyLetter
functionKey KeyNumber (1-15)
controlKey KeyNumber 1-127 according to the following mapping, showing
key(s) typed with the controlKey down and the KeyNumber code generated:
a/Home=1; b=2; c/Enter=3; d/End=4; e/Help=5; f=6; g=7; h/Delete=8;
i/Tab=9; j=10; k/PageUp=11; l/PageDown=12; m/Return=13; n=14; o=15;
p/Function=16; q=17; r=18; s=19; t=20; u=21; v=22; w=23; x=24; y=25;
z=26; Esc/Clear/"["=27; LeftArrow/"\"=28; RightArrow/"]"=29;
UpArrow=30; DownArrow/"-"=31; '=39; *=42; +=43; ","=44; "-"=45; "."=46;
"/"=47; 0=48; 1=49; 2=50; 3=51; 4=52; 5=53; 6=54; 7=55; 8=56; 9=57;
";"=59; "="=61; ~=96; ForwardDelete=127
RESERVED SIGNS
--> invariable, reserved terms and signs...
�
Keywords
Keywords are reserved words (they cannot be used as variables, and they
are not trappable messages or commands) defining the structure and flow
of handlers. They are:
on messageName [param[,param2...]]
function messageName [param[,param2...]]
end messageName
pass messageName -- must be the same as the on/function messageName; all
incoming parameters will automatically be passed on; execution of the
handler will cease here, but the structure must still be completed with
an end return value -- if a function, the value will be substituted in
the calling line; if a handler, the value will go into the Result;
execution of the handler will cease here, but the structure must still
be completed with an end
exit messageName | to HyperCard -- execution of the handler (or, if "to
HyperCard", all handlers) will cease here, but the structure must still
be completed with an end
global var[,var2...]
repeat forever
numberOfTimes
until condition
while condition
with var = startNum [down] to endNum
exit repeat
next repeat
end repeat
if ... then ... [else ...]
if ...
then ...
[else ...]
if ... then
...
[else
...]
end if
send messageString to HyperCard | objectInThisStack | stack
otherStackName -- see Messages for more info. send also has two other
uses: (1) for sending a 'dosc' AppleEvent to another program and (2)
for running an object script written in another scripting dialect; see
Communication for more info.
do expression -- expression can be a string construction, to force
evaluation of the whole string before its execution; this is a way to
get multiple lines, or special punctuation, into a single line. Or it
can be a container, in which case the whole container is executed, line
by line. [A bug in earlier versions prevented this second use (you
could only "do" a line at a time), but this is now fixed.] do also has
another use, for running an expression or contatiner contents written
in another scripting dialect; see Communication for more info.
�
Operators
Operators are reserved symbols and words used for combining "factors"
into "expressions". They are given here in order of precedence; there
are ten levels, and those on the same level are evaluated right to
left. Parenthesised expressions are evaluated from inmost outwards.
()
- [negative number] not there is {[not] a[n]} | no
^
+ -
& &&
< > <= � >= � contains is [not] a[n] | in | within
= is is not <> �
and
or
Notes: "within" is for rects, "in" is for strings. "There is" can be
followed by cd pict, bg pict, or any of the following (plus a further
specifier): scriptingLanguage, program [ID], disk, folder, application,
document, file, stack, menu, menuItem, window, cd, bg, fld, btn, part.
("Program" means a currently running program.) "Is a" can be followed
by number, integer, point, rect, date, logical.
�
Constants
Constants are reserved words standing in the same syntax as variables,
except that they cannot have anything put into them; they have
pre-defined literal values.
colon comma space tab return quote empty
true false up down
eof formfeed linefeed
pi zero..ten
�
Objects and Chunks
These are terms for referring to objects and parts of objects and containers.
stack bg cd part fld btn
me -- reference to the object containing the currently executing
handler; with select and a field you may need to use text of me to
distinguish the contents from the field itself
the target -- also, the long target, the short target. Reference to the
object to which the current message was originally sent; for the
format, see chapter "Properties II" under "Name" of object-type. Under
some circumstances with a button or field you may need to use target
(without "the") to mean the contents.
the result -- returned by "return" in a message handler, or with an
error-message if certain operations fail (so that checking "the result
is empty" can indicate success), or can be set by an XCMD; reset to
"empty" after the next command executes, so check it first thing
it
char word item line
any first last middle second third fourth fifth sixth seventh eighth ninth tenth
next prev this
id
msg
Reserved Signs
GLOBALS
HC maintains in global variables certain information from which it
derives some default behaviours. It is possible to access or create
these variables and alter these defaults. They are very poorly
documented, so it may well be that there are others I have not been
able to discover yet.
documents, applications, stacks -- set initially in the Startup handler
of the Home stack, using bg fld "Paths" the cards with same names.
These determine the "search paths" whereby HC will look for documents,
applications, and stacks if they are not in the same folder as HC or
the same folder as the current stack. You can reset the globals
yourself, and you must set them in the startup handler of a standalone
if you want it to have such "search paths". scriptFindString,
scriptWholeWord, scriptCaseSens, scriptWrapAround -- these determine
initial settings in the Find dialog of the script editor (and are
subsequently changed when you change those settings). You can set them
yourself (eg in a startup handler) if you don't like those settings and
don't want to be bothered changing them manually the first time the
dialog appears. scriptWindowRects -- each line is a Rect corresponding
to the rect of each successive simultaneous open script window.
Globals
BUILT-IN FUNCTIONS
A built-in function is a calculation on parameters or an
information-fetching routine which is evaluated before the line in
which it appears is acted upon.
If a built-in function takes no parameters or one parameter, you can
call it either with the syntax the funcName or [the] funcName of
theParameter, or with the syntax funcName() or funcName(theParameter).
But if it takes more than one parameter you can only use the second,
()-form, with the parameters separated by commas.
This double syntax leads to a curious phenomenon about the relationship
between your own function handlers and the built-in functions. Your own
functions can only be called with the second, ()-form. Your functions
can also have the same name as a built-in function, and can thus
override a built-in function if encountered in the message hierarchy
before the function call reaches HC. Therefore, if you have such a
handler, the calling syntax builtInFunc() can access it and override
HC's built-in function, but the other calling syntax (if permitted),
the builtInFunc, will bypass your handler and go direct to HC.
�
Mouse
mouse <up | down> -- current
mouseClick <boolean> -- reports whether the mouse has been clicked
(regardless of how many times) since either (i) the start of the
current handler-chain or (ii) the last call to MouseClick within the
current handler-chain. This has the additional (possibly very useful)
consequence that simply calling MouseClick during a handler clears all
clicks from the event chain (ie, they don't generate a mouseUp); mouse
clicks during handlers that are not intercepted in this way do generate
mouseUp (one for the lot of them)
mouseH, mouseV <int>; mouseLoc <pt> -- current
clickH, clickV <int>; clickLoc <pt> -- reports position mouse was most
recently clicked ever (ie, not just within this handler); the click
must be within the card, below the title-bar
�
Field Text
clickChunk, selectedChunk, foundChunk <"char x to y of card|bkgnd field
z"> -- if x > y, insertion pt is after y. ClickChunk refers to the word
(or grouped text) in field where the most recent ever mouse-click was;
if the click was after all text, x = y = the number of chars of the
field + 1
clickText, selectedText, foundText <textString> -- just like using the
Value function on the ...Chunk functions above
clickLine, selectedLine, foundLine <"line x of card|bkgnd field z"> --
ClickLine refers to the line in field where the most recent ever
mouse-click was; SelectedLine refers only to the first line any part of
which is included in the selection
selectedField, foundField <"card|bkgnd field z">
selectedLoc <pt> -- the left bottom (!) of the selected text
NB: these all return Empty if no applicable entity exists. Note that a
number of user actions can cause there to be no selection; a useful
trick, though, is that pushing a button whose AutoHilite is False will
not deselect the selection (though it will lose the Found box).
�
List Fields
A list field is one whose lockText, dontWrap, and autoSelect (and
possibly multipleLines) are true. Clicking (or shift-clicking)
automatically selects whole line(s). Clicking elsewhere does not
deselect. Two Selected... functions are modified to work with list
fields by adding a FieldRef parameter; omitting this parameter reduces
the function to a normal field function, which will not see the
"selection" in the list field:
selectedLine(fieldRef) <"line x to y of card|bkgnd field z">
selectedText(fieldRef) <textString>
The SelectedField does not apply.
�
PopUp Buttons
A popup button has "contents" which determine its menu items. Two
Selected... functions are modified to work with popup buttons by adding
a ButtonRef parameter; omitting this parameter reduces the function to
a field function:
selectedLine(buttonRef) <"line x of card|bkgnd button z">
selectedText(buttonRef) <textString>
�
Radio Buttons
A radio button can be one of a "family", in which case clicking on any
member of that family sets its Hilite to true and that of the family's
other members to false. To determine which of a family is hilited, use:
selectedButton(cd|bg family familyNum) <"card|bkgnd button z">
�
Keys
commandKey, optionKey, shiftKey <up | down>
�
Text
length(string) <integer>
offset(findString,inString) <integer> -- returns 0 if InString doesn't
contain FindString
charToNum(char) <integer> -- ignores all but first char of string param
numToChar(num) <char>
�
Math
random(integer) <integer between 1 and given num>
annuity(rate, numPeriods), compound(rate, numPeriods)
average(comma-list), sum(comma-list)
max(comma-list), min(comma-list)
sin(radians), cos(radians), tan(radians), atan(number) <radians>
sqrt(), trunc(), abs()
round() -- returns nearest integer; if an odd and even integer are
equally distant (ie the parameter has ".5" at the end), returns the
even integer
exp() -- e^x
exp1() -- (e^x)-1
exp2() -- 2^x
ln() -- e^result = x
ln1() -- e^result = x+1
log2() -- 2^result = x
�
Environment
[abbr|long] date <"9/2/94">, <"Wed, 9 Feb 1994">, <"Wednesday, 9
February 1994"> -- the result format depends on itl-resource settings
(note how on my British machine, "9/2" means February 9th, and in the
others the day precedes the month; on American machines the order is
different, and on Swedish machines the comma is not present). Use
convert to get a format from which individual items can be extracted
[long] time <"10:50 AM">, <"10:50:10 AM"> -- again, use convert to get a
reliable format for extracting items or doing calculations
secs -- since 1/1/04 12:00 AM
ticks -- since the last startup/restart; roughly 1/60 sec
sound <"soundName" (or "done" if none playing)
tool <"x tool"> -- x can be browse, button, field, select, brush,
bucket, pencil, lasso, eraser, spray, line, text, oval, rectangle,
round rect, regular polygon, curve, polygon menus <return-list> -- the
list on my computer starts with "Apple" and ends with "System Help",
"Keyboards", "Application" windows <return-list> -- windowNames in
front-to-back order, including invisible windows which themselves
include various palettes and windows belonging to HC itself; the list
on my computer at this moment goes: Message, Message Watcher, Variable
Watcher, Scroll, FatBits, Patterns, Tools, bird (a "picture" window),
HyperTalk Reference (the only open stack), although only the last is
visible stacks <return-list> -- full pathNames for all open stacks in
front-to-back order; an "open" stack need not have its window visible,
but it is not the same as a "start using" stack, for which you need to
check to check the global Property, the StacksInUse (and why "stacks"
is a function but "stacksInUse" is a property is known only to God)
programs <return-list> -- progNames of sys-7-friendly apps running on
the same computer; may include extensions not appearing in the
Application menu programs of machine "zone:machine" <return-list> -- of
AppleEvent-aware apps running on the other computer screenRect <rect>
-- for the monitor displaying the largest proportion of the current
card windows, measured from the top-left of the monitor holding the
menubar diskSpace <#bytes> -- of the disk containing the current stack,
or use diskSpace of disk "diskName" to check any disk (too bad there's
no "disks" function!!!) heapSpace, stackSpace <#bytes> -- HeapSpace is
for general issues of how much free RAM room HC has; StackSpace is not
the normal "stack", but some sort of internal structure, and I'm not
sure what you would learn from checking it systemVersion <#.##> --
"7.10" on my machine
�
Other
destination <pathName> -- usable in handlers for CloseStack,
CloseBackground, CloseCard, and SuspendStack to find out where we'll be
going after this number(<chunks> | <objects>) -- <chunks> must name a
container too, using in|of, and can be chars, words, items, lines,
menuItems; <objects> can be [bg|cd] btns|flds|parts, bgs, cds, marked
cds, cds of <background-specifier>, menus, windows value(<expr>) --
forces extra level of evaluation; usually so you can use the name of a
container and get the contents of that container evaluated, but also
can be used to get quotes off the outside of a literal param(num);
paramCount; params <comma-list> -- used where you don't know how many
parameters to expect. Param(0) is the message (handler name); Params
lists them all, starting with 0.
Built-in Functions
PROPERTIES
--> (For Stack, Background, Card, Field, and Button properties, see
chapter "Properties II")
A property is a category of feature of an object; that is to say, the
value of a property helps to describe the current state of the object,
and each property of each object has a set of possible values, one of
which it has at all times.
The syntax for referring to objects is "[the] propertyName of
objectRef", unless it is a "global" property in which case you just say
"[the] propertyName".
The syntax for changing the value of a property is "set the
propertyName [of objectRef] to newValue". You cannot "put" into a
property (and you cannot "set" a container). -- However, some
properties cannot be "set" at all (they are "read-only"); a couple can
be "set" but can not be read!
A few properties can be set by a shortcut command, eg "lock screen"
instead of "set the lockScreen to true".
A few properties revert to default values "at idle time", ie when all
handlers cease. But be warned: there is a bug (or whatever you like to
call it) so that during a handler if an event occurs (such as a mouse
click) which queues up to trigger another handler, "idle time" will not
come. So don't count on this reversion taking place.
These symbols are used to describe properties in what follows:
� = cannot be set
� = can only be set (no get!)
* = reverts to default at idle time
� = shortcut command equivalent
� = default
�
Global
User Abilities:
blindTyping <boolean> -- can user type into hidden msg? (� from Home
stack), powerKeys <boolean> -- can user employ painting keyboard
shortcuts? (� from Home stack) textArrows <boolean> -- can user employ
arrow keys to move insertion point in a field? (If false, arrow keys
move between cards even if a field is open.) (� from Home stack)
userModify <boolean> -- if stack is write-protected, can user type and
user paint tools anyway? A stack is write-protected if on an unwritable
medium, is finder-locked, or its CantModify is true; the UserModify is
ignored otherwise. Changes are discarded when leaving the card. (� =
false, reverts every time a different stack becomes current) userLevel
<1-5> -- 1 = browsing [restricted File & Edit, Go]; 2 = typing [Font &
Style added]; 3 = painting [unrestricted File & Edit, Tools added]; 4 =
authoring [Objects added]; 5 = scripting [editing scripts]. (� at
startup comes from Home stack; reset every time a different stack
becomes current, by taking the lower of (1) the last "set UserLevel"
call and (2) the Protect Stack dialog setting for the stack; a "set
UserLevel" call higher than the current stack's Protect Stack dialog
setting is remembered but will not be acted upon while in that stack)
Parsing:
*itemDelimiter <char> -- � = comma
Display:
�*cursor <nameOrNum> -- included are: watch=4, busy, hand, arrow,
ibeam=1, cross=2, plus=3, or none; or add your own as a CURS resource
and refer to it by name or number. Successive calls to "busy" rotate
the beachball. *dragSpeed <num> -- bigger is faster (in pixels/sec),
except that 0 (= �) is fastest. Bucket and Text tools are unaffected
longWindowTitles <boolean> -- � = false (stackName vs. pathName). No
window titles will show if you hide them or if the cd window's top is
at the screen's top (as with standard windows on a Classic mac)
editBkgnd <boolean> -- toggling is just like selecting Background from
the Edit menu
Scripting:
scriptTextFont <name> -- � = monaco
scriptTextSize <#points> -- � = 9
traceDelay <ticksToWait> -- � = 0
debugger <name> -- �="ScriptEditor"
scriptEditor <name> -- �="ScriptEditor"
variableWatcher <name> -- �="VariableWatcher"
messageWatcher <name> -- �="MessageWatcher"
Suppression:
- lockScreen <boolean> -- � [un]lock screen. If true, suppresses updating
of card drawing (and saves a mess of time); won't prevent msg or
dialogs appearing. � = false
- lockMessages <boolean> -- � [un]lock messages. If true, suppresses
Open..., Close..., Suspend..., and Resume... system messages. � = false
- lockRecent <boolean> -- � [un]lock recent. If true, suppresses
automatic recording of recent cards; can save a mess of time during
navigation. � = false
- lockErrorDialogs <boolean> -- � [un]lock errorDialogs. If true,
suppresses display of error messages; instead, ErrorDialog message is
sent to current cd. � = false
Output:
- numberFormat <str> -- 0 = must fill; # = may fill; � = "0.######".
What's determined is how results of mathematical operations (not,
strings consisting of digits) should subsequently be rendered as
strings in fields and msg; no internal accuracy (19 digits) is lost!
The Variable Watcher window displays in the default format during idle
time, but full accuracy is still present.
printMargins <rect> -- 72 = 1 inch; � = "0,0,0,0"
printTextAlign <left|center|right> -- � = left
printTextFont <name> -- � = geneva
printTextSize <number> -- � = 10
printTextHeight <#points> -- � = 13
printTextStyle <styleList> -- � = plain
NB: the Print... properties are for outputting variables, and for print
report header text. � reset printing restores the defaults.
dialingVolume <0-7> -- � = 7; 0 is low but not silent
dialingTime <#ticks> -- wait after dialing until closing serial connection; � = 180
Painting:
brush <1-32> -- numbered top-to-bottom, then left-to-right, in the Brush
Shape dialog; � = 7
linesize <1-8> -- (but 5=6 and 7=8); � = 1
pattern <1-40> -- numbered top-to-bottom, then left-to-right, in the
Patterns palette; � = 12
centered, filled, grid, multiple <boolean> -- � = false
multiSpace <1-100> -- number of pixels between multiple images when
Multiple is true; � = 1
polySides <3-50, or 0> -- � = 4. "0" means a circle.
textAlign <"left|center|right"> -- � = "left"
textFont <name> -- � = "geneva"
textSize <num> -- � = 12
textHeight <num> -- � = 16
textStyle <commalist> -- � = "plain"
Note: � reset paint restores the defaults for above painting properties
Environment
:
�stacksInUse <return-list> -- of the "start using" stacks, in
hierarchical order
�suspended <boolean> -- is HC running the background (under MultiFinder
/ system 7)? This is the only way to find out; no message is sent when
HC is backgrounded. Cannot be set, but under system 7 HC can background
or foreground itself via DoMenu
�address <zone:machine:program> -- of HC on the network
�environment <"development|player"> -- meaning either HC, or else HC
Player or a stack saved as an application
�[long] version -- of HC; the Version is the popular version number (eg
"2.2"), but the Long Version returns 4 packed 2-digit numbers (eg
"02208000"): major version, minor version, software state (80 = final,
60=beta, 40=alpha, 20=dev), release number
�ID -- of HC = "WILD", or of a stand-alone whose app signature has been
altered
�name -- of HC = "HyperCard", or of a stand-alone with a different
name. Or you can ask for the long name, which returns the pathname of
HC on disk scriptingLanguage -- in which commands entered in the
Message box will be interpreted; � = "HyperTalk". Be careful; if you
say in the Message box "set the scriptingLanguage to QuicKeys" (for
example) you now cannot say "set the scriptingLanguage to HyperTalk" in
the Message box to get back to normal! (The solution is left as an
exercise for the reader.) language -- for non-English systems (� =
English). If you have a "translator" resource for another language and
set the Language to that language, HyperTalk scripts will appear to be
in that language (but they are still "really" in English).
�
Windows
All Windows:
�name <theName> -- you can refer to the window as "window theName"
�id <theID> -- you can refer to the window as "window id theID"; IDs
are unique and permanent
�number <theNum> -- you can refer to the window as "window theNum";
reflects current front-to-back order (same as which line of Windows()
its name appears in)
�owner <theOwner> -- either "HyperCard" (for a card window and HC's
floating windows) or the name of an XCMD (for an external window) rect
<theRect> -- with respect to the topLeft of the current card, except
that the "rect of cd window" is with respect to 0,0 of the screen
holding the menubar. The Rect does not include any title-bar or
scroll-bars or borders. Aspects of the Rect are also accessible via
left, top, right, bottom, topLeft, botRight, height, width: changing
any of the first six moves the whole window without resizing; changing
the Height or Width leaves the topLeft unchanged. If the Rect cannot be
set, the Height and Width cannot be either, but the others can because
they affect only the Loc. loc <point> -- same as the TopLeft portion of
the Rect visible <boolean> -- � show/hide windowRef
Cd Window:
NB on rect: You can change the Rect of the cd window; this can shrink
the amount of card visible, but you cannot make the Width or Height of
cd window larger than the stack's card size ("the Width|Height of this
cd") -- no error results, but the cd window will simply reach the
card's height/width and no more. A cd window can, however, be smaller
than the stack's card size; viewing of the whole card, piecemeal, is
possible via the Scroll pallette. NB: A cd window larger than the
screen can make it very difficult to view the rest of the card. (See
chapter "Properties II" on the Rect of a card.) scroll <point> -- if
"the Width|Height of cd window" is smaller than "the Width|Height of
this cd", specifies the point of the card which is at the topLeft of
the window. The value of the Scroll in relation to the Rect can never
be such that "blank space" would show to the right or bottom of the
card; trying to set the Scroll such that this would happen will not
result in an error but it will have no effect, and changing the Rect
such that this would happen will automatically cause a change in the
Scroll to compensate. The limiting case is when the cd window is the
same size as the card; in this case the Scroll cannot be altered (from
"0,0"). zoomed <boolean> -- "true" means the window is both at full
size and centered in the screen NB on visible: You can turn a cd window
invisible, but this can have seemingly weird effects; for example, that
window can still be current, will be selected as you cycle through with
Next Window, etc., and other buggy-looking things can occur.
Picture Window:
�pictureWidth, �pictureHeight <numPixels> -- size of original image at
normal size scale <-5...5> -- 0 is normal; -1 is half size, 1 is double
size, etc. (I have not figured out what rule is used for determining
what new value of Scroll is defaulted to when you change Scale.) NB on
rect: Oddly, cannot set �width and �height, although nothing is to stop
you from changing these values by altering the rect. (NB: If window has
a grow box, you can make Rect larger than image size, but the user
cannot: and if the user so much as clicks on the grow box of a window
which is larger than the image size, the window snaps down to the image
size.) globalRect <rect>, globalLoc <point> -- like Rect and Loc, but
the latter measure from the topLeft of the current cd window, whereas
Global... measure from topLeft of the screen holding the menubar. NB --
rect, loc, globalRect, and globalLoc can be set to any of four special
screen constants: card, largest, deepest, main. The picture will be
centered (and, with ...rect, full-zoomed) on the named screen. scroll
<point> -- if the Width or Height of the window is smaller than the
width or height of the picture image at its present scale, specifies
the point of the image which is at the topLeft of the window. (If the
window is the same size or larger than the image, the Scroll is "0,0"
and trying to set it has no effect -- the image will be in the topLeft
corner.) If the image is scaled, "point of the image" means point of
the original image: eg, if the Scale is 1, changing the Scroll from 0,0
to 0,1 moves the image up 2 pixels. zoomed <boolean>, zoom <"in|out">
-- identical: "true"/"out" means the window is both at full size and
centered in the screen; usable only if window is "zoom" style
(otherwise, does nothing and returns empty) dithering <boolean> --
works only if 32-bit QD is present and the picture was created with
bitdepth > 0 �properties NB on visible: No message is sent when the
user clicks a card window that was behind your Picture window; so if
ensuring visibility is important to you, create the window in the
floating layer, or check its Number in an Idle handler. A Picture
window cannot be selected with Next Window. Since the Number cannot be
set, you cannot use it to bring a Picture window of the document layer
to the front; you can accomplish this, however, with show.
Palette Window:
�buttonCount <num>
�commands <return-list> -- the command for button n is on line n
hilitedButton <num> -- hilites that button (without sending its
message); 0 to hilite none; but if it is the kind of palette where the
buttons do not remain hilite, always -1
�properties
cannot set �rect
Variable Watcher:
hBarLoc, vBarLoc <num> -- � = 98, 99 resp.
�properties
you can set �zoomed without error but it remains false
Message Watcher:
hideIdle, hideUnused <boolean> -- � = false, true resp.
text <expr> -- complete text
�nextLine <expr> -- text after current text (useful for debugging)
�properties
cannot set �rect
you can set �zoomed without error but it remains false
Msg:
textFont -- � = geneva
textSize -- � = 12
textStyle -- � = plain
cannot set �rect
you can set �zoomed without error but it remains false
Tool Window, Pattern Window:
cannot set �rect
you can set �zoomed without error but it remains false
�
Menus
Menubar:
�rect; �loc (same as TopLeft)
visible <boolean> -- �show/hide menubar
Menu:
�name <theName> -- you can refer to a menu as "menu theName", or ask for
the long name, which returns a valid menuRef, eg <menu "Style">. You
can't change a menu name, but you can delete and create whole menus.
��number <theNumber> -- you can refer to a menu as "menu theNumber",
where TheNumber reflects the current left-to-right order. Yet,
amazingly, you can neither get nor set Number as a property!!! Hence
you cannot find out the number of a menu known by name without
searching through "the menus". (Grrr.)
�ID -- you can refer to a menu as "menu id theID". A permanent
unchanging designator reflecting HC's and the System's internal
resource numbering. enabled <boolean> -- � disable/enable. You can set
this on any of HC's own menus (whether showing or not), but � not for
the system menus. A disabled menu has all of its items disabled; for
tear-offs, the whole palette is disabled, even though it can be shown.
A script can still make a call to a menuItem which has been disabled by
a script (but not a menuItem which HC itself has disabled).
MenuItem:
NB: basic reference form is: menuitem itemNameOrNum of menu
menuNameOrNum. -- You can set features of most of HC's menus; but � not
for the system menus or for Tools, Patterns, or Font. You cannot get
anything � for menuitems of Tools or Patterns. name <theName> -- You
can use theName for itemNameOrNum in the above reference format, or ask
for the long name, which returns a full valid menuItemRef, eg <menuItem
"New Stack..." of menu "File">. To obtain a whole list of names of the
menuItems of a menu, just use a menuRef (eg <menu "File">); a
return-list is substituted. NB that you can set the name of menuItem 1
of menu 1 ("About..."). � put theName into|after|before menuItemRef.
��number <theNumber> -- you can use theNumber for itemNameOrNum in the
above reference format, where theNumber reflects the current
top-to-bottom order. Yet, amazingly, you can neither get nor set Number
as a property!!! Hence you cannot find out the number of a menuItem
known by name without searching. (Grrr.) menuMsg -- A menuItem that you
create will do nothing unless you either (i) intercept DoMenu, or (ii)
give it a menuMsg, or (iii) give it the same name as a standard HC
menuItem (in which case it will have HC's default behaviour). A menuMsg
can be only one "line", but this is still powerful because this can be
either (a) a message you intercept, or (b) a single script line, or (c)
a multi-line script in a Do statement. HC's menus do not have any
default menuMsg; attaching a menuMsg to one of them overrides its
default behaviour, setting the menuMsg to Empty restores it. NB that
you can set the menuMsg of menuItem 1 of menu 1 ("About..."). -- � You
can add menuMsgs when creating or modifying a menuItem or series of
menuItems as part of the put command. checkMark <boolean> -- whether
the item is "checked" (with a markChar). True if MarkChar is not empty,
and setting to false sets MarkChar to empty. HC maintains meaningful
check-marking in some menus (eg Style) and you won't be able to affect
these (though there is no error if you try). markChar <char> -- the
symbol to be used to "check" the item; NB that giving the MarkChar a
value does in fact check the item (and sets the CheckMark to true), and
making the MarkChar empty unchecks the item (and sets the CheckMark to
false). Setting the checkMark to true sets the markChar to its � =
numToChar(18). HC maintains meaningful check-marking in some menus (eg
Style) and you won't be able to affect these (though there is no error
if you try). enabled <boolean> -- �enable/disable menuItemRef. HC
maintains meaningful enabling in some menus (eg File, Objects) and you
won't be able to affect these (though there is no error if you try). A
script can still make a call to a menuItem which has been disabled by a
script (but not a menuItem which HC itself has disabled). textStyle
<style list> cmdChar <char> -- command-key equivalent. Nothing stops
you from changing any of HC's default command-key equivalents. When it
receives a commandKeyDown message, HC searches its menuItems for an
enabled, non-deleted equivalent, top to bottom starting with the
rightmost menu; if it finds one it sends a doMenu, if not it beeps.
(But -Q always quits.) NB: reset menubar restores all HC's menu
defaults.
Properties
PROPERTIES II
--> (For Global, Window, and Menu properties, see chapter "Properties
I")
A property is a category of feature of an object; that is to say, the
value of a property helps to describe the current state of the object,
and each property of each object has a set of possible values, one of
which it has at all times.
The syntax for referring to objects is "[the] propertyName of
objectRef", unless it is a "global" property in which case you just say
"[the] propertyName".
The syntax for changing the value of a property is "set the
propertyName [of objectRef] to newValue". You cannot "put" into a
property (and you cannot "set" a container). -- However, some
properties cannot be "set" at all (they are "read-only"); a couple can
be "set" but can not be read!
A few properties can be set by a shortcut command, eg "lock screen"
instead of "set the lockScreen to true".
These symbols are used to describe properties in what follows:
� = cannot be set
� = can only be set (no get!)
� = linked to an Info dialog
� = shortcut command equivalent
� = default
�
Stack
NB: a stack need not be open to have its properties examined or changed.
cantDelete <boolean> -- � If true, the "Delete Stack..." menuItem balks
if chosen; but the stack is not finder-locked. cantAbort <boolean> -- �
If true, -. (to stop a handler in progress) is disabled cantPeek
<boolean> -- � If true, -(SH)-OPT (to examine where buttons and fields
are) is disabled; thus -(SH)-OPT-Click (to edit a button or field
script) is also disabled. cantModify <boolean> -- � If true, HC will
balk if the user attempts to type in a field or script, or to move or
delete a button or field, and menuItems involving changing the stack
(such as Compact Stack, Delete Stack, Copy, New Card, etc.) are
disabled; a script can still make changes, but they are "temporary" --
no such actions are written to disk, and are removed when leaving each
card. The user can still be permitted to type in fields and use paint
tools "temporarily" by setting the (global) UserModify to true. This
can be a good way to speed up stack response time; if values have to be
saved, they can be sent to a different stack. name -- setting also
changes the name in the Finder, and in the window titlebar if the stack
is open; new name must be Finder-legal (eg no colons in it) or HC
complains. You can ask for the long name, eg <stack "HD:Desktop
Folder:myStack">, the name, eg <stack "myStack">, or the short name, eg
<myStack>; the first two constitute a valid stack reference as is,
while the third requires "stack" before it, eg "stack theShortName".
�size <#bytes>
�freesize <#bytes> -- this is the space that (unfortunately) accumulates
as changes are made to a stack, and has to be eliminated from time to
time by compacting.
�version <comma-list> -- returns a five-item list. The first four items
are all versions of HC (for their format, consult the global Version
property, in chapter "Properties I"): the stack-creator, the most
recent stack-compactor, the oldest modifier since compaction, and the
most recent modifier. (That's according to the Reference stack. The
manual says something totally different, but we all know what it's
worth.) Fifth item is the Secs at the time of most recent modification.
�reportTemplates <return-list> -- names of all report templates
script <str>
scriptingLanguage
�
Background
�number <theNum> -- you can refer to the background as "bg theNum".
Numbers reflect the order of addition to the stack, but are adjusted to
remain sequential if a bg is deleted. Thus there is no guarantee that
the first card will have "bg 1" as its background.
�id <theID> -- a unique unchanging numerical identifier; you can refer
to the background as "bg id theID".
name <str> -- � You can ask for the long name, which returns a full
bgRef including full stack pathname, eg <bkgnd "myBg" of stack
"HD:Desktop Folder:myStack">; or, the name, which returns a valid
bgRef, eg <bkgnd "myBg">; or, the short name, which returns just the
string, eg <myBg>, so that you would have to say "bg theShortName" to
refer to the bg. If a bg has no name, all three forms substitute a full
ref by id, eg: "bkgnd id 4399". cantDelete <boolean> -- � If true, HC
balks if an attempt is made to delete the only cd of the bg. dontSearch
<boolean> -- � If true, find actions skip all fields (cd & bg) of all
cds of the bg.
showPict <boolean> -- whether the background graphics are visible.
�show/hide bg pict. A script can draw in a hidden bg picture but there
is no time savings.
script <str>
scriptingLanguage
�
Card
�number <theNum> -- you can refer to the card as "cd theNum". The
numbers reflect the order within the stack. [NB: although you can ask
for the (function) "the number of cds of this bg", and although you can
identify a card by its sequence within its background, eg "cd 2 of bg
1", you cannot find out what number a card is within its background!
Grrrrr!]
�id -- a unique unchanging numerical identifier. You can ask for the
long id, which returns a full cdRef by id, including full stack
pathname, eg <card id 4625 of stack "HD:Desktop Folder:myStack">; or,
the id, which returns a valid cdRef, eg <card id 4625>; or the short
id, which returns just a number <theShortID>, so that you would have to
say "cd id theShortID" to refer to the cd. [NB that only cards have a
"long id" and "short id" different from the ID; all other objects
simply return a number for all three. Grrr.] name <str> -- � You can
ask for the long name, which returns a full cardRef including full
stack pathname, eg <card "myCd" of stack "HD:Desktop Folder:myStack">;
or, the name, which returns a valid cdRef, eg <card "myCd">; or, the
short name, which returns just the string, eg <myCd>, so that you would
have to say "cd theShortName" to refer to the card. If a cd has no
name, all three forms substitute a full ref by id, eg: "card id 4399".
�owner -- equivalent to the Name of the background of the card (and
callable in the same three formats, long owner, owner, and short
owner). This is how to find out what background a card belongs to
without going there. cantDelete <boolean> -- � If true, HC balks if an
attempt is made to delete the card. dontSearch <boolean> -- � If true,
find actions skip all fields (cd & bg) of the card (but if false, find
actions will still skip the fields of the card if the DontSearch of the
bg is true). marked <boolean> -- � Handy for isolating particular
cards; certain commands can operate on marked cards specifically. �
[un]mark cardRef. showPict <boolean> -- whether the card graphics are
visible. �show/hide cd pict. A script can draw in a hidden cd picture
but there is no time savings. script <str> scriptingLanguage
rect -- this is really a stack feature, in that changing the Rect of any
card changes the rect of all cards of the stack (the stack's "size"),
and in that the user changes it through the Resize dialog of the Stack
Info dialog; but it is rightly classed as a card property in that it
can only be referred to for the current stack. Aspects of the Rect are
also accessible via �left, �top, �right, �bottom, �topLeft, �botRight,
height, width. Note that this is not a "proper" Rect, in that the
"right" and "top" are in fact always 0; thus all you can really change
is the Height and Width, and setting a card's Rect to, say,
"10,10,100,100" actually sets it to "0,0,90,90". The card Rect
represents the maximum size of the card window; a card whose Rect is
larger than the card window can be examined piecemeal via the Scroll
palette. Reducing the Rect of a card squeezes it towards its topLeft;
fields, buttons and graphics off to the right or bottom are not lost,
but they cannot be seen.
�
Field
�number <theNum> -- you can refer to the field as "cd|bg fld theNum".
The numbers reflect the layering order of fields within the bg or cd,
with 1 being furthest away. A new field is created nearest. partNumber
<theNum> -- you can refer to the field as "cd|bg part theNum". The
numbers reflect the layering order of fields and buttons within the bg
or cd, with 1 being furthest away. Changing the PartNumber changes the
layering order (with automatic changing of the PartNumbers of other
fields and buttons, as needed).
�id <theID> -- a unique unchanging numerical identifier. You can refer
to the field as "cd|bg fld id theID". name <str> -- � You can ask for
the long name, which returns a full fieldRef including card name and
stack pathname, eg <card|bkgnd field "myField" of card "myCard" of
stack "HD:Desktop Folder:myStack">; or, the name, which returns a valid
fieldRef, eg <card|bkgnd field "myField">; or, the short name, which
returns just the string, eg <myField>, so that you would have to say
"cd|bg fld theShortName" to refer to the field. If a field has no name,
all three forms substitute a full ref by id, eg: "card|bkgnd field id
2" ( and if the card has no name, then in the Long Name a ref by id
appears, eg: "card id 4399").
rect <theRect> -- aspects of the Rect are also accessible via left, top,
right, bottom, topLeft, botRight, height, width: changing any of the
first six moves the whole field without resizing; changing the Height
or Width grows or shrinks the field round its center point. The field's
scrollbars, if any, are included. Measurement is from the topLeft of
the card. The Right can be made less than the Left, and the Bottom can
be made less than the Top; in either case, the field becomes impossible
to see (though its Visible can still be true) and the Height/Width is
reported as "0". The Rect can be partly or completely off the card
rect, in which case as much of the field as is off the card becomes
impossible to see (though its Visible can still be true).
loc <point> -- the center point of the Rect.
visible <boolean> -- � show/hide fieldRef
scroll <numPixels> -- generates an error if not a scrolling field. If a
scrolling field, this is the number of pixels of the field "hidden"
above the top boundary. It can be virtually impossible for a script to
scroll a field to a certain text unless you already know the scroll
value for that text, or unless DontWrap and FixedLineHeight are both
true, because the calculation is in pixels and because a line is not
the same as a word-wrap "line".
script <str>
scriptingLanguage
style <transparent | opaque | rectangle | shadow | scrolling> -- �
dontSearch <boolean> -- � If true, find actions skip the field (but if
false, find actions will still skip the field if the DontSearch of the
cd or bg is true, or if the sharedText of the bg fld is true). lockText
<boolean> -- � If true, user cannot edit text by clicking in field and
typing, and field receives mouse-click messages. If false,
mouse-clicking in field sends no mouse-click messages, but editing
messages (EditField, ExitField, etc.) come into play. No � (grrrr).
autoTab <boolean> -- � In a non-scrolling field, if true, a
ReturnInField message reaching HC will cause a TabKey message to be
sent if the insertion point is in the last fully visible line of the
field. (Setting on a scrolling field does nothing.) dontWrap <boolean>
-- � If true, text does not word-wrap (ie, only return-characters cause
wrap). Always true when AutoSelect is true; setting to false sets
AutoSelect to false. fixedLineHeight <boolean> -- � If true, field's
TextHeight is used for all text regardless of size of text; if false,
spacing between "lines" automatically adjusts to make room for largest
text in each "line". Always true when ShowLines is true; setting to
false sets ShowLines to false. showLines <boolean> -- � If true, dotted
lines show the base of each "line", and FixedLineHeight becomes true.
wideMargins <boolean> -- � If true, extra left- and right-margin space
appears between text and boundaries. sharedText <boolean> -- � Useful
only in background fields; for a cd field, setting has no effect, and
getting returns Empty. If true, same text appears in field as instanced
for all cds of same background. A bg fld shows / allows editing of text
entered from background layer if SharedText is true, and shows / allows
editing of text entered from card layer if SharedText is false; when
value of SharedText changes, the text entered in the other layer is not
lost, so in effect all bg flds possess two texts, the unshared (card)
and the shared (background). If true, find actions skip the field even
if DontSearch is false (but if false, find actions will still skip the
field if the DontSearch of the field or cd or bg is true). autoSelect
<boolean> -- � If true but LockText is false, DontWrap is made true,
but otherwise has no effect. If true and LockText is true, DontWrap is
made true, and field acts as a "list field": clicking a line with text
in it (or SH-clicking or SH-dragging multiple contiguous lines, if
MultipleLines is true) selects entire line(s), and deselects all other
lines (as well as sending the various mouse messages). The selection is
not deselected when user works or clicks elsewhere. A line consisting
of just a Return has "text" in it, so be sure to eliminate such lines
at the end if you don't want the user selecting a blank line.
multipleLines <boolean> -- � If true but AutoSelect is false, or
AutoSelect is true but LockText is false, has no effect. For effect if
true when both AutoSelect and LockText are true, see on AutoSelect,
above.
textAlign <right|left|center> -- �, � = left
textFont <str> -- �, � = geneva
textSize <integer> -- �, � = 12
textHeight <numPixels> -- �, � = 16
textStyle <commaList> -- �, � = plain
NB: the Text... properties applied to a field are default values only;
particular text chunks may be given other values for textFont,
textSize, and textStyle, overriding the field's defaults, via the Font
and Style menus, and a script can get or set the values of these three
properties for a text chunk. If you get one of these for a chunk of
text where the value is not the same for every char, "mixed" is
returned.
�
Button
�number <theNum> -- you can refer to the button as "cd|bg btn theNum".
The numbers reflect the layering order of buttons within the bg or cd,
with 1 being furthest away. A new button is created nearest. partNumber
<theNum> -- you can refer to the button as "cd|bg part theNum". The
numbers reflect the layering order of fields and buttons within the bg
or cd, with 1 being furthest away. Changing the PartNumber changes the
layering order (with automatic changing of the PartNumbers of other
fields and buttons, as needed).
�id <theID> -- a unique unchanging numerical identifier. You can refer
to the button as "cd|bg btn id theID". name <str> -- � You can ask for
the long name, which returns a full buttonRef including card name and
stack pathname, eg <card|bkgnd button "myButton" of card "myCard" of
stack "HD:Desktop Folder:myStack">; or, the name, which returns a valid
buttonRef, eg <card|bkgnd button "myButton">; or, the short name, which
returns just the string, eg <myButton>, so that you would have to say
"cd|bg btn theShortName" to refer to the button. If a button has no
name, all three forms substitute a full ref by id, eg: "card|bkgnd
button id 2" (and if the card has no name, then in the Long Name a ref
by id appears, eg: "card id 4399"). rect <theRect> -- aspects of the
Rect are also accessible via left, top, right, bottom, topLeft,
botRight, height, width: changing any of the first six moves the whole
button without resizing; changing the Height or Width grows or shrinks
the button round its center point. Measurement is from the topLeft of
the card. What is measured is the whole button, including the circle of
a radio button, the square of a checkBox button, and the title plus
item of a popup button (see on TitleWidth, below, for more about popup
behaviour). The Right can be made less than the Left, and the Bottom
can be made less than the Top; in either case, the button becomes
impossible to see (though its Visible can still be true) and the
Height/Width is reported as "0". The Rect can be partly or completely
off the card rect, in which case as much of the button as is off the
card becomes impossible to see (though its Visible can still be true).
loc <point> -- the center point of the Rect.
visible <boolean> -- � show/hide buttonRef
enabled <boolean> -- � � enable/disable buttonRef; a disabled button is
greyed and mouse clicks within it generate no messages, though it does
still receive messages about the mouse's location
hilite <boolean> -- if true, all pixels within the intersection of the
card window and the "shape" of the button are inverted (a transparent
button's "shape" is its rect; an oval button's "shape" is the oval),
except that for a radio button, the black dot appears in the circle,
and for a checkBox, the X appears in the box. For a popup button, the
value of the Hilite makes no difference and has no effect. Can be
altered via mouse if AutoHilite is true or Family is non-zero.
script <str>
scriptingLanguage
style <transparent | opaque | rectangle | roundRect | shadow | checkBox
| radioButton | standard | default | oval> -- � autoHilite <boolean> --
� If true, the Hilite becomes true while the mouse is pressed within
the button, and becomes false when the mouse is released or leaves;
except that for a radio button or checkBox the circle/box thickens
while the mouse is pressed within the button, and the filledness of the
circle/box toggles when the mouse is released within the button.
"Within the button" means within its Rect, except that for oval buttons
it means within the oval. The AutoHilite makes no difference to a popup
button; all popup buttons display auto-hilite behaviour. NB: AutoHilite
behaviour is overridden if the button is in a Family; see below.
sharedHilite <boolean> -- Applies only to background buttons, though
setting on a cd btn causes no error, and getting on a cd btn returns
Empty. If true, the Hilite for the btn as instanced on each cd of the
bg is always the same; if false, the Hilite for each instance of the
btn is independent. Changing the value from false to true sets the
Hilite to false, and references to the Hilite from then on have to do
with "shared" hilite value; meanwhile, the "unshared" Hilite values are
retained, and are restored if the value is changed from true to false.
showName <boolean> -- � If true, and if the Name has not been set to
Empty, the Short Name appears within the button's shape. icon
<�name|num> -- � If not 0 (meaning it has no icon), the designated icon
(if available in the resource chain) appears within the button's rect,
except for radio buttons and checkBoxes, which do not display their
icon. Attempting to set the icon of a popup button gives an error.
family [0-15] -- � If not 0 (meaning it is not part of a family),
pressing the button hilites it and leaves it hilited, and unhilites any
buttons in the same layer (cd or bg) whose Family is the same.
Assigning a popup button a Family has no effect. titleWidth -- �
Applies only to popup buttons (can get and set for all button styles,
though). Denotes how many pixels of the button's width, starting with
its Left and heading rightwards, are to be reserved for its title when
it is "at rest". When the mouse is held down within the button's Rect,
the Rect is hilited and the contents of the button appear as a menu
whose left edge is at the button's Left+TitleWidth (thus if the
TitleWidth is larger than the width of the button, the menu will appear
surprisingly off to the right of the button). When the button is at
rest, the region of its Rect between the button's Left+TitleWidth and
its Right is covered by a shadow box, assuming the Right is larger (if
not, no shadow box appears). If this shadow box is wider than about 18
pixels, a down-triangle is fully visible within it. As the shadow box
is made wider still, parts of the currently selected line of the
button's contents appear: eg, "...", then "F...", then "Fi...", then
"First...", then "First Line". textAlign <right|left|center> -- �, � =
center. Has no effect on checkBoxes, radio buttons, and popups.
textFont <str> -- �, � = chicago. Has no effect if button is displaying
an icon, in which case the title, if displayed, will be in Geneva.
textSize <integer> -- �, � = 12. Has no effect if button is displaying
an icon, in which case the title, if displayed, will be sized 9.
textHeight <numPixels> -- �, � = 16, but meaningless, since a button
can have only one line of text. textStyle <commaList> -- �, � = plain.
Has no effect if button is displaying an icon, in which case the title,
if displayed, will be styled plain. NB: the Text... properties applied
to a button refer to the display of its name when ShowName is true. For
popup buttons, both the title and the "menu" are affected.
Properties II
COMMANDS
--> syntax of built-in "verbs"...
All commands (as opposed to keywords) generate messages, which proceed
up the hierarchy from the object whose script generated them, and which
must reach HC in order to execute their default behaviour.
Some commands (marked * below) are sent as messages automatically by HC
in response to user actions: that is, they are also system messages.
Consult chapter "Messages" for info on where and when these are sent.
Here is the opening terminological passage from that chapter,
explaining the relationship between commands and messages:
A message can be sent (i) by HC in response to events ("system"
message), or (ii) by a script ("handler" message), or (iii) from the
Message box ("msg" message). A handler message or a msg message can be
made up ("user-defined") or within HC's own known vocabulary
("pre-defined"); all system messages are pre-defined. A pre-defined
message can be "informational" (it is sent purely to let handlers know
what is happening) or a "command" (HC has a built-in action response to
it). When a message reaches HC, if its informational, it does nothing;
if it is a command, HC obeys it; if it is user-defined, HC complains.
Keypress commands are not re-described below; see chapter "Messages".
For commands having to do with talking to other applications, see
chapter "Communications".
�
Containers & Properties
put expr [into | after | before [chunk of] container] -- default is
"into msg", which will also show msg if it is hidden. "Before" and
"after" do not cross boundary lines; eg, "before item 2 of myCont"
means within item 2, just after the comma that delimits its start. If a
chunk number involving only "line" or "item" exceeds what is present,
HC will add intermediate delimiters; but, eg, if myCont contains "x",
then "put myStr into item 3 of line 3 of myCont" will generate two
Returns but not two Commas, and "put myWord into word 3 of myCont" just
acts the same as "put myWord after myCont". delete chunk of container
-- for "word", "item", and "line", a following delimiter, if any, is
also deleted, so this is not the same as "put empty into" the same
chunk add|subtract|multiply|divide number to|from|by|by [chunk of]
container -- the answer replaces the contents of the chunk or
container. HC complains if either argument is not a number (empty
counts as a number). See on put, above, for how HC supplies
intermediate delimiters if needed. get expression -- same as, "put
expression into it" set property [of objectRef] to expression -- see
chapters "Properties I" and "Properties II"
Property-setting Shortcuts: reset paint -- paint properties to defaults;
see chapter "Properties I" reset printing -- print properties to
defaults; see chapter "Properties I" enable | disable buttonRef -- sets
the Enabled; see chapter "Properties II" lock screen; unlock screen
[with visualEffect [speed] [to image]] -- sets the Lockscreen (see
chapter "Properties I"), but this way of unlocking is more powerful
because it can include a visual effect. If no "image" is included, the
visual effect moves the locked image out of the way to reveal the new
screen; if an "image" is included, the visual effect moves the locked
image out of the way to reveal the designated image, but that image
then just suddenly changes to the unlocked image, so this is not as
effective as with the visual command, where several transformations can
be happen on a single go. See below on visual, where "visualEffect",
"speed", and "image" are defined. lock | unlock error dialogs -- sets
the ErrorDialogs; see chapter "Properties I" lock | unlock recent --
sets the LockRecent; see chapter "Properties I" lock | unlock messages
-- sets the LockMessages; see chapter "Properties I"
See also Showing and Hiding (for setting the Visible), Marking (for
setting the Marked), and Menus (for setting the Name, MenuMsg, and
Enabled), below
�
Simulating User Actions
Keypress commands are not re-described here; see chapter "Messages".
select [before | after] [chunk | text] of fieldRef -- sets selection
point; the field's lockText need not be false. If it is a "list" field,
only the syntax "select line..." will do anything; what follows is
about non-list fields. Selecting by item|line|word will not include the
delimiter before or after. "Before|after" place the insertion point
with no text selected. To select the whole text, use "text" as the
chunk; otherwise the field qua object will be selected (ie with the
Field Tool). (NB: to deselect all non-list field text, say select
empty; to deselect all lines of a list field, say "select line 0
of...".) select line num of buttonRef -- for popup-buttons, changes the
SelectedLine, and the text appearing in the button "at rest", if room
has been allotted for this. If "num" = 0, no text will appear. No
effect on non-popups. select btnOrFldRef -- choose button or field tool
and select the designated object *choose <name> tool; choose tool <num>
-- tools are numbered right-to-left, then top-to-bottom, in the Tools
palette (grr). "Name" can be: browse, button, field, select, brush,
bucket, pencil, lasso, eraser, spray, line, text, oval, rectangle,
round rect, regular polygon, curve, polygon. It is an error to choose a
tool that the user cannot choose at the present UserLevel. click at
point [with modkey[, modkey[, modkey]]] -- "modKey" can be: shiftKey,
optionKey, cmdKey. If the point is one where mouse-click messages would
be sent if the user clicked there, a MouseDown, about 9
MouseStillDowns, and a MouseUp are sent; if you ask for two such clicks
in a row, a MouseDoubleClick is also sent. However, despite the
"modKey" modifier, a handler cannot learn that a modifier key was
"down" (grr). The click is "theoretical"; the actual cursor does not
move. Clicking outside the card window is legal but has no effect. You
cannot script the Polygon tool (grr). drag from point to point [with
modkey[, modkey[, modkey]]] -- "modKey" can be: shiftKey, optionKey,
cmdKey. ShiftKey must be used to select text. The drag is
"theoretical"; the actual cursor does not move. You cannot script the
Curve tool (grr). type string [with cmdKey] -- as if user typed *doMenu
itemName[, menuName] [without dialog] [with modkey[, modkey[, modkey]]]
-- "modKey" can be: shiftKey, optionKey, cmdKey. (The modKey list is
carried in param(6).) Same action as choosing the menu with the mouse,
except that disabled menuItems are available, and so are deleted
menuItems belonging to HC (but not menuItems taken out of action due to
low UserLevel). "Without Dialog" suppresses dialogs from Delete Stack,
Convert Stack, Cut Field, Clear Field. The ItemName must be exact;
capitals don't count, but ellipses do ("...", three periods in a row).
create stack name [with bgRef] [in new window] -- bypassing dialogs of
New Stack menuItem. Errors go into the Result. save stackRef as name --
bypassing dialogs of Save A Copy menuItem, but even more powerful: need
not be current stack! Errors go into the Result. delete
buttonOrFieldRef -- the button or field must be on the current card (no
error for trying, though)
�
Showing and Hiding
picture name[,source,style,visible?,bitDepth,floatingLayer?] -- any of
the optional parameters may be omitted. "Source" = file | resource |
clipboard. "Style" = rect (no nothing); shadow (no nothing); dialog (no
nothing, nice border); plain (titlebar, close box); roundrect
(titlebar, close box); windoid (titlebar, close box); document
(titlebar, close box, scroll & size); zoom (titlebar, close box, scroll
& size, zoom). � = "file", "zoom", "true", picture-depth, "true" for
rect, shadow, windoid, "false" for others. The purpose of "BitDepth"
(1,2,4,16,32) is to let you force a lower depth than the picture
actually possesses (you can't force it higher), so as to use less
memory at cost of lower resolution, and prevent too high depth from
screwing up screen colors; 0 forces no buffering at all, which slows
scrolling and zooming (and disables picture properties if memory is
really tight). palette name[,locPoint] -- you can't create the palette
invisibly, but you can use an offscreen loc. *close windowRef -- the
window must be an XCMD window or the current cd window (when other
stacks are open) hide titlebar | menubar | window|btn|fldRef -- sets
the Visible (except for titleBar). Also sent as a *message if user
hides menubar show titlebar | menubar | window|btn|fldRef [at locPoint]
-- sets the Visible (except for titleBar), and Loc if "at" is used; if
a window, also brings it to front. Also sent as a *message if user
shows menubar. show|hide cd|bg pict; show|hide pict of cd|bgRef -- sets
the ShowPict. Use the second syntax to affect non-current cd or bg
�
Finding, Marking, & Sorting
find [ whole | word | chars | string ] [international] str [in fldRef]
[of marked cds] -- the first optional parameter alters how find
interprets the presence of multiple words in "str", and when it regards
the search as successful, as follows:
a) words regarded as separate strings (only the first gets marked):
(none) -- card has words beginning with every given word
word -- the given words all appear on the card as words
chars -- the given words all appear on the card anywhere
b) spaces regarded as part of a single string:
whole -- str appears between word-boundaries
string -- str appears anywhere
"International" means that diacriticals matter; you cannot make
capitalization matter, though (grr). Find will find in invisible
fields, which can cause mysterious-looking results, so you may want to
prevent this by setting the field's DontSearch. There is no penalty for
giving a non-existent fldRef. Errors and failures go into the Result.
-- NB: find is fastest if the length of words of str is divisible by 3,
and the longer the faster. [un]mark cdRef | all cds | cds where
booleanExpr | cds by finding ... -- changes the Marked. In the "where"
form, the test is carried out on every card of the stack, so "this" in
the BooleanExpr refers to each card in turn. Syntax after "finding" is
identical to find, above. There is no penalty for giving a non-existent
fldRef. Errors and failures go into the Result.
show|hide groups -- makes grouped text in fields visibly marked, or not
sort [[bgRef] | [marked cds [of bgRef]] [how] by expr -- and...
sort [ lines | items of ] container [how] [by expr] -- First form
default is all the cards of the stack; "bgRef" form sorts all cards of
the designated background. "How" = [ ascending | descending ] [ text |
numeric | international | datetime ]; default is "ascending" & "text".
Default chunk of container is "lines". Note that if "by" is used, there
is essentially a fifth value-type, Boolean; "false" precedes "true" if
ascending (because this is actually a "text" sort!). The "by" expr is
evaluated separately for each card or line or item so as to derive the
key that will be used to order it; but it can be any expression that
yields the required type. It may include the special word each to
designate the lines or items taken one at a time. -- As far as I can
tell, HC is remarkably good about not disturbing the order and
interleaving of other cards when sorting. For example, if just cards 2
and 4 are marked and you sort the marked cards, cards 1 and 3 will
remain 1 and 3. But you will also go to the first sorted card (grr).
�
Dialogs
answer promptStr [with btnName1[,btnName2[,btnName3]]] -- last btn is
default-type; if no btnNames are given, "OK" will appear. BtnName of
response goes into It. answer file promptStr [of type
type1[,type2[,...]]] -- types can be stack, text, application, picture,
paint, or any four-letter type code; default is no filtering. Pathname
of chosen file goes into It; if user cancels, It is empty and theResult
is Cancel. Sorry, no way to select a folder, nor to prevent selector
button from reading "Open". Selecting an alias resolves the alias.
[Wow, is this wrongly documented in manual and reference stack!] answer
program promptStr [of type type1[,type2[,...]]] -- types are
four-letter creator codes; default is no filtering. Programs running on
macs networked to this one and with Program Sharing on are shown.
Net-path of chosen program goes into It; if user cancels, It is empty
and the Result is Cancel. Actual linking to a program on another mac is
not forged (eg, user must give a password) until you try to communicate
with it; see chapter "Communications". ask promptStr [with defaultStr]
-- for dialog with one editable text-box. Dialog contains OK (default)
and Cancel; edit-box entry goes into It. If user cancels the Result is
Cancel. NB that you can enlarge edit-box by including several lines in
DefaultStr (if you just want a big box, concatenated Returns would do).
ask password [clear] promptStr [with defaultStr] -- just like ask,
except that text in the edit-box appears as bullets. "Clear" keeps It
from being encrypted; the edit-box still shows bullets. An encrypted
reply is a ten-digit number. ask file promptStr [with defaultStr] --
the default button will read "Save"; pathname of postulated file goes
into It. If user cancels the Result is Cancel.
�
Menus
See also chapter "Properties I", which describes your power over menus
and the results of exercising that power. create menu name -- menu-name
appears leftmost among HC's menus, with no items in it. Will not
restore one of HC's standard menus you have deleted. delete
[menuItemRef of] menuRef -- deleting HC's menus or menuItems leaves
them available via doMenu (and they can be restored), but deleting your
own wipes them right out. enable | disable [menuItemRef of] menuRef --
sets the Enabled (see chapter "Properties I") put itemList
before|into|after [menuItemRef of] menuRef [with menuMsg msgList] --
sets Name and MenuMsg (see chapter "Properties I"). Putting into a
menuItem that already exists replaces that menuItem, but only that
menuItem even if itemList has several items. For a disabled grey line
in a menu, use "-" as a name. NB that giving a menuItem the same name
as one of HC's standard menuItems gives it its default behaviour as
well; you can therefore provide any desired subset of HC's menuItems in
any desired arrangement. reset menubar -- restores HC's default menus
and removes any other created menus. A problem arises when several
stacks each want to display a private menubar, because if a stack is
ill-behaved it may leave its menubar present when yours becomes
current. The simplest solution is to be defensive and well-behaved
yourself: on OpenStack and ResumeStack, use reset menubar and create
your menubar anew, and on CloseStack and SuspendStack, use reset
menubar. Unfortunately things can get insanely tricky if your stack is
a "start using" stack; to see one solution, examine the Home stack
script as modified by the Color Tools stack.
�
Navigating
go [ cdRef | bgRef | markedCdRef ] [of] [stackRef [in new window]
[without dialog]] -- (I mean to say, you can use a card reference or a
stack reference or both, but if you use both you have to connect them
by "of"). MarkedCdRefs are restricted to simple ordinal specifications
of "marked cd" (ie, unlike cdRef, you can't relate ordination to a bg;
grrr). Omitting cdRef sends you to the first cd of whatever you do
specify. "Without dialog" prevents SFOpen from appearing if stack isn't
in search paths; instead, error is reported in the Result. go back |
forth | home | cdAdjective -- "back" and "forth" move among recently
visited cards. "cdAdjective" is just a shortcut syntax for simple
word-ordinal cdRefs in the same stack: you can say "first", "third",
"next", etc. push whatCard -- you can push any card that you can
specify with the first syntax of go, above. Places a specifier for the
card on top of a special "push-list". pop cd [into | before | after
container] -- removes the card specifier currently on top of the
"push-list" (see push, above). If no container is specified, also
executes a go to that card; if a container is specified, just performs
a put. (The second syntax is handy when you want to go in a new window,
because you can't do that with pop. Grr.) The bottom-most item in the
"push-list" is cd 1 of the Home stack, and cannot be removed. show [
[howMany] | all | marked ] cds -- default is "all". Goes quickly to
each of the specified number of cards in turn, starting with the next;
no messages are sent, but a knowledge of each card is apparently cached
in RAM, so that subsequent navigation will be faster.
�
Import & Export
Text Files:
open file pathName -- for text files; a file must be open before you can
read or write it. Creates the file if it can't find it. read from file
pathName [at [-]startNum] [[for numChars] | [until char]] -- you must
use either "for" or "until" syntax. "-" lets you start a certain number
of chars from the end. "char" can be a literal character or tab,
return, space, quote, formFeed, eof, end; the "until" char is included
in the read. Nulls are read as spaces. Result goes into It. There used
to be a limit of 30K chars, but this is now lifted; however, the text
of a field is still limited to 30K. write text to file pathName [at
[-]startNum|eof] -- "-" lets you start a certain number of chars from
the end. If you don't use "at", writing starts from the end of the
previous write (from start of file if there was no previous write). If
a series of writes contains no use of "at", the file is replaced, but
if even one "at" is used, any previous and not overwritten text
remains. close file pathName -- signals done reading or writing;
important to do this
Printing:
print expr -- if expr is a single fieldRef, styled text will be used
print all | marked | howmany cds -- prints card images, using the
current Print Stack and Page Setup settings; if "howmany" used, cards
will be sequential starting with the current card print cd | cdRef
[from point to point] -- prints card image, using the current Print
Stack and Page Setup settings, with option to print just a certain
rectangle of the card open printing [with dialog] -- for printing cards
not in sequence; all "print" card commands will be collected until
"close printing". "With dialog" brings up Print Stack dialog, where
user can change settings. open report printing [with dialog] [with
template name] -- for printing cards according to a report template;
all "print" card commands will be collected until "close printing".
"With dialog" brings up Print Report dialog, where user can change
settings. Either the command or the user must specify a template, or
else one must have been used earlier (and it will be used now by
default). copy template name to stackRef -- for getting a report
template from current stack into another close printing -- don't forget
this after an "open printing"
Paint:
import paint from file name; export paint to file name -- just like the
corresponding menu items (but without dialog), and only available when
they are
Telephone:
dial num [with modem [commandString]] -- default commandString is
"ATS0=0DT", and be sure to enclose yours in quotes so HC doesn't try to
evaluate it first! If "modem" is used, commands go out the serial port;
if not, the speaker makes touchtones.
�
Special Effects
visual name [[very] fast | slow ] [to image] -- visual effects pile up
within a handler until the next go, when they are executed in sequence.
The effect is a way of revealing the next image from the current one.
"Image" can be black, white, gray, inverse (of card we are going to),
card (which we are going to); "card" is the default. If you change to a
non-card image and do not change to the card with another effect, the
image is instantly replaced by the card. Effect names are:
plain (the default)
zoom open|close (from the clickloc, but to the center)
iris open|close; barn door open|close
push|wipe|scroll right|left|up|down (push = both cards move; wipe = both
cards still; scroll = next card moves)
dissolve; checkerboard; venetian blinds
shrink to|from top|center|bottom
flash [howMany] -- default is 3
beep [howMany] -- default is 1
wait howMany [ ticks | secs ] -- default is ticks
wait until | while boolean
play resourceName [tempo speed] [noteString] -- included resources are
Harpischord, Flute, Boing; or play stop to kill the currently playing
string. 200 is a moderate tempo.
Notes are abcdefg[#|b] with octave (4=middle); or you can use numbers if
you find that easier, with 60 = middle C; r = rest. Durations are
whqestx[.|3]. Note and duration should be together, followed by space,
then next note and duration, etc. Duration and octave remain in effect
until altered (inital defaut is 4q). NB: play name 0 will preload the
resource. HC usually continues with actions while the sound plays.
Errors go into the Result.
edit script of objectRef
debug checkpoint -- there are other "debug" commands but they won't
start|stop using stackRef -- insert or remove stack script in hierarchy,
just following current stack (see chapter "Messages"). All resources in
a "using" stack also become available.
convert [chunk of] expr [[from format] [and format]] to format [and
format] -- for date-time format conversions; "and" is for handling
date and time separately. Formats are: seconds, long date, short date,
abbr date, long time, short time, dateItems (=
yr,mo,day,hr,min,sec,dayNum). Conversion is performed in place, except
that conversion of a literal goes into It. Date-time formats respond to
itl resources, so calculations and storage should use "seconds" or
"dateItems", which are reliable across localisations.
help -- goes to first cd of "HyperCard Help"
Commands
COMMUNICATIONS
--> talking to other applications...
�
Apple Events
SENDING, SAME MAC:
You can send basic Apple Events on the same Mac via the following commands:
open [docPath with] appPath -- sends an 'oapp' or 'odoc', as
appropriate, telling an application to launch or to open a document.
Errors go into the Result. A valuable use is to bring HC to the
foreground by telling itself ("this program") to open. close [docPath
in|with] appPath -- sends a 'quit' or 'clos', as appropriate, telling
an application to close a document or to quit altogether. Unfortunately
'clos' is not a required Apple Event so not every app need be able to
handle it. Errors go into the Result. (Do not type the words Close
"Finder" into the message box in a misguided attempt to test this
command!) print docPath with appPath -- sends a 'pdoc', telling an
application to print a document.
SENDING, OTHER MAC: You can send basic Apple Events to an already
running program on the same or a remote Mac via the following commands.
If on another Mac, the syntax "[zoneName:]machineName:theProgram")
navigates the net. You can specify the program by name or by "ID",
meaning its creator signature.
send expression to { this program | program [ID] theProgram } [without
reply] -- sends a 'dosc' (doScript). This presumes that the program has
some native scripting dialect; what you send should be a command or
series of commands in this dialect. Reply or error goes into the
Result. request expression of|from { this program | program [ID]
theProgram } -- sends an 'eval' (evalute). The evaluated expression
(ie, the direct param of the reply) goes into It. Errors go into the
Result.
RECEIVING AND REPLYING: Incoming Apple Events trigger an appleEvent
system message.You can intercept and deal with such events yourself if
you like. This ability was more important under 2.1, when HC could
respond automatically only to the basic four Apple Events, plus 'dosc'
and 'eval'; it was useful then to be able to define your own Events.
Now, however, HC responds automatically to over 150 events, so you may
want to check this before interfering. HC won't do its automatic
response unless the appleEvent message is passed all the way to HC.
When an Apple Event comes in, class and id (and sender) are passed as
parameters to the appleEvent message. If you handle the event yourself
and you need more information (so-called "parameters"), you use the
request command; to reply to it, you use the reply command, as follows:
request ae data -- fetches the "direct parameter" (the one whose
keyword is "----") into It. Errors go into the Result. request ae data
with keyword theKeyword -- fetches the parameter whose keyword is
"theKeyword", into It. Errors go into the Result. A special case is the
"rtid" keyword, which gives the returnId; you can ask for this with
request ae return id. You can fetch the sender's signature ID (as
opposed to name) with request ae sender id. reply replyString [with
keyword theKeyword] -- if you omit the "with keyword" option, the reply
expression is sent as the "direct parameter". For keyword "errs" you
can use the cuter form reply error replyString.
�
OSA Dialects
If OSA dialect extensions installed themselves onto you Mac during
startup (as do AppleScript, QuicKeys, Frontier's UserTalk), you can
send commands directly into the system in those dialects. (To find out
what dialects are in your system, open a script and examine the pop-up
dialect menu at the top of the window.) The "keeper" of the dialect can
thus be made to exercise its particular powers on your machine:
AppleScript could be made to send some commands to a scriptable app
such as Scriptable Text Editor or to take advantage of an 'osax' you
happen to have; or, QuicKeys could be made to type an expression in any
app whatever. There are two cases: the dialect commands live in a
container (or are constructed as an expression), or, the entire script
of an object is written in a dialect.
CONTAINER:
You can send expressions and the contents of containers with the do command:
do expressionOrContainer as dialectName -- Sends commands to the
"keeper" of the dialect in question. If the container has several lines
(a field, perhaps), the whole container will be sent as a script.
SCRIPT:
You can write an object's entire script in an OSA dialect, using the
pop-up menu at the top of the script window, or the script property the
scriptingLanguage. Note that dialects can't be mixed in one script,
though scripts of different objects in one stack can have different
dialects. Scripts in foreign dialects don't work within HC like
HyperTalk scripts. The script is not "pretty-printed" until you close
the window. At that point it is sent to the "keeper" of the dialect for
checking and compilation; so problems can arise if compilation
conditions are not right (for example, AppleScript can't compile when
there is a reference to a program on a remote computer unless the
program is running). Also, foreign dialect scripts can be slow to open
(while the script "decompiles"), and if you try to open them when the
dialect is not present on the computer or under earlier versions of HC,
there can be trouble (like, loss of the script).
How you "talk" to a script in another dialect depends on whether it can
receive function messages or not. If a dialect cannot receive function
messages, like QuicKeys, the only way to deal with it is to run the
entire script of an object by saying send "run" to theObject (or by
letting the message run reach it in the hierarchy). You might think
this means there is no good reason to keep such commands in a script
(why not just keep them in a container, as above?), but I suspect that
there is some speed value, since the script is compiled. If a dialect
can receive function messages, like AppleScript, you can use messages
from within HyperTalk to call the functions. For example, if the
hyperTalk message MyMessage reaches an AppleScript object script
containing a handler "on MyMessage()", the handler will run. When an
AppleScript handler is running, the default application is
automatically HyperCard; you don't have to "tell HyperCard" anything.
HyperCard is scriptable, so AppleScript can talk to it, either using
"do script" or using the various Apple Events that HyperCard
recognises. Values can be passed as parameters to messages, or using
HyperCard's scripting object type "variable" (meaning a global), or by
telling HyperCard to set the contents of a container; but watch out,
HyperCard is expecting strings only, whereas AppleScript variables can
be of other types and may have to be coerced or otherwise processed.
--------------------------------------------------------------------
-end of text file conversion-