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 for hypercard help HYPERTALK 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 , 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 ^ * / div mod + - & && < > <= ² >= ³ 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 -- current mouseClick -- 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 ; mouseLoc -- current clickH, clickV ; clickLoc -- 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 -- 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 -- 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) 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) Ê 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 Ê Text length(string) offset(findString,inString) -- returns 0 if InString doesn't contain FindString charToNum(char) -- ignores all but first char of string param numToChar(num) Ê Math random(integer) 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) 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 -- the list on my computer starts with "Apple" and ends with "System Help", "Keyboards", "Application" windows -- 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 -- 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 -- 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" -- of AppleEvent-aware apps running on the other computer screenRect -- 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 -- usable in handlers for CloseStack, CloseBackground, CloseCard, and SuspendStack to find out where we'll be going after this number( | ) -- must name a container too, using in|of, and can be chars, words, items, lines, menuItems; can be [bg|cd] btns|flds|parts, bgs, cds, marked cds, cds of , menus, windows value() -- 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 -- 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 -- can user type into hidden msg? (¶ from Home stack), powerKeys -- can user employ painting keyboard shortcuts? (¶ from Home stack) textArrows -- 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 -- 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 -- ¶ = comma Display: ¦*cursor -- 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 -- bigger is faster (in pixels/sec), except that 0 (= ¶) is fastest. Bucket and Text tools are unaffected longWindowTitles -- ¶ = 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 -- toggling is just like selecting Background from the Edit menu Scripting: scriptTextFont -- ¶ = monaco scriptTextSize <#points> -- ¶ = 9 traceDelay -- ¶ = 0 debugger -- ¶="ScriptEditor" scriptEditor -- ¶="ScriptEditor" variableWatcher -- ¶="VariableWatcher" messageWatcher -- ¶="MessageWatcher" Suppression: *lockScreen -- ¤ [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 -- ¤ [un]lock messages. If true, suppresses Open..., Close..., Suspend..., and Resume... system messages. ¶ = false *lockRecent -- ¤ [un]lock recent. If true, suppresses automatic recording of recent cards; can save a mess of time during navigation. ¶ = false *lockErrorDialogs -- ¤ [un]lock errorDialogs. If true, suppresses display of error messages; instead, ErrorDialog message is sent to current cd. ¶ = false Output: *numberFormat -- 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 -- 72 = 1 inch; ¶ = "0,0,0,0" printTextAlign -- ¶ = left printTextFont -- ¶ = geneva printTextSize -- ¶ = 10 printTextHeight <#points> -- ¶ = 13 printTextStyle -- ¶ = 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 -- ¶ = 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 -- ¶ = "geneva" textSize -- ¶ = 12 textHeight -- ¶ = 16 textStyle -- ¶ = "plain" Note: ¤ reset paint restores the defaults for above painting properties Environment : ¥stacksInUse -- of the "start using" stacks, in hierarchical order ¥suspended -- 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 -- 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 -- you can refer to the window as "window theName" ¥id -- you can refer to the window as "window id theID"; IDs are unique and permanent ¥number -- 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 -- either "HyperCard" (for a card window and HC's floating windows) or the name of an XCMD (for an external window) rect -- 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 -- same as the TopLeft portion of the Rect visible -- ¤ 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 -- 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 -- "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 -- 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 , globalLoc -- 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 -- 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 , 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 -- 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 ¥commands -- the command for button n is on line n hilitedButton -- 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 -- ¶ = 98, 99 resp. ¥properties you can set ¥zoomed without error but it remains false Message Watcher: hideIdle, hideUnused -- ¶ = false, true resp. text -- complete text ¦nextLine -- 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 -- ¤show/hide menubar Menu: ¥name -- you can refer to a menu as "menu theName", or ask for the long name, which returns a valid menuRef, eg . You can't change a menu name, but you can delete and create whole menus. ¥¦number -- 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 -- ¤ 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 -- You can use theName for itemNameOrNum in the above reference format, or ask for the long name, which returns a full valid menuItemRef, eg . To obtain a whole list of names of the menuItems of a menu, just use a menuRef (eg ); 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 -- 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 -- 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 -- 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 -- ¤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