Tilting at Pixelated Windmills: HyperCard IIGS BugTracker documents

The HyperCard IIGS BugTracker stack was developed by Brendan Bellina to provide information about known bugs in HCGS, errors in the HCGS Script Language Guide, and also provide information about differences in Macintosh HyperCard 2.4.1 and HyperCard IIGS 1.1. Several documents are included in the stack that can be helpful to a HCGS developer. Several of those are also shared in this blog post. The stack is included in the HCGS Best Of 32 MG image available at the Silverwand Software site.

The following documents are included below:

Apple's HCGS Technotes

HCGS Technote #1 - Corrections in the Script Language Guide

HCGS Technote #2 - Known HyperCard IIGS Bugs

HCGS Script Language Guide Errata - B Bellina, May 2024 revision

Common Mac HyperCard and HCGS HyperTalk Differences - B Bellina, Nov 2024 revision

Apple II

Technical Notes

_____________________________________________________________________________

Developer Technical Support

HyperCard IIGS

#1: Corrections to the Script Language Guide

Written by: Dan Strnad & Matt Deatherage March 1991

This Technical Note corrects the HyperCard IIgs Script Language Guide from

Addison-Wesley.

_____________________________________________________________________________

Appendix A: External Commands and Functions

Page 317: ReturnStat

Developers who worked with the beta version of HyperCard IIgs on Volume V of

the Developer CD (or volume 4 of Developer Essentials) should pay special

attention to the use of the returnStat parameter documented on page 317 ofthe

manual, as this method for using HyperCard's error-reporting facilities

wasnot present in beta versions of HyperCard.

Page 318: HyperCard IIgs callbacks

Before describing the callbacks, the Script Language Guide says that thefirst

parameter to each callback is the parameter block pointer that HyperCard IIgs

passes to the XCMD or XFCN. This is not correct; the XCMD/XFCN

parameterblock is not passed to callback routines. Each callback uses only

the parameters supplied with its description.

Pages 318-324: Callback descriptions

The numbers listed for each callback are actually decimal numbers, not

hexadecimal. There should not be a "$" in front of each number.

Pages 325-330: Beep, an example XCMD

Although there are "beep" sample XCMDs provided with the HyperCard IIgsScript

Language Guide, they do not necessarily build and execute unmodified.

Specifically, depending on your compiler, there could be a linking

problemwith the Pascal and C XCMDs as given in the manual.

XCMDs and XFCNs are code resources, and are therefore subject to the

limitations listed in Apple IIgs Technical Note #86, Risking ResourcefulCode.

The specific problem here is that most Pascal and C compilers will create at

least three segments: ~globals, ~arrays, and main. An XCMD or XFCN can only

have one segment and the entry point must come first. Not only must you link

all the object segments into one segment, but you must specifically

extractthe entry point and link it first. HyperCard will pass control to the

first byte of the loaded XCMD or XFCN, and therefore this must be the entry

point. The samples in Appendix A point this out in the code.

Actual buildable sample source for the "beep" XCMDs is available in APW

andMPW IIgs format on Volume VI or later of the Developer CD Series (or

volume 5 or later of Developer Essentials). A complete APW C sample is

included below.

An APW Sample XCMD: "CBeep"

CBeep.c

/*----------------------------------------------------------------------

file CBeep.c

This XCMD has the following syntax:

CBeep beep once

CBeep ## beep n times

CBeep ? display usage information

CBeep ! display version information

----------------------------------------------------------------------*/

#include <types.h>
#include <MiscTool.h>
#include <GSOS.h>
#include <HyperXCMD.h>
/*
Globals
*/
int _toolErr;
XCMDPtr gParamPtr;

/*
Forwards
*/
pascal void CBeep();

/* We place the entry point function in its own segment, so the linker can
extract it and ensure that it's first in the load file. */
segment "EntrySeg"
/*
This is the entry point to the program. Make sure this procedure
comes first in the final OMF resource because this is where HyperTalk
will be jumping in.
For a really simple XCMD you could just put the code all in here, but
for cleanliness' sake this example calls another routine from here.

*/
pascal void EntryPoint(paramPtr)
XCMDPtr paramPtr;
{
CBeep(paramPtr);
}
/* All other code & data is placed in the "Main" segment */
segment "Main"

/* The actual CBeep function. Interpret parameters and beep the speaker
*/
pascal void CBeep(paramPtr)
XCMDPtr paramPtr;
{
short beepCount;
short counter;
Str255 str;
char *formStr = "\pAnswer \"FORM: CBeep {count}\"";
char *versionStr = "\pAnswer \"CBeep XCMD v1.0\" & return & \"(c) 1991
Apple Computer, Inc.\"";
gParamPtr = paramPtr; /* put in a global for easy access in other funcs
*/
if (paramPtr->paramCount > 0) {
ZeroToPas(*(paramPtr->params[0]), &str);
beepCount = 0;
if (str.text[0] == '?') /* test for special characters */
SendCardMessage(formStr);
else if (str.text[0] == '!')
SendCardMessage(versionStr);
else beepCount = StrToNum(&str); /* not a special - take as # of
beeps */
}
else beepCount = 1; /* no count, assume one */
beepCount = (beepCount <= 15) ? beepCount : 15; /* limit 15 beeps */
for (counter = 0; counter < beepCount; counter++) SysBeep();
}
CBeep.r
/*******************************************************************/
/*
/* CBeep.r
/*
/* Copyright (C) 1991
/* Apple Computer, Inc.
/* All Rights Reserved
/*
/* Rez source for building XCMDs.
/*
/*******************************************************************/
#include "types.rez"
read $801E (1, convert) "CBeep.omf";
resource rResName ($0001801E) {
1,
{ 1, "CBeep";
}
};

Make file

* ------------------------------------------------------------------
*
* This makefile will build C XCMDs for HyperTalk
*
* Copyright Apple Computer, Inc. 1991
* All Rights Reserved.
*
* Builds: CBeep
* This makefile depends on a .r file called CBeep.r to act
* as a source for the resource compiler.
compile +t +e CBeep.c keep=CBeep
* ------------------------------------------------------------------
*
* The compilers will output 3 or more segments: main, containing code;
* and ~globals and ~arrays containing data. This line ensures that
* everything gets put back into the main segment.
*
* In addition, it specifically links the EntryPoint procedure FIRST,
* ahead of any globals or data structures.
* The linker line is very long - make sure you use all of it
linkiigs -x -lseg main CBeep.root(@EntrySeg) CBeep.root(@Main)
CBeep.root(@~arrays) CBeep.root(@~globals) 2/CLib -lib 2/CLib -o CBeep.omf
compile CBeep.r keep=CBeep.rsrc
* now use your favorite resource utility to copy the XCMD from CBeep.rsrc
* into your stack

Further Reference

_____________________________________________________________________________

o HyperCard IIgs Script Language Guide

o Apple IIgs Technical Note #86, Risking Resourceful Code

o HyperCard IIgs Technical Note #2, Known HyperCard Bugs

Apple II

Technical Notes

_____________________________________________________________________________

Developer Technical Support

HyperCard IIGS

#2: Known HyperCard Bugs

Revised by: Matt Deatherage May 1992

Written by: Dan Strnad & Matt Deatherage March 1991

This Technical Note documents known bugs in the released version of HyperCard

IIgs that may affect developers.

CHANGES SINCE MARCH 1991: Revised to list version 1.1 bugs (sigh) as well as

version 1.0 bugs.

_____________________________________________________________________________

HYPERCARD EXTERNALS AND NAMED RESOURCES

HyperCard's XCMD and XFCN callbacks documented in Appendix A of the HyperCard

IIgs Script Language Guide include callbacks that find named resources. In

versions 1.0 and 1.1, these routines don't compare the lengths of the resource

name strings, which makes HyperCard return the wrong named resource from time

to time.

A more precise description of this problem is in Apple IIgs Technical Note

#83, "Resource Manager Stuff." Note that HyperCard IIgs does not use the

Resource Manager's named resource routines, but the code in the Resource

Manager suffers from the same problem the HyperCard code has.

PREVIOUS BUGS FIXED

The two bugs previously listed in this Note--improper handling of desk

accessories and crashing when using objects or properties of different stacks

to externals--are both fixed in HyperCard IIgs version 1.1.

Further Reference

_____________________________________________________________________________

o HyperCard IIgs Script Language Guide

o HyperCard IIgs standard documentation (included with HyperCard IIgs)

Apple IIGS Script Language Guide Errata - compiled by Brendan Bellina

A collection of HCGS Script Language Guide corrections

by Brendan Bellina, revised May 27, 2024

The HCGS Script Language Guide published by Addison-Wesley is a very useful guide, however there are some errors in it that are not documented in Developer Technical Note #1 from March, 1991, as well as missing information pertaining to HCGS v1.1.

These are the additions and corrections I have made in my copy of the guide during the course of my development. Mileage may vary. Caveat Emptor.

Fields (p. 6) (addition)

There is a maximum of 30,000 characters in a field. (see p. 346)

itemDelimiter (p. 68) (addition) (v1.1)

Set the itemDelimiter to use a character different than comma as a delimiter. The delimiter is automatically reset to comma by idle. (Also add to glossary page 397)

Correction (p. 80)

The openStack description states that the order of system messages when a stack is opened is openCard, openBackground, openStack. This is actually backwards. The correct order is openStack, openBackground, openCard. The close system messages order is closeCard, closeBackground, closeStack.

Clarification (p. 80)

The closeCard, closeBackground, and closeStack descriptions state that the messages are sent when transitioning to another card, background, or stack. This is not a complete statement, since all of the close system messages are also sent when a stack is closed by opening an application. In this situation the closeCard, closeBackground, and closeStack messages are sent followed by the suspend message.

Answer (p. 103) (addition)

File type "application" includes both ProDOS (type 255) and GS/OS (type 179) applications. To distinguish use the file type number.

File type numbers include: stack 85; GS/OS application 179; BASIC program 252; ProDOS application 255

Maximum length of each button in the answer dialog is 11 characters.

Ask (p. 108) (addition) (v1.1)

When cancel is clicked "It" will be empty and "Cancel" will be in "the result".

Delete (p. 123) (addition)

Do not use the word "the" after delete. Doing so will not work in HCGS though it does work in Mac HyperCard.

DoMenu (p. 126) (addition)

The without dialog option does not work with the Clear Field menu option and may not work with others as well.

Open (p. 143) (addition)

When using open with a file both colons and forward slashes can be used as delimiters.

Open file (p. 144) (correction)

In the example checkFile script the line:

if the result is not empty then answer

should be:

if it is empty then answer

(Note: I recommend using the fileExists XFCN from this stack instead, since using open file to check file existence will mistake an empty file for file absence and create an empty file if there was no file.)

Play (pp. 146-147) (addition)

The notation string is limited to 254 characters, same as in Macintosh HyperCard 1.2.5.

A rest is "r" followed by duration. For example a whole note rest is "rw". A whole rest can also be played by itself by using: play "silence" w

(clarification) The "play stop" command will only stop a sequence of notes that are being played at the end of a note. It will not immediately stop the playing of a note. So if a note is really a lengthy sound effect such as a movie quotation then issuing play stop will have no noticeable effect.

(clarification) Using the phrase: wait until the sound is "done" works in HCGS but the quotation marks MUST be used around the word done. In Mac HyperCard the quotation marks around "done" are optional.

Pop card (p. 148) (clarification)

When popping a card into a container the card identification is removed from the stack and put into the container rather than transitioning. With or without a container pop card always removes the most recently pushed card from the top of the stack.

Read limit (p. 155) (correction)

The statement "You can read strings up to 16834 characters" is incorrect. That was a limitation of Mac HyperCard at one time. In HCGS read is limited only by available memory.

heapSpace and stackSpace (p. 181) (addition)

In addition to DiskSpace there are undocumented heapSpace and stackSpace functions that check memory. (Also add to glossary pages 396 and 399)

numToChar (p. 196) (clarification)

numToChar allows control characters to be written by specifying numbers lower than 32. However it is not possible to use numToChar with ASCII value 0 because numToChar(0) is nothing rather than hex $00.

random (p. 201) (clarification)

The random function has a maximum limit of 65535. If a higher number is specifed then the random function will return 1.

Round() (p. 203) (clarification)

The round function is based on the IEEE standard which states that numbers that end with .5 should round to the nearest even whole number. This results in unexpected results like round(7.5) = round(8.5). These are equivalent because per IEEE standard rounding of .5 is to the closest even integer, so positive even numbers and negative odd numbers round down, while positive odd numbers and negative even numbers round up:

round(7.5) returns 8

round(8.5) also returns 8

round(-7.5) returns -8

round(-8.5) also returns -8

To always round up use this function:

function roundup num

if abs(num - trunc(num)) = .5

then add .1 to num

return round(num)

end roundup

To always round up when positive and always round down when negative use this function:

function roundNum num

if num - trunc(num) = .5 then add .1 to num

else if num - trunc(num) = -.5 then subtract .1 from num

return round(num)

end roundNum

ShiftKey (p. 208) (correction)

Notes should read "See also the commandKey and optionKey functions earlier in this chapter."

Field properties (p. 221) (addition)

There is a maximum of 30,000 characters in a field. (see p. 346)

Field properties (p. 222) (addition) (v1.1)

The backColor property is not listed. This is the field background color.

Button properties (p. 224) (addition) (v1.1)

The backColor property is not listed. This is the button background color.

LastError (p. 262) (correction)

The final line of the sample script should be "end idle" not "end mouseUp".

HCGS Callbacks (p. 318) (correction)

See HCGS Developer Tech note #1, March 1991

Beep example XCMD (p. 325) (correction)

See HCGS Developer Tech note #1, March 1991

Common Mac HyperCard and HCGS HyperTalk differences:

by Brendan Bellina, last revised November 26, 2024

(This is not Apple documentation and some of these issues may be for specific versions of HyperCard and HyperCard IIGS only.)

Avoid unneeded use of "the":

HCGS can misinterpret the use of the always optional "the", so avoid it on both platforms except when using it with system functions that have no parameters (because it is faster to use the than ()) (e.g, the clickChunk, the clickLine). Examples of misinterpretation include following the "delete" command.

Use number(), not "of this stack":

HCGS does not understand the phrase "of this stack" in the context of returning the number of cards or backgrounds in a stack, so instead use the number() function to get the number of cards or backgrounds for a stack.

Required quotation marks around done in HCGS are optional in Mac HyperCard:

Using the phrase: wait until the sound is "done" works in HCGS but the quotation marks MUST be used around the word done. In Mac HyperCard the quotation marks around "done" are optional.

Ask differences:

The Mac HyperCard ask command can handle multiple lines in a dialog, whereas HCGS only allows a single line.

New Button defaults:

In HCGS new button defaults include Auto Hilite ON and rectangle style, in Mac HyperCard these defaults are Auto Hilite OFF and "roundRect" style.

Allowed Button styles:

HCGS is limited to rectangle, opaque, rectangle, shadow, round rect, check box, and radio button. Mac HyperCard 2.4.1 has all of these as well as standard, default, oval, and popup.

New Field defaults:

HCGS new field defaults to transparent style, in HC Mac the default is rectangle style. The HCGS default font is 8 pt. Shaston, the Mac HyperCard font is Geneva 12 point.

The default textFont value in HCGS is Shaston. Mac HC used either Chicago or Geneva as the default textfont depending on the HC version. In Macintosh HC if you set "the textFont" to a font that is not installed then it will reset to the default font. In HCGS if you set "the textfont" to a font that is not installed then the set command is ignored. This behavior can be used to determine if a font is available. Macintosh HyperCard stacks often use Apple's FontExists XFCN.

resetPaint command settings:

Setting HCGS HC Mac

grid false false

lineSize 1 1

filled false false

centered false false

multiple false false

multiSpace 1 1

pattern 1 12

brush 7 8

polySides 4 4

outlined false not a setting

textAlign left left

textFont shaston "Geneva"

textSize 8 12

textStyle plain plain

textHeight 9 16

Allowed Font styles:

HCGS fonts cannot be Condense, Extend, or Group styles. Only plain, bold, italic, underline, outline, and shadow are common to both platforms.

Mac HC 2.2 and later allows multiple font styles within a field. Earlier versions of Mac HC and HCGS allow only a single font style within a field. The MultiFont bitmap font released on Script-Central Special Edition v9n4 can be used to mix plain and italic Times (10, 12, 14) within a field.

Enabling/Disabling buttons:

There is no enable/disable button capability in HCGS. This can be mimicked by graying the title and text of the button and checking the color in the mouseUp script. (see the enable/disable/isEnabled functions by B. Bellina in this stack script.)

Button Family differences:

Both Mac HC 2.4 and HCGS allow buttons to be in families, but the method for determining which button is hilited in a family of buttons is different. In HCGS the hilited button is determined by: "the hilitedBtn of [card/bg] family [n]. In Mac HC use "the selectedButton" instead. The number of button families allowed is also different: Mac HC allows 15 button families; HCGS allows 9.

Field Messages:

There is no exitField message in HCGS. In Mac HyperCard exitField is sent to unlocked fields when the insertion point is removed without any text having been changed in the field. Scripting an idle handler, closeCard handler, and openField handler can be used to generate exitField if it is required. For scripting examples see the Readymade.Flds v1.1 stack by Brendan Bellina.

Entering/Leaving commands:

There is no close, suspendStack, or resumeStack messages in HCGS. There are closeStack, suspend, and resume messages though. To simplify Mac to HCGS conversion use handlers:

on close

closeStack

end close

on suspendStack

suspend

end suspendStack

on resumeStack

resume

end resumeStack

Locking Commands:

Mac HyperCard has the lock messages command and the lockMessages property, but HCGS only has the property so "lock messages/unlock messages" will not work in HCGS. Instead use "set lockMessages to true|false"

Locking Errors:

The HCGS lockErrors property is the same as the Mac HyperCard lockErrorDialogs property.

clickText functions:

HCGS did not have clickLine and clickChunk added until v1.1. clickText was never added to HCGS. Simulating clickText() with a function can be done, but "the clickText" will not work in HCGS.

ScreenRect:

The HCGS screenRect is always "0,0,320,200". The Mac HyperCard screenRect should never be this. This is one way to tell if a stack is being run on a GS or Mac.(For an alternative way see the "long name differences" section.)

Sort differences:

Later versions of Mac HyperCard enhanced the sort command to allow sorting containers rather than only sorting cards. The HCGS sort command only sorts cards. To sort the content of containers in HCGS you must use a sort function, the sortContainer XFCN, or the QuickSort XFCN. The VisiSort GS stack by Brendan Bellina published in Script-Central Special Edition v9n2 includes several sort functions and the QuickSort XFCN.

Note that the SortContainer XFCN uses ">" to indicate sort in ascending order and "<" to indicate sort in descending order, while the Mac HyperCard sort uses the words ascending and descending.

Find differences:

The HyperCard find command can indicate a specific field to be searched. In Mac HC that field can be either a card field or a background field. In HCGS it can only be a background field.

Card Properties:

Referencing the height or width of a card in HCGS results in an error. The height of a HCGS card is always 200 and the width is always 320.

Menus:

Menus are handled very differently (see the Substitutions section below). Although the doMenu command works for both, HCGS does not allow the "without dialogs" clause properly (despite Apple's HCGS Script Language Guide saying that it does.)

answer file of type:

Filetypes vary between HCGS and Mac HC. The most common difference is that HyperCard stacks in HCGS are type "stack", whereas HyperCard stacks in early versions of Mac HyperCard are type "STAK" and later versions are stack. However there is a bug in HCGS that HyperStudio stacks will also be returned by answer file when "stack" is specified. A workaround for this bug is to use the GetPrefix XCMD to select the HCGS stack since the XCMD correctly allows only the selection of HCGS stacks. An alternative to the XCMD is to use this function (which is however slower than GetPrefix):

function answerStack thePrompt

-- by Brendan Bellina 5/5/24

-- The answer file type of stack command does not distinguish

-- between HCGS and HyperStudio stacks. The Open Stack... command

-- does allowing this function to be used in place of using

-- answer file of type stack.

-- To populate both "it" and "the reply" properly use the format:

-- get answerStack()

-- A space will be appended to the end of the prompt to prevent

-- an issue if a stack with the prompt's name exists.

-- If no prompt is specified then "the stack" will be used.

-- The prompt will be preceded by "Where is " and followed by "?".

-- Note this function unlocks the screen, messages, and recent.

-- Alternatively use the GetPrefix XCMD by Michael Nuzzi.

put last word of the long name of this card into startStack

put last word of the id of this card into startCardID

push card

set lockScreen to true

set lockMessages to true

set lockRecent to true

if thePrompt is empty then put "the stack" into thePrompt

put space after thePrompt

go to stack thePrompt

if (last word of the long name of this stack is startStack ¬

and last word of the id of this card is startCardID) then

pop card into null

put empty into theReturn

else

get word 2 of the long name of this stack

get char 2 to (length(it) - 1) of it

put it into theReturn

pop card

end if

set lockScreen to false

set lockMessages to false

set lockRecent to false

return theReturn

end answerStack

Long name differences:

The long names of objects in HCGS always begin with a colon ":", but never in Mac HyperCard. This is true when getting the long name of a stack, or when selecting a file with an answer file dialog. For example, the long name of the Home stack for HCGS might be:

stack ":HD:HCGS:Stacks:Home"

and the value of "it" if the stack was selected with an answer file dialog would be:

:HD:HCGS:Stacks:Home

whereas the long name of the Home stack for Mac HyperCard might be:

stack "HD:MacHC:Stacks:Home"

and the value of "it" if the stack was selected with an answer file dialog would be:

HD:MacHD:Stacks:Home

(It makes no difference if a stack is on a Mac or ProDOS partition.)

Because the long name of stacks in HCGS ALWAYS start with a colon ":", and the long name of stacks in Mac HyperCard NEVER start with a colon ":", a certain way to determine if a stack is running on a Mac or IIGS is to examine the second character of the second word of the long name of the running stack (second char of second word of long name of this stack or char 8 of the long name of this stack). If it is a colon then you are running HyperCard GS. This function can be used:

function isGS

return (char 8 of the long name of this stack is colon)

end isGS

Pathname and open file differences:

As stated above, names of objects on the IIGS ALWAYS begin with a colon, and on the Mac NEVER begin with a colon. The same is true of pathnames. To open a file specifying the full pathname from a HyperCard GS stack the pathname needs to begin with a colon, for example,

open file ":HD:Documents:HCGS:Files:MyFile"

If the initial colon is left off a run-time error will occur causing the open file to fail. The following message will be placed into "the result" when the error occurs:

Couldn't create file "HD:Documents:Files:Myfile".

In a Macintosh stack exactly the opposite occurs. To open a file specifiying the full pathname from a Macintosh HC stack the pathname should never begin with a colon, for example,

open file "HD:Documents:HCMac:Files:MyFile"

If the path begins with a colon then a run-time error will occur causing the open file to fail. The following message will be placed into "the result" when the error occurs:

Can't create that file.

the scroll:

In Mac HyperCard the scroll of a field is returned in pixels. In HCGS the scroll of a field is returned in lines (a line as defined by the textHeight of the field, not return-delimited).

DoMenu without dialog bug:

Mac HyperCard 1.2.5 did not have the without dialog option in doMenu. This was added in later versions of Macintosh HyperCard. In HCGS it does not work with the "Clear Field" menu option and may not work with others as well.

pass bug:

In HCGS if a handler in an object tries to pass itself to another handler in the same object with the same name (for example, two mouseUp handlers in the same object), then the second handler WILL NOT receive the passed message. In Macintosh HyperCard the second handler WILL receive the message.

Important note: (10/14/23) I noted this bug years ago but I have recently been unable to prove that either Mac HyperCard 1.2.5 or 2.4.1 behave differently than HCGS, so this is likely not a bug in HCGS after all. It would be bad practice to have two handlers with the same name in an object anyway since that would likely lead to confusion.

Different standard fonts:

Macintosh HyperCard included Palatino and Chicago as standard fonts. The IIGS does not have Palatino or Chicago. The minimum standard fonts for HCGS are:

Courier 10, 12

Geneva 10, 12

Helvetica 10, 12

Shaston 8, 16

Times 10, 12

Venice 14

Additional bitmap fonts Apple provided for HCGS and present on a full install of HCGS include:

Courier 9, 14, 18, 20, 24

Geneva 14, 16, 18, 20, 24

Helvetica 9, 14, 18, 20, 24

Times 9, 14, 18, 20, 24

Venice 12, 24

MenuBar:

The HCGS menubar does not have top or bottom properties, but the Mac menubar does.

Keyboard Key differences:

The Mac Plus keyboard does not have the control key or function keys or escape key. The IIGS standard keyboard does not have function keys but the IIGS can use the Apple Extended Keyboard II that does have function keys. On an Apple II the paddle buttons 0 and 1 correspond to the command and option keys.

Going Back:

In HyperCard the key in the upper left corner of the keyboard immediately left of the "1" key does the Back command. If the keyboard also has an Escape key then the Escape key also does the Back command.

Pattern differences:

Mac HC allows 40 patterns numbered 1 - 40 with 12 being solid black and 2 being solid white. HCGS allows 32 from 1-32 of which the first 16 are solid colors and 1 is solid black and 16 solid white (in the standard palette).

Visual Effect differences:

Not all visual effects available for the Mac are available in HCGS. The stretch visual effect, for example, is only available in Mac HC. HCGS can use colors with certain visual effects like fade.

Mac HyperCard allows other stacks to be in the hierarchy between the running stack and the Home stack. This allows handlers, functions, sounds, and other resources in those stacks to be used without them having to be copied into the local stack or Home stack. HCGS lacks this ability. When converting stacks a Mac stack might refer to another stack or expect another stack to be in its hierarchy, so in those cases any additional resources must also be copied into the HCGS stack.

Mac HC 2.3 has the Darken and Lighten paint options. These are not available in HCGS but can be mimicked using handlers by Brendan Bellina in the BackgroundArtGS stack released on Script-Central Special Edition v9n4.

----------

When converting stacks consider the following substitutions:

Substitute HCGS xfcn "XReplace" for Mac HyperCard XFCN "Substitute" or "Replace". (Note that XReplace can replace strings with strings whereas Substitute can only replace a single character with a single character.)

Substitute HCGS xfcn "addpopup" for Mac HyperCard popup buttons.

Substitute HCGS xfcn "addmenu" for Mac HyperCard create menu command.

Substitute HCGS xcmds "enableMItem" and "disableMItem" for Mac HyperCard enable/disable menuItem commands.

Substitute the HCGS enable/disable and isEnabled functions (in the stack script) by B. Bellina for the Mac HyperCard enable/disable commands.

Substitute the HCGS existsObj function (in the stack script) by B. Bellina for the Mac HyperCard "if there is" phrase.

Substitute the HCGS existsCard function (in the stack script) by B. Bellina for the Mac HyperCard "if there is" phrase

Substitute the HCGS search function (in the stack script) by B. Bellina for the Mac HyperCard Search xcmd.

For sorting a container use the sortContainer XFCN from the Scripter's Tools stack.

The KeyDown command does not exist in HCGS. This can be mimicked in some circumstances using an idle handler and the msg box.

Substitute HCGS hilitedBtn for Mac HC selectedButton when determining the selected/hilited button of a button family.

For answer file type "stak" substitute using the GetPrefix XCMD or answerStack function (shown in text above) by Brendan Bellina to select a HCGS stack since answer file type "stack" in HCGS incorrectly allows selection of HyperStudio stacks.

Substitute the clickLine, clickChunk, and clickText functions in this stack script which should work with all versions of HCGS. HCGS has no system clickText function though, so substitute clickText() for "the clickText".

The say command and other talking commands integrated with MacInTalk in HC are not present in HCGS. Instead use the Byte Works Talking Tools, the Speak XCMD, and the TextToSpeech function by Brendan Bellina.

There is no HCGS equivalent for Apple's Mac HC FontExists XFCN. To check if a font exists use the fontExists function (in the stack script) by Brendan Bellina.

The Mac HyperCard ability to mark cards for sorting and printing is not available in HCGS. This can be mimicked using a background field. Use the scripts by Brendan Bellina in the Lateral File Index template in the Stack.Templates stack published in Script-Central SE v7n1.

The Mac HC Darken and Lighten paint options are not available in HCGS. Use the handlers by Brendan Bellina in the BackgroundArtGS stack published in Script-Central SE v9n4.

Tilting at Pixelated Windmills

Thursday, February 26, 2026

HyperCard IIGS BugTracker documents

No comments:

Post a Comment