[README for MetaCard 2.5 Apr 18, 2003]

This document describes the differences between the current release of
MetaCard and earlier releases.  This document is derived from the beta
feature list, and so is in the reverse order that the features were
added (latest at the top).  You may read about a feature that is
modified from an entry farther down in the document.

Be sure to read the installation instructions in the file
README.install for more information on installing MetaCard.

===================== Mac/Carbon Engine Issues ======================

Known problems in the Carbon engine, some of which we may be able to
address when Apple gets around to finishing the Carbon API, some of
which it may never be possible to address.

1) Pulldown menus in dialogs and menu-panel menus use the MetaCard's
   internal menu display routines instead of the native menu manager.
   API support in Carbon is very weak in this area and so it may not
   be possible to change either of these.

2) Unicode is not supported for Mac system-menubar menus yet.

3) Due to limitations in Appearance Manager, it is not possible to
   print controls that are shaded (i.e., scrollbars,
   radio/checkbox/standard buttons, and option and tab menus).
   Workarounds include can use "import snapshot" to make images of
   them that will print, change the look and feel to something other
   than "Appearance Manager", or simulate these controls using other
   types of objects.

4) Rapid changes to onscreen objects may not always be visible on OS X
   due to the way that OS buffers window contents.  To force an update
   you can use "wait for 1 millisecond", or send a message to resume
   after a short interval and exit the current handler.  We are
   searching for an automated solution to this that doesn't seriously
   compromise performance for all other drawing.

5) You cannot initiate a drag of type "files" on a MacOS system.

================ Limitations and Incompatibilities =================
Known limitations, some of which may be addressed in the next release,
some of which it may never be possible to address.

1) The fonts on the various platforms are not all exactly the same size
   and proportion for a given face/size/style.  While considerable
   effort has been made to minimize these differences, some fields and
   buttons will have to be resized/repositioned to make them look right
   on all platforms.  Fortunately, the Helvetica 14 point font used in
   the development environment is are pretty close on all three
   platforms (the Win32 engine usually substituting the slightly
   narrower "Arial" font if Helvetica isn't available).

2) Conflicts have been reported between the Mac PPC engine's memory
   management architecture and memory management products like
   RamDoubler.  The workarounds for this problem are to disabling the
   memory utility or MetaCard's memory management system (instructions
   for making MetaCard behave like conventional Mac apps provided
   below in the entry marked TMEM).

3) Conflicts have been reported between the MetaCard and various virus
   protection products on Windows and MacOS systems.  If you
   experience any inexplicable behavior, especially relating to
   reading or writing files (including opening or saving stacks) or
   processes (shell/launch/open process), please try disabling this
   other software to see if that solves the problem.
 
4) MetaCard is very good at exposing bugs in the drivers for graphics
   cards.  These problems seem to be most frequent in Windows 98, but
   can plague any Windows system.  The most common symptom are images
   or cursors that draw in the wrong colors or with the mask and data
   reversed, and bits of windows left on the screen when they are
   closed or moved.  Be sure you have the latest drivers from the
   vendor of your graphics card.  If the problem still exists with
   those, try turning acceleration to its lowest level.  If that
   doesn't fix the problem (or even if it does), please report this
   bug to the vendor of your graphics card.

6) Patterns (e.g., the backPattern property) are not printed correctly
   on MacOS systems, nor can they be used to draw text on Windows or
   Mac systems.

7) The "scale" and "progress" styles of scrollbars default to the
   Motif look and feel if oriented vertically in the Windows 95 and
   Macintosh look and feel settings.

8) There are system-specific bugs in the sound recording components of
   QuickTime.  Some systems work perfectly, others don't.  There are
   unfortunately no workarounds other than restricting the target
   platform to those that don't have these problems.

Please report other bugs/conflicts to support@metacard.com.

******************** MetaCard 2.5 release notes **********************

The params() function now returns parentheses around the arguments
when called from a function, a change made to improve HyperCard
compatibility and to enhance the Message Watcher.

The fontNames() function now takes an optional argument "printer" that
will return the fonts available on the currently selected printer.

The matchText(), matchChunk(), and replaceText() functions are now all
*case sensitive*, even when the caseSensitive property is set to
false.  This change was required to fully support generic character
types and other PCRE extensions (e.g., \W to match non-words and \D
for non-decimals).  To get the old behavior back, prepend the option
"(?i)" to the regular expression, which forces a case insensitive
match on all literal characters.

The uniEncode and uniDecode functions now accept an optional second
parameter that will be used to to convert to/from multibyte character
representations on those platforms that support this.  For example,
uniEncode(field 1, "japanese") will output a 16-bit character string
translating any multibyte characters in the original input to their
Unicode equivalents.

The uniEncode and uniDecode functions now return data in a
platform-specific byte order, which is required to use these functions
with the new unicode display capability.  Use the binaryEncode()
function if you need to convert to a platform-independent encoding.

A SIGTERM signal sent to the UNIX (including Mac OS X) engines causes
a shutDownRequest message to be sent to the defaultStack.  Passing the
message causes a normal exit, not passing it causes the signal to be
ignored.

The constant "lf" was added.  It has the same value as "CR", which is
ASCII 10.

Drag and drop is now fully implemented, though there may still be
changes to the API during the beta test period.  You can now drag from
other apps and drop on the MetaCard app and vice versa.  The following
messages, properties, and functions are supported:
  dragStart is sent when an selection in a field is dragged.
      Not passing dragStart suppresses the automatic drag.
  dragEnd is sent 
      Not passing dragEnd suppresses the automatic deletion of the selection 
  dragEnter is sent when a drag enters a control.
  dragLeave is sent when a drag leaves a control.
  dragMove is sent to the control under the mouse when dragging over it.
  dragDrop is sent when the user drops on a control.
  The acceptDrop property governs whether a drop will be accepted.
     The default is for unlocked fields to accept dropped text, and all
     other objects to not accept anything.  This property should be set
     in a dragEnter handler.
  The dragData property contains the data dropped.  This property can
     also be accessed as an array (e.g., the dragData["text"]), but
     defaults to "text" if no type is specified.
  The dragSource function returns the long id of the drag source.
  The dragDestination function returns the long id of the object dropped
     on.  It is only valid during the dragDrop and dragEnd messages.
  The dropChunk function returns the character index where text was
     dropped in a field.
  Keys(the dragData) returns a list of the types of data in the dragData.
     Currently only "files" and "text" are supported

Block commenting using /* */ as delimiters is now officially supported
(this feature has actually been available since 2.4.1, but was just
never documented).

mouseEnter/mouseLeave messages are now sent when moving or changing
the visibility of a control changes the control at the current
mouseLoc.

The clipboardData property can be used to get or set the data on the
clipboard directly without having to use cut/copy/paste.  To set data
of a particular type, use an array format:
set the clipboardData["text"] to "some text"

The precedence of the "there" operator has been changed to that of the
other unary operators.  This shouldn't cause any backward
compatibility problems for fully parenthesized expressions, but you
should check any expressions of the form "there is a <a> and there is
a <b>" to make sure they do what you intended.

The engine will now no longer exits automatically when all windows are
closed if there are pending messages.  You must cancel pending
messages for a stack when it closes or use the "quit" command to force
the engine to exit.

The "boundingRect" property fixes the scrollable area of a group such
that it doesn't resize when controls are moved to the edge of the
group.  Groups also now automatically scroll when an object within
them is moved using the pointer tool.

The "ask" command now accepts [information | question | error |
warning] as modifiers in addition to password and file, and displays
the appropriate icon in these cases.

The shell() function now returns empty instead of 0 if there is no
error.

"rectangle" style buttons now draw using Aqua routines on MacOS unless
the backColor or backPattern of the button has been set.

Setting other properties in a setProp handler now calls the setProp
handler for those other properties instead of setting them directly.

Keys in array custom properties are now properly translated when a
stack is saved on a different platform.

Object's with cantSelect set to true now behave as if they have the
browse tool chosen rather than just being ignored as in previous releases.

The ask, answer, and "open printing with dialog" commands now all take
an "as sheet" parameter which will open the dialog as a sheet on OS X.
This parameter has no effect on other platforms.

The "sheet" command opens a dialog as a sheet on OS X, and as a modal
dialog on the other platforms.

Default-style buttons now throb appropriately in the Mac OS X engine,
but due to limitations in the API (i.e., there is no support for
animation in Appearance Manager), they only draw correctly when placed
directly on dialog backgrounds and not when placed on top of other
controls.

Fields now fully support unicode fonts, including input.  To set a
unicode font, append ",unicode" or ",language" to the textFont (e.g.,
"Arial,japanese").  Setting the font of a field or selection within
the field and then selecting in that range of characters will open the
platform-specific text input tools, set to input characters in that
language.  This information is retained accross getting/setting the
htmlText.

Buttons can display Unicode in their labels if their fontName property
is set as above.

Fields now support cut/copy/paste of styled text.

The rtfText property of fields can be used to get and set the styled
text of that field in RTF format.

The unicodeText property of fields can be used to get and set the data
in the field as UTF-16 (16-bit Unicode) characters.

The debugging UI and script-language API has been entirely redesigned
to improve performance and usability.  As previously, though, the only
documentation on the API is available in the development environment
scripts.  The core UI features consist of:

  You now set breakpoints directly in the script editor by clicking in
  the column to the left of the script editor field.

  Once you've hit a breakpoint, you can run/abort/trace/step using the
  new "Debug" menu items or their keyboard accelerators.

  When you've hit a breakpoint, the "Execution Contexts" and "Variable
  Watcher" will show the state in the current context.  Clicking on
  the different lines in the "Execution Contexts" dialog allow you to
  see the call stack that led to the current script statement and the
  values of the variables in each of those contexts.

  You can view and change the value of variables in the current
  context using the "Variable Watcher".  Clicking in the column to the
  left of the variable names sets a watch on that variable, and a
  dialog opens so that you can specify an expression.  Canceling out
  of that dialog will cause the debugger to stop any time that
  variable is changed.  If you supply an expression, the debugger will
  only stop when that expression evaluates to true.  

  The "Message Watcher" shows messages as they are sent with the
  option to filter messages based on type, message name, and whether
  the message was handled or not.

******************* MetaCard 2.4.3 release notes *********************

The messages "suspend" and "resume" are sent when the application
loses and gains the keyboard focus, respectively.

The major feature implemented in this release is that the Carbon
engine for OS X is now a Mach-O format executable, which enabled it to
use many of the features from the UNIX engines:
  1) The shell() function can be used to run subprocesses.
  2) "write <d> to stdout" and "read from stdin until eof" are now
     supported, making it possible to use this engine to develop CGIs
     with Apache or other UNIX-based HTTP servers.
  3) Signals can now be used (the "kill" command, and the "signal" message).
  4) The full UNIX file system can now be accessed.  The downside of
     this is that paths *must* now be in UNIX form and not the old
     MacOS form.
  5) Unix time and date functions are now used for greater accuracy
     and efficiency.
  6) Quartz drawing is used for all text in OS versions 10.1.5 and
     later, which means it may look and format differently from the
     same text displayed in the PPC engine run on older Mac OS
     versions.

The operation of datagram sockets has been changed on all platforms.
In previous releases it was not possible to read and write to the same
datagram socket.  Now, you can do a single "read from socket <s> with
message <m>" on the client datagram socket after opening it and all
packets that arrive on that socket will send message <m>.  On the
datagram server side, when a new packet arrives, a new socket that has
the client address will be opened.  You can then write to this socket
to send a message back to the client, or immediately close it if only
new incoming packets are needed.

The new dnsServers function returns a return-delimited list of the DNS
servers configured on the current system.

The new driverNames function returns a return-delimited list of the
serial device drivers installed on a Mac OS X system.

Externals must now be in Mach-O bundle format on Mac OS X.  Updated
projects are included in the Mac OS X package.  Rather than load from
the resource fork of a stack, externals must be kept in separate files
and are loaded using the stacks "externals" property as they are on
Win32 and UNIX platforms.

******************* MetaCard 2.4.2 release notes *********************

The crop command changes the rectangle of an image without scaling the
image data.  If you crop to a smaller rect, image pixels will be cut
off, and if you crop to a larger rect, blank pixels will be added.

Sound recording has been completely rearranged in this release.  The
new support is as follows:
  "record sound file <f>" is now the only supported syntax to start
   recording.

   "answer record" opens a dialog that allows the user to select
   recording parameters such as compression and the sampling rate.

   The properties recordRate, recordSampleSize, recordChannels, and
   recordCompression can be set directly prior to recording, or
   queried after the "answer record" command completes to get the user
   selections.  The supported values for each of these properties can
   be determined from the "answer record" dialog on the target
   platform.

   The recordCompressionTypes function returns a list of the supported
   codecs on the current platform.

   The recordInput parameter can be set to any of the following to
   specify the recording input source:
	"cd  " for the internal CD player input
	"emic" for the external mic input
	"irca" for the RCA jack input
	"tvfm" for the FM tuner
	"idav" for the DAV analog input
	"imic" for the internal mic input
	"mbay" for the media bay input
	"modm" for the modem input
	"zvpc" for the zoom video input

   The recordFormat property can be set the "wave", "aiff", "ulaw", or
   "movie", which determines the file format that will be used to
   store the audio data.  Note that not all codecs are supported for
   all formats, and that only uncompressed audio (the "raw " codec)
   and "ulaw" formats can be played back using the built-in play
   command.  QT will automatically change the compression if you try
   to save a file of the wrong configuration, but you can use a
   program like QT Pro to determine which file format/code
   combinations are supported.

   The behavior of the "recording" property, the recordLoudness
   function, and the stop recording commands are unchanged.

The defaultCursor property can be used to set the browse-tool cursor
to something other than the standard hand cursor.

The Carbon engine now deletes the last two lines in the first menu
(the "File" menu by HIG standard, in which the last two lines are a
separator and "Quit") automatically to eliminate the duplication the
"Quit Application" item in the Application menu.  If your application
was previously doing this with a script, you need to remove the lines
that do this.

Compatibility with OpenLook Window Manager (formerly the default
windowing system on Sun systems) has been removed because it causes
problems with current versions of Gnome and KDE.

The "mouse" function is now async rather than event based as in
previous releases.  This means that "the mouse" will only return
"down" if the mouse is actually down at the exact instant the function
checks it.  See the new information in the MetaTalk Reference for more
details.

Images now support the "angle" property which can be used to
non-destructively rotate an image (the existing "rotate" command is a
painting feature, and so permanently changes the actual pixel values
in the image).

Stacks now support a windowShape property which can be set to the ID
of any masked image and that mask will be used for the window shape.
This feature works on all platforms.

Multiple externals are now supported on Win32 and MacOS systems.  On
Win32, just set the externals property of a stack to a multiline list
of the DLLs to load.  On MacOS systems, multiple CODE resources can be
included in a stack file.  The set that will be loaded for a given
platform depends on the ids of the resources.  The value of the id mod
3 is used to select the externals for a given platform as shown in the
following table:
0 - PPC
1 - 68K
2 - Carbon

The deleteRegistry function will delete the specified key from the
Windows Registry, returning true or false depending on whether the key
was deleted or not.

The constantNames() function returns the list of predefined
constants.

Handler parameters are now checked against the list of functions and
properties and flagged as script errors if a match is found.

Many changes have been made to HTML import and export, QT support (the
player object), and error reporting.  These all involved bug fixes and
should have minimal compatibility impact, but be sure to test these
features in your application if you rely on particular undocumented
behavior. 

Path names longer than 255 characters are now fully supported on
MacOS.

MacOS menus now support escaped characters (e.g. "\(" will appear as
"(" in a menu item instead of disabling that menu item as it did in
previous releases).

Mouse wheels are now supported on MacOS X.  As on Win32 and UNIX,
a rawKeyDown message is sent to the target field, and they scroll
automatically if it is passed or not handled.

Printing of stacks with menu bars now only prints the area below the
menubar on MacOS.

This release uses a new Perl-compatible regular expression library.
This library includes new support for Perl pattern characters and
non-greedy matches.  Any Perl regular expression reference can be used
for documentation (http://www.perldoc.com/perl5.6.1/pod/perlre.html is
a good one).

The grid lines in fields have been changed to draw using the
borderColor property instead of the hiliteColor.

When the a field has a vertical grid, text is now truncated within a
"cell" rather than being pushed off to the next tab stop location.

Holding down the control key (command key on MacOS) while
double-clicking on a stack now will start up MetaCard with the full
development environment if the engine can find it.

The recursionLimit property allows you to adjust the limit on the
depth of recursion for function calls, decreasing it for quicker
failure during development, or increasing it if you require more depth
to execute a recursive algorithm on a larger data set.

The currentTimeChanged message now includes the new time as a
parameter.

The new "long owner" owner property returns the long name of an
object's owner.  Note that it's still safer to get the long id of an
object and delete the first 4 words to get an unambiguous reference to
the owner.

The hilitedLines property of fields can now only be used with fields
with listBehavior set to true.  It sort of worked in previous
releases, but couldn't be set and failed in several special cases,
making it unreliable and so unusable.

The new lineDelimiter (abbreviates to "lineDel") property can be
changed to use a different character for line chunk expressions.

******************* MetaCard 2.4.1 release notes *********************

Error reporting has been reworked to improve accuracy of error reports
and provide information in cases like "send .. in" where no errors
were reported in previous releases.  Most of these changes should not
affect applications developed with MetaCard with one exception: you
now must "start using" the execution error dialog to have errors
reported outside the development environment.  The resource mover has
been modified to optionally make the required changes to the stack
script.  The execution error dialog itself has been modified to make
use of this new information (you can select different lines in the
error message field and open the script editor to each line in the
error traceback).

A number of changes have been made to the player object, including
having it not pause when the user clicks in a playing movie.  A player
bug still remains with QT 5: the controller thumb does not always
update properly while a movie is playing.  The workaround is to do
something that will force the controller to be redisplayed.  For
example settting the showController false in a preOpenCard handler and
back to true in an openCard handler.  Or do the reverse with the
alwaysBuffer property.  We are awaiting word back from Apple on a
better workaround.

The getResource(<path>, <type>, <name>) function returns the binary
data in the resource specified.  The <name> parameter can be either
the name or the id of the resource.

The setResource(<path>, <type>, <id>, <name>, <flags>, <data>)
function puts <data> into the resource specified.  If either the <id>
or <name> property is empty, it will update an existing resource
without changing its id or name.  The <flags> parameter can contain
zero or more the following characters in any order S (System heap), U
(pUrgeable), L (Locked), P (Protected), R (pReload), and C (Changed).

The getResources function has been modified to include the <flags> as
described for setResources as the last item, and to return the values
in the same order required for the setResource function (type, id,
name, flags).

The tag returned for chunks with "link" textStyle with no linkText
property has been changed for the htmlText property.  It was <link> in
2.4, but this was incompatible with the HTML specification and so has
been changed to <a>.  If you have saved off htmlText edited in
MetaCard 2.4, you'll need to use the replace command to replace <link>
with <a> and </link> with </a> before setting the htmlText of a field.

Processes started with "launch" and "open process ... for neither" are
no longer killed when the engine exits.  Processes opened for
read/write/update still will be to avoid littering the system process
table with zombies.  Use the kill command to kill each line in the
openProcesses if you want to make a clean exit.

******************** MetaCard 2.4 release notes **********************

An control's showFocusBorder governs whether a focus border is drawn
around the control when it has the keyboard focus.  It can be used to
suppress the focus border drawn around fields in the Macintosh look
and feel, and all objects with the Motif look and feel.

The recordFormats function returns a list of the audio compression
format supported by the version of QT installed on the current system.

The following new callbacks have been added to the external API:
GetVariableEx, SetVariableEx, GetArray, and SetArray.  These functions
support passing binary data directly between the external and the
engine, improving performance and simplifying implementation.  A new
external tutorial provides examples of their use.

The hiliteColor and focusColor properties now default back to current
OS settings if they are not set anywhere on the inheritance path.
Note that as shipped in previous releases, the Home stack had these
properties set, and you'll need to clear them to see the proper colors
in your stacks.

The MacOS engine now supports emacsKeyBindings behavior via the
control key instead of via the command key as in previous releases.

A new modifier to the repeat keyword (for each element) can be used to
simplify and improve performance of scripts.  For example, to loop
over all the elements in an array variable named "a1", assigning
variable tElement to each one in turn, use:
repeat for each element tElement in a1

The keysDown() function returns a comma-delimited list of the keysyms
for the keys that are being held down on the keyboard.  The values are
the same as passed with the rawKeyDown message.

The properties "arm" and "hilite" have been changed to "armed" and
"hilited".  The old names will continue to work as synonyms.

The properties "showGroups" property and functionality have been
merged into the "underlineLinks" property.  The old name will continue
to work as a synonym.

Buttons now have a wider range of icon properties to make state-based
display easier.  The full set is: armedIcon, disabledIcon, hilitedIcon,
icon, and visitedIcon.

Buttons and text strings in fields now have a "visited" property.

The "backdrop" property can now be set to the id of an image, just
like the icon property of buttons and the backgroundPattern property
of all objects.  Messages "mouseDownInBackdrop" and
"mouseUpInBackdrop" are now sent to the current card of the
defaultStack when the user clicks in the backdrop window.

The "address" function now returns simply machinename:executablename
on all plaforms (it did this before on Windows and UNIX platforms, but
because Appletalk zones are no longer supported on MacOS, it has been
removed from that platform as well).

The abbreviation "img" is now accepted for the "image" control type.

The MacOS engine now uses Appearance Manager calls to draw standard
controls by default on all OS versions 8.5 and later.  This change was
required to support OS X standard controls, which are very complex and
difficult to emulate.  Unfortunately drawing using the OS routines
requires more memory and is *much* slower than using the older,
emulated, look and feel routines.  It also means that setting
properties like opaque and backgroundColor will have no effect for
these controls.  The older look and feel is still available by setting
the lookAndFeel property to "Macintosh" instead of the default
"Appearance Manager".

The Win32 and MacOS engines will use the system default background
color/pattern if the backColor and backPattern of all objects on the
inheritance path (including the Home stack) are set to empty.

Support for URL access other than "file:", "binfile", and "resfile"
have been moved out into a script library named "libURL" that you must
start using before you can access these types of URLs.  This new
library supports FTP in addition to the HTTP support in previous
releases as well as new support for file-based proxies, keep alive
connections, and other new features.  HTTP proxies should now
automatically be detected on MacOS systems.
The "answer effect" command opens the QT effects dialog and returns
an effect description which you can pass to the visual command to execute
the desired custom effect.

QT is now used by default for visual effects, which should improve the
quality for most of them.  You can now specify the effect name or 
four-character-code in quotes.  The new command syntax is:
visual [effect] <name, 4CC, or qt effect description> 

The "answer effect" command opens the QT effects dialog and returns
an encoded effect description that can be passed to the "visual"
command.

The new "qtEffects" function returns a list of the available effects.

The command "record sound file <f> [as 4CC <code>] [with dialog] [with
<q> quality]" records a sound to the file specified by <f> with
optional quality "good", "better", or "best" (default is "good").
Recording continues until the command "stop recording" is executed.
If a a 4CC (such as "ulaw") is used, the sound is compressed to that
format.  The "with dialog" option causes a dialog pops up before
recording that prompts the user for settings.

The recordLoudness() function returns the amplitude of the current
signal at the microphone port.  The recording() function returns
whether a recording is currently taking place.

The "answer color" command opens the OS-specific color chooser dialog,
and returns the chosen color in "it".

The "merge()" function evaluates commands and expressions embedded in
a string and replaces them with the resulting value.  For
compatibility with SuperCard/Flamethrower, expressions start with "[["
and end with "]]".  Statements are delimited with "<?" and "?>".  You
must use "return" with statement to return a value:
put merge("3 + 5 is [[3 + 5]] and 2 + 2 is <?return 2 + 2?>")

There are several new field features:
  Fields now support embedded images and hidden text.  To embed an
  image, set the "imageSource" property to the name, id, or URL of an
  image.  It always applies to a single character in the field, hiding
  that character.  The linkText property can be used to attach an
  arbitrary string to a section of text.  Both the imageSource and linkText
  properties are supported via the field's htmlText property.

  The "group" attribute for field text has been deprecated.  The new
  name is "link", and fields with this attribute appear in a different
  color as is the standard for WWW browsers.  They also hilite and
  show visited colors as is standard for browsers.  When the user
  clicks on one of these links a message "linkClicked" is sent to the
  field.  It has one parameter which is the linkText property for that
  run of text or the text itself if no linkText has been defined for
  that run.

  The colors used for links can be changed with the global and stack
  properties linkColor, linkHiliteColor, and linkVisitedColor.  The
  underlineLinks property enables or disables underline for these
  chunks.

  You can drag and drop a selection within a field.  You cannot yet drag
  and drop between fields or between MetaCard and other applications.
  This will be a high priority for the next release.

  Triple-click now selects a line in fields

Many new array features have been added:
  The "split <var> by <pd> [and <sd>]" command splits a variable up by
  a primary delimiter <pd> and an optional secondary delimiter <sd>.  If the
  secondary delimiter is supplied, the result is an associative array
  with the keys being the text before the secondary delimiter and the
  values being the text after.  If no secondary delimiter is supplied,
  a numerically indexed array starting with 1 is created.

  The "combine <var> using <pd> [and <sd>]" does the inverse of the
  split command, producing a single string from an array using the
  delimiters specified.

  You can now do numerical calculations on all elements of an array
  using the standard mathematical commands, functions, and operators.
  Most basic operations can be done either with a scalar or another
  array, but the arrays must have the same dimensions and that
  operations are done between elements with the same index/key.  The
  new matrixMultiply function does a true matrix multiplication
  (rotate, then multiply) on two numerically-indexed array variables
  and returns an array result without changing either of its
  parameters.

  The new commands "intersect <a1> with <a2>" "union <a1> with <a2>"
  work on the indices of the two arrays.  If both arrays have the same
  keys but different values, the value of array <a1> is preserved.

  The transpose() function swaps the order of the items in keys for a
  "multidimensional" array.

  The "extents" function returns a return-delimited list of minimum
  and maximum indices for each dimension of a numerically-indexed
  array.

  The new "median" function returns the median value of a list of
  numbers or an array.

  The new "stdDev" function returns the standard deviationof a list of
  numbers or an array.

New image features:
  Cut/copy/paste now supports image data and selections on Windows and
  MacOS systems.

  The "flip [image <i>] horizontal" and "flip [<i>] vertical" commands
  flip an image <i> or selection.

  The "rotate [image <i>] by <d>" command rotates the pixels of an
  image <i> or the current paint selection by the specified number of
  degrees.  The image will be expanded to accommodate the rotated
  rectangle unless its lockLocation property is set to true.

  The paintCompression property can be set to "png", "jpeg", "gif", or
  "rle" and governs how painted images are compressed for storage.  If
  the image has an alpha channel, it's automatically compressed in png
  format.  This property can also be used with image objects to
  determine which format their data is stored in.

  The jpegQuality property controls the quality (and file size) of
  JPEG images produced with the "export" command.  It ranges in value
  from 1 to 100.

  It is now possible to export GIF files with the export command, but
  a special key must be purchased to enable compression.  Contact
  info@metacard.com if you'd like more information on this feature.

  The alpha channel in PNG images is now fully supported, allowing
  variable transparency in images.  But note that the alpha channel is
  collapsed to a fixed 1-bit mask when an image is painted.

  Image objects now support the "blend" ink and have a blendLevel
  property that ranges from 0 to 100 and governs the relative
  contribution of the image pixel values to the drawn area.

  The imageData, maskData, and alphaData properties can be used to set
  the pixels that an image object displays.  The imageData is a
  sequence of 32 bit binary values, with 8 bits each for red, green,
  and blue.  The maskData is sequence of 8 bit values, which 0 being
  transparent and all other values being opaque.  The alphaData
  property is a sequence of 8 bit values with variable transparency
  from 0 (totally transparent) to 255 (totally opaque).

  You can now specify an image and export to a container instead of
  just to a file: "export <image> to <container> as <format>"

The new "backgroundBehavior" of groups governs whether it behaves like
a HyperCard background (card messages pass through it, it can be
accessed with "background" chunk expressions, and it is copied over to
a new card when one is created).  It defaults to false, but will be
true for all groups created in previous releases.

The command "record sound file <f> [with <q> quality]" records a sound
to the file specified by <f> with optional quality "good", "better",
or "best" (default is "good").  Recording continues until the command
"stop recording" is executed.  The recordLoudness() function returns
the amplitude of the current signal at the microphone port.  The
recording() function returns whether a recording is currently taking
place.

New file system commands:
  The command "create alias <d> to file <s>" creates an alias named
  <d> to an existing file <s>.

  The aliasReference function takes a file name as a parameter and
  returns the file that it points do if the parameter is an alias.

  The longFilePath() function returns the long file name of a short
  (8.3 format) filename on Win32 systems.  The shortFilePath()
  function does the inverse.

  The function "the detailed files" returns a comma-delimited list of
  file attributes including the urlEncoded file name, size, resource
  size, creation date, modification date, access date, backup date,
  user and group id, permissions, and creator code and file type.  The
  term "detailed" is a synonym for "long" and so can also be used with
  the date and time functions.

The waitDepth() function returns the current depth of waits (mostly
useful when using "wait for messages", but potentially also when using
"send .. in" and "wait").

New date features:
  The "date" function now accepts "system" and "internet" in addition
  the older modifiers "long", "short", "abbrev", and "english".  The
  "system" date is that specified by the LANG environment variable or
  system control panel.  The "internet date" function returns the date
  formatted to RFC 822, the format used in email headers and other
  Internet protocols. 

  The convert command now also accepts these new date format strings,
  and an optional "from" parameter that describes the source format
  for the date string:
  convert <date> [from <dateFmt> [and <dateFmt>]] to <dateFmt> [and <dateFmt>]

  The monthNames function returns a list of the month names for the
  current locale setting.  It can be modified by
  long/short/abbreviated just like the date function itself.

  The weekDayNames function returns a list of the days of the week for
  the current locale setting.  It too can be modified by
  long/short/abbreviated.

  The dateFormat function returns a format string for the current
  locale in the format specified for the ANSI C strftime() function.

  The local property "useSystemDate" sets the default return value for
  the date function.  If set to true, "the date" returns the same
  value as "the system date".

You can now execute strings using other OSA languages on the Mac via
"do <s> as <l>".  You can get a list of the available languages for
<l> with the "alternateLanguages" function.

The specialFolderPath() function takes a name as a parameter and
returns the path to that folder on the current system.  The supported
folder names on the Mac are "Apple", "Desktop", "Control",
"Extension", "Fonts", "Preferences", "Temporary", and "System".  On
Windows systems, the supported names are "desktop", "fonts",
"documents", "start", "system", and "temporary" (none are case
sensitive).

The player object now will accept URLs in its fileName property, which
will cause QuickTime's internal networking routines to download and
play the file.  This also allows playback of streaming video.

****************** MetaCard 2.3.2 release notes **********************

The HyperCard-compatible properties scriptTextFont and scriptTextSize
have been added, and the standard script editor dialogs modified to
honor these settings.

The "ask file" command now prompts the user about overwriting an
existing file on all platforms.  Previously it only did this on Mac and
on UNIX systems when using the "save as" menu.

A significant change has been made to low-level event handling in the
Win32 engine to work around a long-standing bug in timer handling in
all Windows operating systems.  There should be no impact on existing
stacks, but as with any major change, keep an eye out for problems
related to it.

You can now set the layer of objects in groups, and even move objects
into and out of groups by setting their layer properties
appropriately.  This feature is turned off by default but can be
enabled by setting the "relayerGroupedControls" property to true.

A shutDownRequest message is now sent when the "quit" command is
executed.  If you don't pass the message, the quit is aborted.

The "export" command now accepts "jpeg" and "png" in addition to
"paint" to export those other formats.  The JPEG display routines now
use the standard library from the "Independent JPEG Group", which
supports progressive JPEG and other JPEG features not supported in
previous engines.

The global "windowBoundingRect" property specifies the rectangle in
which all windows must open.  By default it is the same as the
screenRect minus the size of the menubar (on Mac) or task bar (on
Windows), but can be made smaller to support UI features like tool
bars.

The "wait" command takes an optional clause "with messages", which
allows normal event dispatching to occur during the wait.  You can
also wait for a single message (or all currently-queued messages) to
be dispatched with the command "wait for messages".  This is a
powerful feature that can be used to simulate multi-threading without
all the work of using "send .. in", but you must be very careful to
avoid rentrancy: if the handler that calls "wait .. with messages"
gets called again as a result of one of those messages, an infinite
loop will occur.

The player object has several new properties and messages:
  The "playloudness" property changes the volume of the player, and
  returns the value the user selected using the volume slider in the
  QT controller.

  The "nodes" property returns a list of the nodes in a QTVR movie
  with an "id,format" line for each node where id is a number and
  format is either "object" or "panorama"

  The "currentNode" property can be used to get or set the id of the
  current QTVR node.

  A "nodeChanged" message is sent when the user changes the current
  node in a QTVR movie.  It includes a single parameter, the new node
  id.

  The "hotSpots" property returns a list of the hot spots in the
  current node of a QTVR movie, with an "id,type" line for each
  hot spot where id is a number and type is one of "link", "url", or
  "undefined".

  A "hotSpotClicked" message is sent when the user clicks on a hot
  spot in a QTVR movie.  It includes a single parameter, the hotspot
  id.

  The "mediaTypes" property returns a list of the media types in
  a Quicktime movie and will be one or more of "video", "audio",
  "text", "qtvr", "sprite", "flash".

  The "constraints" property returns three lines with the minimum and
  maximum values for pan, tilt, and zoom for a QTVR movie.

  The "pan", "tilt", and "zoom" properties of a player govern the
  current view in a QTVR movie (zoom is also know as "field of
  view").

  The "trackCount" property returns the total number of tracks in a
  movie.  The "tracks" property returns a return-separated list of the
  tracks in a movie, with a "id,type,starttime,endtime" line for each
  track in the movie.  The "enabledTracks" property can be used to get
  or set the list of enabled tracks using a return-delimited list of
  the track ids.

New date functions and behavior:
  

****************** MetaCard 2.3.1 release notes **********************

The message "quitMC" has been changed to "shutDown" to remove
MetaCard-specific terminology from the language and to improve
semantic compatibility (the startup message is "startUp").

The message QTDebugStr is sent when some event causes a QT movie to
execute the DebugStr action.  The parameter to the message is whatever
string was supplied to the DebugStr action when the movie was
created.  This message can be used to determine when the user clicks
on a specific object or area in a QT movie.

The Mac engine now support Navigation Services for file selection.
You can disable this feature and use the old Standard File dialog by
setting the dontUseNS property to true.

You can disable QuickTime on Windows and MacOS by setting the
dontUseQT property to true.  This is of limited use on the Mac, but
can be use to test operation of your stack using only the built-in MCI
routines on Windows.  Note that this property must be set *before* the
first operation that uses QuickTime is performed.

The formatForPrinting stack property should now work properly with all
types of printers.

The full range of 16-bit characters can now be displayed on Windows
systems, though you still have to enter them with scripts using the
htmlText property or the numToChar() function.

Setting the text properties of an object to the same values as its
parent object no longer causes the object to automatically start
inheriting from the parent.  Instead you must explicitly set the
textFont property to empty to cause the object to start inheriting its
font from its parent.

The drives() function returns a list of the currently mounted
drives/volumes on Windows and MacOS systems.  The volumes() can be
used as a synonym.

The groupIds property returns a return-separated list of the groups on
a card.  This is similar to the groupNames function, but works even in
the case of two groups having the same name.  Similarly, the new
cardIds property returns a list of the ids of the cards in a stack.

Searching for stacks listed in the stackFiles property now works from
the fileName of the stack with that property set, rather than from the
current directory as was the case in previous releases.

The player object now supports the traversalOn property which governs
whether it can be controlled with the keyboard.

The movieControllerID property of the player object returns a pointer
to the movie controller of a QuickTime movie as an integer.

A larger-than-usual number of changes in behavior of the object and
scripting language have been made to improve compatibility with
HyperCard, SuperCard, or OMO, or to improve operation of Cross World's
new development environment.  This may just be a point release, but
you should test your applications for compatibility as if it were a
major release.

******************* MetaCard 2.3 release notes ***********************

One of the new features in this release has been found to cause
backward compatibility problems in stacks that use a particular
scripting technique.  In previous releases, it was perfectly
acceptable to use the same name for both a variable and a custom
property.  This no longer works in 2.3 because you can now use a
variable anywhere a custom or standard property would be used.
Because this problem can be difficult to diagnose in stacks created
with older releases, we are looking for ways to either eliminate it or
at least to make it easier to find.  Suggestions are welcome at
support@metacard.com.  In the mean time, this new problem reinforces
the need to have a consistent naming system for variables, including
putting some sort of prefix on them to indicate their type (e.g.,
paramters are pWhatever, locals are tWhatever or lWhatever, and
globals are gWhatever).

The MacOS PPC, Win32, Linux, Solaris, SGI IRIS, and HP9K700 engines
have been built for this release.  Engines for the other platforms can
be made available by request.  If you have a particular platform that
you'd like to see supported during the beta phase, please send your
request to support@metacard.com.  All the standard stacks are
included.  To license, either copy over your existing mchome.mc stack
or relicense the new one using your old name, organization, and key
information.  Note that the sound, image, and movie files for the demo
stack aren't included in this distribution.  Copy the "demo" directory
from your 2.2.X installation to the directory you've installed this
release in if you want to review the demo.

The order of the items in the "margins" property has been changed to
make it compatible with the "rect" property.  The order is now left,
top, right, bottom.

The "long name" and "long id" properties now return the fileName of
the stack as the last word instead of the name as in previous
releases.  Also, the mainStack has also been added to the path if the
object is in a substack.  These changes have been made to reduce the
incidence of getting the wrong object when multiple stacks with the
same name have been loaded at the same time.

The fontName property now allows selection of Unicode fonts on Windows
NT by appending a ",W" to the font name (e.g., "Helvetica,W").  While
this isn't the most elegant solution (something better is planned for
2.4), it does allow displaying the full range of characters on that
platform.  Note that only display is supported with this font setting:
Text editing doesn't work properly with it.

A "print script" option has been added to the script editor, and a
stack with the "printField" handler it uses has been added to the
tools stack.

This is largely a bug-fix release, but a few changes to the UI have
been made, including the addition of numerous keyboard shortcuts
(e.g., command-tab to switch tools, esc and enter keys to close
dialogs, and improved compatibility between emacsKeyBindings and OS
standards).

The "open socket" command now takes an optional "with message"
parameter that can be used to determine when a connection has been
established.

The functions hostAddress and peerAddress return the IP addresses of
the local and remote hosts a socket is connected to, respectively.

The md5Digest function computes a 128-bit (16 byte) MD5 digest of an
input parameter.  It can be used to determine if a large value has
changed without having to retain a backup copy of that value.

MacOS look and feel has been implemented for tab style buttons, and
for progress and scale style scrollbars.  The Windows look and feel
has been implemented for scale style scrollbars.

A new "constant" keyword can be used to declare constant values in a
script:
constant c1 = 3, c2 = 4

The "local" keyword now accepts initializers:
local l1 = 5, l2 = 6

The qtVersion function returns the current QuickTime version or 0.0 if
QT is not available.

A "selectionChanged" message is sent when the selection is changed in a
player.  A "currentTimeChanged" message is sent when the current time
is changed in a player.

The stackFileType property can be used to change the creator code and
file type of stacks when they're saved on MacOS systems.

This A5 release is primarily a bug fix release over A4 and only has
one new feature: a socketTimeoutInterval property that applies to all
socket operations.  If any operation on socket takes longer than the
number of milliseconds specified in the socketTimeoutInterval, a
"socketTimeout" message is sent to the object that initiated that
operation.  The object can either ignore the message (in which case
the interval is restarted), notify the user, or just close the
unresponsive socket.

Custom property arrays are now accessed and saved as "sets", separate
from non-array custom properties.  This means that the customKeys
property no longer returns array elements unless you pass the array
name as a subscript (as in "customkeys[arrayname]").  This
architecture greatly decreases memory and disk space requirements for
large indexes, and improves performance at some sacrifice in backward
compatibility.  You can get a list of the custom property sets on an
object with the customPropertySets property.  You can specify that all
custom property references should be taken out of a particular set by
setting the customPropertySet property to the name of that set.

It is now possible to use arrays with most commands and functions for
which this makes sense.  For example, you can now move complete arrays
from one variable to another with the "put" command.

You can get and set an array including all of the important properties
set on an object with the "properties" property.  You can also now
pass a variable name where a standard or custom property name would
normally go in an expression.

The new player object uses QuickTime to play movies and sound files on
Win32 and MacOS systems.  You can control the player with the start,
and stop commands (e.g., "start player <exp>").  Other features
include the properties:
  fileName - the movie to play
  showController - show the controller bar
  alwaysBuffer - draw movie into its own buffer, which allows playing
                 the movie behind other controls
  startTime, endTime - sets a selection
  showSelection - allows the user to see and edit a selection
  playSelection - play just the selected part of clip
  currentTime - get and set the current play time
  playRate - change playback speed and direction (set to -1 to reverse)
  callbacks - a return-delimited list of "time, message" format callbacks
  duration - the duration of a movie, in movie units (see timescale)
  timescale - the timescale of the move in units per second
  formattedWidth, formattedHeight - the natural size of the movie
  paused - get and set the paused state of the movie

A high-level socket interface is now available on all platforms.
These new features should allow third party developers to produce and
maintain packages that support all the key Internet protocols
including HTTP client and server, FTP client and server,
POP/IMAP/SMTP, and others.  A sample HTTP server is available in the
distribution directory to get you started.  Among the new features:
  open [datagram] socket [to] <host:port>
  close socket <host:port>
  write <exp> to socket <host:port> [with message <m>]
  read from to socket <host:port> with message <m>
  read from to socket <host:port> for | until <x> [with message <m>]
  
  The [with message <m>] option causes the command to return immediately
  and send message <m> with the data when the operation is complete.
  Without that parameter, execution blocks until the operation is
  complete.  When doing delayed reads and writes, there are also a
  couple of messages sent when the connection goes down or has an error
  (socketClosed and socketError).  The delayed messsages have parameters
  for <host:port> and the data read in the case of read.
  
  For servers, there is: 
  accept [datagram] connections on port <p> with message <m>
  The message comes with the source address and connection number, and
  creates a socket that you read, write, and close using the above
  commands.  For datagram sockets, the entire data is passed as a
  parameter with message <m>.  We're still discussing whether a
  connection number needs to be available in the client side, either via
  the openSockets() function or something that could be specified in the
  <host:port> string (sometimes you want to be able to open multiple
  sockets to the same host).  Suggestions about how this should work
  would be welcome.
  
  There are also a few utility functions:
  openSockets() - returns a list of the open sockets.
  hostName() - the name of the current host
  hostNameToAddress(<exp>) - Name to IP address
  hostAddressToName(<exp>) - IP address to name

The binaryEncode(<format>, arg1, ...) and binaryDecode(<format>,
<exp>, arg1, ...)  functions take Perl/Tcl format strings that pack
and unpack binary structures.  Especially useful when getting and
sending binary data over sockets.

Painting is now supported on Windows and MacOS in addition to UNIX.

You can now use arbitrary-sized patterns in non-rectangular shapes
with the Win32 engine on Windows 95/98 (it was limited to 8x8 or
rectangular shapes in previous releases).

The 64K limit on script length has been increased to 4 gigabytes.

The cantSelect property for controls governs whether they can be
selected with the pointer tool or only with scripts.

Memory management has been extensively reworked in the Win32 and MacOS
engines.  There should be minor performance improvements overall, but
performance improvements in the largest and longest-running stacks are
dramatic (we have degenerate cases that are over 20 times faster on
Windows and almost 35 times faster on MacOS).

Text-width calculations have been reworked on both Windows and MacOS.
Performance when putting text into fields that must be word-wrapped
has increased by anywhere from a factor of 3 to an order of magnitude.

The field pageHeights property returns a return-separated list of the
heights in pixels of the field as it would be broken into pages based
on its current height with no clipping.  The idea is that you set the
field height to that value, print, set the scroll to the value and the
height to the next value, print, and so forth.

The formatForPrinting property of stacks determines whether text
wrapping and position is controlled by printer or screen font width
tables in the Win32 engine.  Use "answer printer" to set up a printer
driver, then open a stack with this property set to true, then print
that stack.

You can now get and set the htmlText of chunks within a field.

You can get formattedRect, formattedWidth, formattedHieght,
formattedTop, and formattedLeft properties of chunks of text in a
field, making it much easier to do things that require figuring out
much text will fit in a given rect.

The "ask" and "answer" dialogs now take an optional string to show in
the title bar:
ask <prompt> titled <title string>

The answer command now takes an optional type parameter which allows
changing the icon shown:
answer [information | question | error | warning] <prompt> \
  [with <b1> [or <b2 ..]] [titled <exp>]

Unfortunately, adding the above features to ask and answer required
changing the engine/dialog API, so ask and answer and file selector
dialogs that you have moved into your stacks using the resource mover
will have to be deleted and new stacks moved over.  Likewise if you're
using a modified version of one of these dialogs from an earlier
release, it will need to be reworked in the process of upgrading to
2.3.  Hopefully the new features will eliminate the need for these
custom dialogs and so all you'll need to do is add a parameter or two
to the "ask" and "answer" commands in your scripts.

Another benefit of the new ask and answer architecture is that the
three undocumented properties used for engine/dialog communication in
previous releases have been replaced by the single documented property
"dialogData".  It will be recommended that this property also be used
in conjunction with the "modal" command to send data to the dialog and
retrieve data from it.

"answer folder" is now implemented on all platforms.

The buildNumber function returns an integer build number of the
current release (useful for distinguishing patch releases).

The constantMask property can be used to play back some multi-frame
GIF files that use non-standard compression techniques.

The deleteResource function deletes the specified resource from a
MacOS resource fork.

The secureMode property governs whether any scripts in the current
session can access files or run commands with shell() or open
process.  It can only be set to true, and once set can never be turned
off within a session.

Menus that are larger than the screen or that must be positioned such
that they are partially off screen now automatically scroll as needed
using MacOS-style scrolling arrows.

****************** MetaCard 2.2.5 release notes **********************

This is exclusively a bug fix release.  Areas where bugs were fixed
include printing images, the script debugger, message delivery, sound
playback, support for the mouse wheel on Windows, and several minor
problems in the development environment.  The starter kit limits were
also adjusted to allow 10 front and back scripts in addition to 50
stacksInUse.

****************** MetaCard 2.2.4 release notes **********************

This is primarily a bug fix release but a few performance improvements
are also included.  Areas where bugs were fixed include moving and
sizing groups, selections and tab handling in fields, error reporting,
printing, and menu behavior.

****************** MetaCard 2.2.3 release notes **********************

This is exclusively a bug fix release and includes fixes for problems
displaying PICT, JPEG, and animated GIF images, dynamic paths, and
error reporting.

****************** MetaCard 2.2.2 release notes **********************

This is primarily a bug fix release, but a few new features are
available:

1) all platforms include support for "launch <document> with <application>"
but this command is especially useful on the Mac.

2) The Win32 engine includes support for scrolling with the wheel on
the new wheel mice.  You can get the raw messages that do this with a
rawKeyDown handler.

3) The BSD engine is for FreeBSD and BSDI UNIX systems, which means
it is now possible to write CGI scripts in MetaCard on the OSs most
popular with commercial ISPs.

4) You can now delete global variables and individual array elements
with the delete command.

5) New messages "moveControl" and "resizeControl" are sent when the
user finishes moving or resizing a control with the pointer tool.

6) The MacOS engine now supports additional AppleEvent structures that
allow it to be used as a CGI engine with most popular HTTP servers.

****************** MetaCard 2.2.1 release notes **********************

This release will requires a different key from the 2.2 release in
order to implement a subscription model upgrade policy.

Messages no longer pass through the stack script of the first stack
opened when MetaCard is run without a Home stack.

Two new url types have been added.  The "binfile" type reads and
writes files in binary mode.  The "resfile" type allows reading and
writing the resource fork in the MacOS engine.

There is now a "line" graphic style.

The rename command can be used to rename files.

The bufferHiddenImages property governs whether hidden images
decompress their data into a pixmap even when they're hideen, reducing
memory requirements at the expense of performance.  Setting the
alwaysBuffer property of the image to tru overrides this property.

The capsLockKey function returns the state of the keyboard Caps Lock
key.

The charset property of a stack can be used to determine which
platform the stack was last saved on (useful if you need to
untranslate characters in the Symbol font).

The macToISO and isoToMac functions translate between the two
character sets.

The compress function compresses a string into a gzip-compatible
archive.  The decompress functions does the reverse.

The httpHeaders property can be used to supply custom headers in HTTP
requests for servers that require them.

The navigationArrows governs whether the arrow keys cause card
changes when no field has the selection.

The selectionMode property controls how objects are selected when
dragging a selection rectangle on the card.  The "intersect" mode is
the old default.  In the "surround" mode, only objects completely
surrounded by the selection rectangle are selected.

Setting the selectGroupedControls property to true allows you select
individual controls within a group without having to ungroup or go
into "edit background" mode.

The selectionHandleColor is the color used to draw the boxes around
the selected object.

The videoClipPlayer property supports renaming the standard XAnim
player to non-conflicting names.

The 64K limit on custom properties has been increased to 4 GB.

Button contents menus can now be used to build hierarchial (aka
cascading or pull-right) menus.  Using one or more "tab" characters at
the start of a button name will cause that menu item to be placed in a
submenu, with the depth of the submenu being determined by the number
of tabs.

Numerous improvements to the standard UI have been made, including an
improve system for prompting to save your work when exiting MetaCard,
and protection against deleting a group that appears on multiple
cards.

Numerous improvements to the engine have been made, including support
for millisecond timing on MacOS and increased performance on all
platforms.

******************* MetaCard 2.2 release notes ***********************
The technique of returning a value from a modal dialog using the
"return" command no longer works in 2.2.  It relied on the result not
being cleared between handler calls, which caused problems in many
converted HyperCard, SuperCard, and OMO stacks.  See the "modal"
command in the MetaTalk Reference for a workaround.

The focusedObject function returns the long id of the object with the
current keyboard focus.

A reloadStack message is sent when the user attempts to reload a stack
with the same name as a stack loaded previously.  This message is used
in the standard development environment to prompt the user whether to
destroy the current stack and open the new one.

Newly created stacks are made mainstacks by default (as opposed to
substacks of Home) and the user is prompted for a filename when the
stack is saved the first time.

Menu management has been reworked for the MacOS platform to be faster
and more reliable.

The stack scroll property can be used to determine how much a stack
has been scrolled to hide the stack menubar group on MacOS.

Cards now have a defaultButton property which returns the long id of
the button that should be activated when the return key is pressed.
In addition, this button will be activated automatically when return
is pressed and no object has the keyboard focus (a returnInField
handler will still be required to implement this behavior if a dialog
has an editable field).

A bad entry in the rawKeyDown table in Windows has been fixed.  If
your scripts were looking for page down, its value is now 65367.

The stack property dynamicPaths can be used to have messages sent to
objects added to the message passing hierarchy as the result of doing
a "go" to another card.  This is provided for HyperCard compatibility
and defaults to false.

Scaled images now print at full image resolution rather than at card
resolution.  This feature is not supported for images with masks
(i.e. it doesn't work with transparent GIFs or PNGs).

The Win32 engine now runs properly on Windows 98.  There are a large
number screen driver bugs in Windows 98, however, which makes running
MetaCard on that release an iffy proposition (invisible icons and
cursors are the most common problems, but in some cases garbage
appears on the screen when opening windows and dragging objects
around).

Improved printing on Windows.  You must still set a large right margin
on fields when printing to some printers to prevent wrapped text from
being clipped (The fonts supplied with HP PCL printers are much wider
than their on-screen equivalents, for example).

Improved compatibility with MacOS 8 including support for Appearance
Manager version 1.0.1 and later (MacOS 8.0 shipped with AM 1.0, which
does not include some required functions).

Improved compatibility with MacOS look and feel standards including
sizing icons and window activation behavior.  Not all MetaCard help
and tools stacks have been updated to make room for the grow icon
however.

The clone, copy, create, and paste commands put the id of the created
object in the variable "it".  This feature was actually added in a
previous release but wasn't documented.

Multiple monitor MacOS systems are now handled correctly.

OpenTransport and QuickTime are now weak-linked so MetaCard will now
start up even if these services are not installed.

Support for Appearance Manager is now available in the Mac engine, and
a new property "accentColor" allows getting and setting the color used
for button hilites.

The default UNIX key bindings have been changed to be compatible with
Windows and Mac.  A new property emacsKeyBindings restores the
previous Emacs-compatible bindings.

The "focus" command supports setting the keyboard focus to a specific
button or field.

The new formattedLeft and formattedTop properties together with the
old formattedWidth and formattedHeight properties can be used to get
the bounding rect for the objects on a card or in a group.

The accentColor property governs the color used to draw armed menu
buttons, and the global hiliteColor property is the color used to fill
text selections.  These properties are picked up from the system
at startup (Appearance Manager on the Mac), but can be changed by
scripts.

The command "copy <object> to <destination>" allows copying an object
directly from one stack to another without changing the clipboard or
using copy and paste.

The script editor is now a modeless dialog, and you can edit the
script of multiple objects at the same time, each in their own window.

Menu and text hilite colors have been separated in the Mac engine.

Minor updates to the development environment to allow access to new
features including support for setting the number of a card and inks.

MetaCard-format externals are now supported on Mac PPC systems, and
the external tutorial has been ported to the Mac.

The ask and answer file commands now take the starting path for the
file selector from the file name passed to them.

Modal dialogs and palette windows should operate properly, though
there is no support for non-movable modals.

The scripting language features for addressing elements in the
menubar in a HyperCard-compatible fashion are now supported.
Menuitems can only be addressed by number, however:
get the name of menu 1
disable menu "Style"
enable menuItem 3 of menu "Style"
hilite menuItem 1 of menu "Font"

Button-contents menus can now have accelerators in them, denoted using
the Mac-standard format (if /X appears on a line, control-X is the
accelerator for that menu item).

The standard MetaCard menu bar now uses the new language and
accelerator features.

lock/unlock colormap can be used to change the fixed colormap that is
used by default on 8-bit Mac systems.  The typical procedure would be
to unlock the colormap, go to a card that contains objects that have
colors that should be installed in the colormap, and then lock the
colormap again.  A "CLUT-flash" will occur when the card redraws, but
at least now the developer has control over when it occurs.

All visual effects are now implemented.

The patterns used for foregroundPattern and backgroundPattern are
now rotated to match a control's position rather than being fixed at
the window origin as they were in previous releases.

The Mac engine can now open ports "modem:" and "printer:" as files
and read from and write to them.  The serialControlString can be used
to set baud rate and other parameters.

MacOS8 look and feel is now almost completely implemented,
including tracking for radio buttons and checkboxes.

A global property "proportionalThumbs" determines whether thumbs
are proportional as on Windows and UNIX or fixed size as on MacOS.
Set to false by default on MacOS, true on other platforms.

A "TMEM" resource controls use of the MacOS memory management system.
It contains two bytes.  The first byte controls whether temporary
memory is used for normal heap management (1 for yes, 0 for no).  The
second byte controls whether temporary memory is used for pixmap
storage (window backing pixmaps and images, 1 for yes, 0 for no).  By
default both are enabled, and can be changed only with a resource
editor (e.g., Resedit).  If you set one or both bytes to 0, you'll
also have to increase the MetaCard application partition size in the
Finder (figure about 6MB + the size of all stacks you'll be editing).

Partial support for modal dialogs (movable modals) is supported in
this release.  Full modal support (system-modal) is looking doubtful
for 2.2 at this point because event management becomes a rats nest in
MacOS when trying to support modals that include time-based elements
(like editable fields with flashing cursors).

The help menu in a MetaCard menu bar group is now installed in the
proper place in the system menu bar.  The last element in that menu is
now installed in the Apple menu, rendering the "appleMenuItems"
property added for 2.2A4 redundant.

The "launch" and "open process" commands are now available on the
Mac.  No support for reading or writing to processes is supported or
planned for the Mac version of 2.2, though in many cases you can use
AppleEvents to achieve the same results.

The "replace" command replaces text in a container.  It is a plain
character replace which means it is faster than the replaceText
function and also will work with characters that are difficult or
impossible to use in regex-based functions like replaceText.

The globalLoc and localLoc functions are SuperCard-compatible
functions for translating coordinates between stack relative and
screen relative.  In addition, the mouseLoc function has been changed
to provide coordinates relative to the defaultStack instead of the
mouseStack as was the case in earlier releases.

The stackFiles is now a stack property instead of a global
property.  The syntax is the same (a list of stack name, file name
pairs), but must now be explicitly set by the developer.  The previous
automatic behavior was more convenient in general, but had a
virus-like quality and tended to grow to large sizes if not
periodically cleaned out.

Stacks are now tagged with the platform they were last saved on,
and Mac to PC/ISO-8859 character translations are now handled
automatically.  Note that the translation will slow loading somewhat,
and so it is recommended that stacks be saved once on the target
platform prior to releasing them.

A new "platinum" look is now the default on the Mac platform.  It's
still being tuned, but please report any problems/suggestions you
have.

The behavior of "exit to MetaCard"/"exit to top" has been changed
to be compatible with with HyperCard.  Most importantly, pending
messages are suppressed when this command is executed (e.g., if you
exit from a closeCard handler, the openCard message for the
destination card won't be executed).

The mouseMove message is now sent to the control that contains the
mouse pointer, rather than directly to the card as in previous
releases.

A mouseRelease message is now sent when the mouse button is
released outside the control that received the mouseDown message (this
is useful for implementing drag and drop behaviors).

A mouseColor function returns the color of the pixel the mouse
cursor is over.

The import snapshot command now takes optional rectangle and
window parameters, allowing taking snapshots of areas of the screen
without user intervention.

A "lock moves" command locks the moving objects so that multiple
objects can be set up to move at the same time.  "unlock moves" causes
them to all start moving at the same time.

PICT images can be imported on all platforms, but will only be
displayed on the Mac (use import snapshot to take a snapshot of the
PICT after importing for cross-platform deployment).

The serialControlString property supports setting baud rate and
other properties of serial ports on Windows systems.

Stacks now have a menubar property that controls which menu bar is
displayed on MacOS systems when that stack window is active (has the
keyboard focus).  The value is the name of a group that is used to
build a menu bar.  Currently only button contents menus are supported,
but support for stack menus (menu panels) is planned.  There is no
support for accessing menus directly from the scripting language yet,
so you must make changes to them by accessing the buttons in the menu
group directly.

A defaultMenubar property controls which menu bar is displayed
when a stack without a menubar is active.

Stacks now have an editMenus property.  When set to false (the
default), on MacOS the stack window will be scrolled and resized so
that the group specified in the menubar property is not visible and
the equivalent menu is displayed in the Mac menu bar.  When set to
true, the menu bar will be visible in the stack window just as it is
on UNIX and Windows systems.

Properties "activatePalettes" and "hidePalettes" can be used to
achieve more Mac-like behavior (hidePalettes may not be functional in
this release).

HTTP GET and POST are now implemented in Mac engine.

The Mac engine now supports HyperCard-compatible XCMDs.

The Mac now supports the functions copyResource, deleteResource, and
getResources, which can be used to manage components of the resource
fork (including moving XCMDs from a HyperCard or SuperCard stack into
a MetaCard stack).

The first cut at Mac look and feel is available in this release.  It
is still incomplete, but reports of compatibility problems and
suggestions for best mapping of this style to the Motif and Windows 95
styles are welcome at support@metacard.com.  Arguments for/against
user selectable OS 8 styles are also sought.

The button style "rectangle" has been replaced by the style "standard"
(which causes a button to adopt the style specified by the lookAndFeel
property).  A new style "rectangle" has been added for those case when
a true rectangle is required.

Animated GIFs are now supported.  They automatically play when opened,
but can also be controlled by getting and setting the properties
currentFrame, frameCount, repeatCount, and palindromeFrames.

Inks are now supported.  Only basic logic operations are supported on
Windows and UNIX platforms, but the full set of arithmetic operations
are supported on the Mac.

Images can now be scaled on all platforms.  Note that you must set the
locLocation property after scaling or the images will revert to their
native size when reopened.  Note that scaling images is still not a
recommended technique for mainstream development as it greatly
increases memory and CPU usage and degrades image quality.  Scaling
images using an external image editing package prior to importing them
is still the recommended procedure.

The value() function now takes an optional second parameter which is
an object that is used for the context of the evaluation.  This is
similar to the SuperCard "via" keyword (used to call a function
handler in another object), but is much more powerful because *any*
expression can be evaluated in the new context.

You can now print a card into a particular rectangle on the page.
This new feature will support printing headers, footers, and other
sophisticated printing features directly from the scripting language.
There is a also a "print break" command that causes a page break.
We're still looking into developing a UI (similar to HyperCard's
report generation system) using these new features and welcome
suggestions as to how it should work.

Several OMO compatible functions have been implemented include the
"hilite" and "unhilite" commands, library management routines
(library/release library/libraries()/libraryStack/releaseStack),
"existence" as a function.

Improvements have been made in the way 24-bit images are displayed on
16-bit displays.

The field showGridLines property has been replaced by two independent
properties vGrid and hGrid.

The SuperCard "grab" command has been implemented, which supports easy
dragging of objects: on mouseDown
  grab me
end mouseDown

A statRound() function has been added that does statistical rounding
like the HyperCard round() function (x.5 where x is even rounds down
instead of up).  In addition, both round() and statRound() take an
optional second parameter which is the digit to round at (0 is the
default, 1 rounds at the tenths level, -1 rounds at the tens level).

The Mac engine now supports PNG files.

The Mac engine now supports script interrupt (command-.) to abort
runaway scripts.

The "miscdosc" and "misceval" AppleEvents are now handled properly in
the Mac engine.

The standalone builder now works on the Mac.  There is currently no
option for changing the icons or the creator codes/file type binding,
but these can all be changed with tools like Resedit.

The Mac engine now supports printing and a HyperCard-compatible Apple
Event management system (the appleEvent message and the request,
reply, and send to program commands).  It should now be possible to
use MetaCard to build CGI applications since most Mac WWW servers use
AppleEvents to support CGI.

The move command can now be asynchronous (e.g. move button 1 to
100,100 without waiting), which means that you can move multiple
objects at the same time.  You can also move to multiple points with a
single command (e.g., move button 1 to the points of graphic "path").
As in previous releases, move is system speed compensated and you can
either use the moveSpeed or a time interval to control speed.  There
are also a new function movingControls (returns a list of the moving
objects), a new command "stop moving", and a new message moveStopped
which is sent when a control comes to rest.

A wholeMatches property can be used to force matches made with the
itemOffset, lineOffset, and wordOffset functions to match whole chunks
only.  A new operator "is among" does the same thing (e.g., the
command 'put "3" is among the items of "1,22,333"' puts "false"

A try-catch-finally control structure has been added to ease error
handling.  A throw keyword can be used to throw errors to a try-catch
structure.

A convertOctals property has been added to allow automatic
conversion of numbers with leading 0s to octal numbers (numbers with
a leading 0x are automatically still converted to hexadecimal).

A centuryCutoff property controls what century 2-digit years are
assigned to.

The following properties are now *local* properties: itemDel,
numberFormat, centuryCutoff,  convertOctals, caseSensitive, and
wholeMatches.  A local property retains its value only for the current
handler, and doesn't affect the default value for handlers it calls or
has been called by.  This means you don't have to save and restore
these properties when building scripts that will be used in
libraries.  This change is experimental and may be reversed if too
many scripts turn out to be incompatible with it.  Please report as a
bug any incompatibilities you run into.

Images in PNG format can now be imported on Windows and UNIX systems
(Mac support to be added for the next release).  PNG compresses images
better than GIF, supports masks (transparency) like GIF but also
support 24-bit data like JPEGs.  They'll also make an excellent format
for import snapshot and paint images (though this is not fully
implemented yet).  PNG images also support gamma information (the
function used to convert RGB values to display luminance) and the new
screenGamma function allows finer control of this feature.  This
should eliminate the need to have separate sets of images for
different types of systems (which typically have different gamma
functions).

A showGridLines property has been added for fields which allows the
fields to look like tables or spreadsheets.

Field objects now get a scrollbarDrag message sent whenever they are
scrolled, whether by the scrollbars or when text selection causes a
scroll.

The "busy" cursor is now a rotating beach ball as found in HyperCard.

A flushEvents function that can be used to flush some types of events
out of the incoming event queue.  Mostly useful to prevent multiple
clicks on a "next" button from skipping multiple pages.

A few other bug fixes and compatibility improvements (e.g., you can
now use "a" as a variable name in MetaCard.  We still don't
recommended this, but there are too many lazy HC and SC developers out
there for us to continue to ignore this issue ;-)

****************** MetaCard 2.1.X release notes **********************
A raisePalettes controls whether or not palettes "float" above other
windows.  A raiseMenus property governs whether or not the stacks
containing a menu button are raised before a menu panel is opened.
These properties and the pointerFocus property can be turned off to
improve compatibility with some broken X11 window managers
(specifically fvwm).

Audio in formats other than mulaw is now supported on the SPARC and
SPARCSVR4 engines. Depending on hardware capabilities (which varies
depending on model), this includes most sampling rates up to and
including CD-quality.

The htmlText property of fields now supports a much more useful set of
HTML tags, including support for font, size, and color changes, all
textStyle attributes, and subscript/superscript.

The "Standalone Builder" stack now allows you to set the version
information stored in the executable for the Win32 engine.  This
information about the standalone is displayed when you pick
"Properties" from the right-button popup menu in an Explorer window,
and includes version, copyright, product description, and other
information.

Functions uniEncode and uniDecode convert to and from the 16-bit
Unicode character format used in Windows resources (and as the native
string format in Java).  Implementation is limited to the converting
strings in ISO-8859 character sets at this point, and only in the
byte-order expected by little-endian processor architectures (Intel,
Alpha, some MIPS).

A playStopped message is now sent when an audioClip or videoClip
finishes playing.  It comes with one parameter: the name of the clip
that has stopped.  This will help eliminate those pesky "wait until
the sound is done" statements that prevent interaction with the UI
while a clip is playing.

The move command now takes an optional "without messages" clause that
disables message dispatching during the move.


******************* MetaCard 2.1.1 release notes **********************
This is the first release of the new MetaCard Starter Kit.  This
serves the same purpose as the save-disabled distribution used in
previous releases, but instead of not allowing saving, this release
limits the length of the script an indivdual object.  The Starter Kit
will allow development of fully functional applications and multimedia
presentations that can be redistributed without runtime or licensing
fees.  It just takes more work to develop with the Starter Kit than
with the full license.  This release has a limit of 10 statements per
object (handler names, if-repeat-switch statements, and comments don't
count toward the limit).  There are also limits on the number of
statements that can be executed with the "do" command (5) and on the
number of objects that can be added to the message path with the
"start using" and "insert script" commands.  There are no limits on
object creation, the development environment, or the total length of
the scripts in a stack.

A spiffy new demo stack shows off many of MetaCard's capabilities, and
provides a more complete introduction to the product.

The replaceText function can be used to perform quick substitutions of
one string within another.  It accepts the same regular expression
patterns as the matchText function.

The Win32 engine now attempts to pick up HTTP proxy settings
automatically from Netscape or IE Registry entries.

Buttons used as combo boxes and drop-down lists now have a menuLines
property that can be used to set the height of the menu panel.

The script abort function has been changed to allow Control-Break and
Control-. to abort scripts (the previous sequence, Control-C, is the
"copy" keyboard accelerator on both Windows and the Mac).

Two new callback functions have been added to the external API:
GetVariable and SetVariable.  These allow getting and setting the
value of local as well as global variables from within an external.
In addition, all callbacks now work in the context of the calling
environment, and not the environment of the stack the external was
attached to (as was the case in previous releases).

A few new convenience features have been added, including accelerators
(short cuts) to open the card and stack scripts directly
(Control-Alt-C and Control-Alt-S, respectively), search and replace
for the script editor, and the KP Enter key closes the script editor.

Stack positioning was changed on UNIX systems to make placing stacks
at particular locations more reliable.  The menu bar and message box
stacks also now position themselves in more useful locations when they
open.

You can now open a stack into the window of another stack, closing the
old stack in the process.  It has the side effect of setting the new
stack's mode and resizable properties to the values set for the old
stack.  The command syntax is:
go to stack "newstack" in window of stack "oldstack"

The Win32 engine can now be run on Windows 3.1 systems.  Note that
this is primarily designed to support *deployment* of MetaCard
applications on these systems.  Windows 3.1 is not a recommended
platform for developing MetaCard applications.  There are many
requirements and restrictions:
 1) Win32s must be installed.  You can get information on Win32s and a
   pointer to download the current version from the following document
   on the Microsoft WWW site:
   http://support.microsoft.com/support/kb/articles/q122/2/35.asp
 2) The look and feel is Windows 95, not native 3.1
 3) Printing is not supported
 4) The dissolve, stretch, and shrink visual effects are not supported
 5) Neither shell() or open process are supported
 6) HTTP URLs and the load and post commands are not supported
 7) Import snapshot is not supported
 8) External DLLs are supported, but you have to be careful to only
    use functions supported by Win32s in your XCMDs/XFCNs.
 9) There are some problems navigating among windows due to bugs and
    incompatibilities in Win32s.  Specifically, Alt-Tab doesn't bring
    up the task manager, and windows don't always raise when you
    clicking on them.  Setting the "raisePalettes" property to false
    (using the Preferences dialog) is a partial workaround for the
    latter. 
10) A TCP/IP package must be installed (WINSOCK.DLL), or a warning
    will appear during startup.  The functions in this DLL are not
    called unless you attempt to use HTTP URLs, though, so you can
    suppress the error by making a copy of another DLL and naming 
    it WINSOCK.DLL.

The commands "load" and "unload" have been added that manage a cache
of HTTP resources.  The "load" command asynchronously downloads files.
The functions "urlStatus" and "cachedUrls" provide information about
the URLs in the cache.

Functions base64Encode/base64Decode convert binary data to the MIME
format used for email and HTTP transfers.

Functions urlEncode/urlDecode prepare strings to be submitted in a
format compatible with HTML forms, and decode HTML form data when
MetaTalk is used in CGI applications.

The property httpProxy allows use of HTTP through a proxy.  A new tab
was added to the preferences palette to change it.

The property toolTipDelay governs how long it takes for tooltips to
open.  Setting it to 0 suppresses display of toolTips.

Operators bitAnd, bitOr, bitNot, and bitXor have been added that
perform bitwise operations (these have be renamed from andBits,
etc. for this release).

Palette windows no longer float on top of windows of other
applications when MetaCard loses the focus.  This new design also
works on UNIX/X11 systems.  It does have one disadvantage: palette
windows sometimes flash when toplevel windows get the keyboard focus.

A resource move dialog is included in the tools stack (open it from
the Tools menu).  This dialog allows you to select stacks from the
tools stack and make them substacks of your stack.  It also will make
copies of the icons you use in a stack.  This allows distribution of
products without including mctools.mc.

A standalone builder dialog is included in the tools stack (open it
from the Tools menu).  This stack appends a stack to an engine, and
patches the engine to tell it where the stack is.  It works on all
platforms, though of course when you make a standalone the appended
stack can only be used on a single platform.

A menu builder that builds lists of menus and menu items, and then
constructs a menu bar at the top of your stack can be opened from the
Tools menu.

Functions "queryRegistry" and "setRegistry" have been added to the
Windows engine.  This allow scripts to get and set things like the
file-extension/executable mapping.  Be careful with setRegistry: you
can render applications and even the whole system inoperable if you
delete or put bogus values into the registry.

Serial ports can now be opened, written to and read from on Windows
95/NT systems.  Be sure to specify a ":" as the last character in the
device name.

The functions clickChar, clickCharChunk, mouseChar, and mouseCharChunk
return information on which character the user clicks or moves the
mouse over.

The property "backdrop" has been implemented.  Setting it to a color
name or RGB value creates a window just below all MetaCard windows,
obscuring the desktop.  Set the backdrop to none to remove the
window.

A chunk types "token" has been added.  Tokens are chunks as defined by
the MetaTalk parser.  It treats each operator and punctuation mark as
a separate element.  Tokens are between words and chars in the
hierarchy:
char 1 of token 2 of word 1 of "somefunction(a+b)" # returns "("

A container type "url" has been added.  All operations are synchronous
but the "load" command has been used to prefetch a URL.  Urls are the
new highest level container type, as they can contain main stacks:
button 1 of card 2 of stack "whatever" of url "http://whatever"
get url "http://somemachine/somefile"
put url "file:somefile" into field 1
put field 1 into url "file:somefile"

The "post" command posts the specified data using HTTP POST to the
specified URL:
post somevar to url "http://www.somewhere.org/cgi-bin/somescript.mt"

A few new SuperCard compatibility features have been added, including
a "currentwindow" function, an "interrupt" function, "lower" and
"upper" (which are like toLower and toUpper), a "userProperties"
function (same as customKeys), "style" as a stack property, and a
"showInvisibles" property.

******************** MetaCard 2.1 release notes **********************

Windows 95 can't use images larger than 8x8 as fill patterns, so
many of the objects in the mcdemo stack don't look as good under
Windows 95 as they do under NT and all the UNIX platforms.

Stack windows are no longer automatically double-buffered.  This means
you may see flickering as objects are redrawn in some cases.  Doing a
visual effect or selecting an object with the pointer tool enables the
buffer (backing store) for the target stack.  The alwaysBuffer
property can be set to force double-buffering from the time a stack is
opened.

Due to differences in how Motif and Windows 95 handle keyboard focus
indicators and the "default" button in a dialog box, objects must be
resized as they are loaded from version 2.0 stacks.  Scripts that
dynamically resize controls may need to be changed to account for
this.

In Windows 95, editable fields are drawn with a white background.
When MetaCard is in Windows 95 look and feel mode, it draws fields
with white backgrounds if they are opaque, don't have a background
color set, and are showing their border.

Menu panel behavior for Motif was changed to be more Windows-like:
items are hilited (armed) automatically as the mouse is moved over
them, even when the mouse button is not held down.

Minor changes to the external function call API had to be made to
support calling external functions as DLLs on the Windows platform.
The external package for UNIX platforms is called external.tar.Z,
which must be uncompressed and untarred, and then compiled.

The Win32 engine supports the shell() function and the "open process"
command.  Due to limitations in the DOS compatibility in Windows 95
and NT, not all DOS applications can be run this way.  We recommend
recompiling any problem programs into 32-bit console applications
which don't have these problems.  Command line (console) applications
currently always open a window, but a feature to suppress this window
will be included in the final 2.1 release.

Many new SuperCard compatibility features have been added, including
new token abbreviations (e.g., num, len, avg, all of which are listed
in the compatibility section of the MetaTalk Reference), within and
intersect functions, and a "move rel" command.  The commands insert
and remove, which support sending all messages through the script of
an object before (front) or after (back) all other objects in the
normal message path (this is kind of like the HyperCard "start using"
command, but it can be used with all types of objects): 
insert script of button 1 into front
insert script of button 1 into back
remove the script of button 1 from back

Negative chunk expressions are now supported.  For example, char -1 is
the last character in a chunk, and word -2 is the second-to-last word.

The keyboard accelerators for cut/copy/paste follow the Motif and
Windows 95 standards, depending on the state of the lookAndFeel
property.

The X to Windows font mapping table was changed so that the Win32
engine works correctly regardless of the desktop font settings.

The "ask file" and "answer file" commands will bring up the Windows
file selector if the global property "systemFileSelector" is set to
true.

The Windows printer selection dialog can be opened with the "answer
printer" command, and the page setup dialog has been modified to use
this new command.  Printing in general on Windows system is still only
partially functional.

A large number of properties and functions have been added for
SuperCard compatibility.  Among those that would potentially be useful
to MetaCard-only developers are the ability to address stacks as
"stack x of stack y", which will look for a substack of a particular
main stack, and a "selected" property for all objects that can be used
to select and deselect them without having to use the "select"
command.  See the last page in the Reference for a list of the other
properties.

Improvements to the script editor include real-time color syntax
highlighting, and a list of handlers in the current script can be
found in the Edit menu.  Selecting one of these items will scroll the
editor to that handler.

Several additional SuperCard-compatibility features have been added,
including support for patterns and an "altID" property that can be
used to assign ids in the range that HyperCard and SuperCard use.
Controls can be addressed using these alternate id's, yet they don't
conflict with MetaCard's requirement that all objects in a stack have
unique ids.

A global property named explicitVariables has been added which causes
the script compiler to flag as an error any variable used before it is
declared with the "local" or "global" keywords.  It also causes
unquoted literals to be flagged as errors.  A check box for this
property has been added to the Preferences dialog.  All of the scripts
used in the MetaCard tools and help stacks can be used with
explicitVariables set to true.

The new function mciSendString allows sending data to the Windows MCI
subsystem, which can be used to control audio and video recording and
playback devices with a finer level of control than is available with
the "play" command.

Scrolling groups: you can add vertical and horizontal scrollbars to
groups, allowing scrolling of arbitrary numbers of controls quickly
and easily.

All controls types can now be created at runtime in the non-Home stack
(run-time) environment.

Controls can be created in groups by specifying "in group whatever"
on the create command line, e.g.:
create button "test" in group "some group"

A new "script errors" dialog will automatically pop up when one or
more controls that have script errors are opened.  You can then open
the faulty scripts by doubling clicking on the lines in the list box
in that dialog (this dialog is especially useful when trying to use
the new "explicitVariables" property with existing stacks).

Functions have been added that allow you find out what fonts are
available on the system.  The fontNames() function returns a list of
the font names.  The fontSizes(fontname) function returns a list of
the size available for the supplied face name.  The
fontStyles(fontname, fontsize) function returns a list of the styles
available for the specified face and size.

8) The style of menu items created with button contents can be changed
by adding special characters at the start of each line:
-  makes a divider between groups of menu items
!c makes the menu item a hilited check box
!n makes the menu item an unhilited check box
!r makes the menu item a hilited radio button
!u makes the menu item a unhilited radio button
(  makes the menu item disabled (can be combined with !r and !c)

Creating a set of !r and !u menu items separated by dividers makes
them into a radio group (which causes enforcement of the "one button
hilited" rule).  Putting an & in the menu item name causes the
character immediately following it to be underlined and used as the
mnemonic for that menu item.

Color palette management on the WIN32 engine is now complete.  All
display depths (1, 4, 8, 16, 24, and 32) are now supported, and
conflicts with the system palette in 8 bit modes have been minimized
as much as possible.

The "popup" command now be can be called from any type of object,
making it possible to open right-button menus (a Windows 95 standard)
from any control.

The new tabbed-dialog development environment is complete.  Among the
new features in this release are a right button menus to get to a
script or the properties of any object.

A "tooltip" property has been added for buttons and fields that shows
a short help message when the mouse remains motionless on the control
for a short time.

Graphic objects have "label" and "showName" properties.  They also now
support text font and style properties.  These features makes it much
easier to build flowcharts and other labeled diagrams.

Buttons and graphics now support multi-line text labels.  You can set
them using the new properties dialog, putting \n in-line where you
want the line breaks to be.

Buttons have a "hiliteIcon" property which allows them to show a
different icon depending on whether they're hilited or not.

The "open file" command now accepts the modifiers "binary" and "text"
as in "open file whatever for binary read".  By default, the WIN32
engine opens files in "text" mode, which means cr-lf pairs are
translated to a single linefeed on read, and vice versa for write.
UNIX engines are unaffected (there is no difference between the two
modes on UNIX systems).  As in 2.1A1, path delimiters are maintained
internally as the UNIX-standard / character and this is how they
currently appear in the file selector.  Paths are translated back to
the DOS standard \ character when files are opened.

Playback of videoClips (AVI format only) and audioClips (all formats)
is supported in the WIN32 engine.

The look and feel is switchable at runtime between Windows 95 and
Motif using a global property.  A "preferences" dialog (from the Edit
menu) allows you to choose between the two.

Buttons have a "tabbed" menu mode that is used to implement the the
tabbed dialogs that are ubiquitous in Windows 95.  These are set up
just like option menus, except that the "menuPick" message has two
parameters, the new tab and the old tab.  In most cases, you'll just
hide a group named the same as the old tab, and show one named after
the new tab.  You could also just go to a card named the same as the
new tab.

Buttons have a "comboBox" menu mode which also work like option menus,
but with an additional edit field the contents of which can be set and
retrieved by getting the "label" property of the button.  Currently
the field created by the button sends the same messages (e.g,
closeField and exitField) that other fields do, although this design
is still being evaluated.

An autoHilite property has been added to fields that causes lines in
the field to automatically hilite when the mouse cursor passes over
them.

********************* MetaCard 2.0 release notes **********************

MetaCard now can be used as a Helper Application for most Web browsers
without compromising system security.  The "-f" command-line option
prevents MetaCard from using the open, import, export, and kill
commands, and the shell(), files(), and directories() functions.
Setting the environment variable MCNOFILES to some value other than
"0" will also disable these features.  Stacks can still be opened on
the local system, but they cannot be saved.  This makes it possible to
build presentations using a combination of WWW-based and local
content.  See the file README.install for tips on setting up MetaCard
as a Helper Application.

MetaCard now supports the X11R5 Xmb text extensions on X11R5-based
platforms (HP9K700, Linux, IRIS, SPARCSVR4, and IntelSVR4).  The Xmb
calls use the LANG environment variable and a fontset to display text
strings that contain a mix of 8 and 16 bit characters.  To use it, set
the LANG environment variable and set the textFont to a valid fontset
(a list of font names separated by commas) for that locale.  The old
16-bit character support remains in place for use on other platforms,
and for those applications where mixed 8 and 16 bit text is not
required.

Display PostScript (DPS) support has been dropped from the RS/6000 and
IRIS engines since these vendors no longer bundle support for DPS.
The SPARCSVR4 and Alpha engines will retain support, although the very
limited portability of the EPS control now makes it useful even less
often.

The functions commandNames, functionNames, and propertyNames return
lists of strings known to the MetaTalk interpreter.  The functions
localNames, globalNames, variableNames return lists of the variables
currently defined.

Pasting text with quick-paste (mouse button 2) now causes
keyDown/keyUp messages to be sent for each character added, allowing
handlers that do input validation to work on pasted text.

MetaCard stacks should now use a ".mc" extension to make use of
MetaCard as a WWW helper application easier, and to ease the
transition to OS/2 and Windows.  The standard MetaCard stacks have all
been renamed, and the file selection dialog now automatically prompts
with a name with a .mc extension.

A new mouseMove message is sent (naturally enough) whenever the
mouse is moved.  Using this message is the preferred means of having
an object track the cursor (it should be used instead of the
traditional repeat loop that checks the mouseLoc).

New functions mouseChunk, mouseText, and mouseControl can be used with
the mouseMove message to determine which control, and if it's a field
which text, is under the mouse cursor.

The global property screenMouseLoc can be used to determine the
current mouse cursor position in screen coordinates, or to *set* the
cursor position from a script.  This feature is useful for simulating
the cursor movements in CBT packages, but should *not* be used as a
general UI technique.

The new keyUp message is sent after the keyboard key has been
released.  This is useful when you want to do something (like a
search) *after* a key has been entered into a field rather than before
as is required with the keyDown message.

The send command now takes and "in" argument.  So, you can "send
mouseUp to button 1 in 3 seconds".  This feature should be used in
almost all cases where idle handlers and the "wait" command were used
in earlier releases since it results in easier to develop and easier
to maintain scripts, much better performance, and allows better
interactivity (you can easily wait for a mouse button press, a key
press, or a timer event all at the same time).  The pendingMessages
function gives a current list of these delayed-execution commands, and
the cancel command can be used to cancel them.

Times can now be specified as floating point numbers, and floating
point numbers are returned from the "long seconds" function.  This
allows greater precision for waits and sends and for measuring
reaction times.

The hide and show commands now take a "visual effect" argument.  This
allows only the changed area to be updated, which was not possible
with the traditional "lock screen..show..unlock screen with visual
effect" sequence.  This results in much smoother effects and some
nifty new effects (e.g., you can scroll an object into position).

The visual effect command now takes a "sound" parameter.  This is used
to improve the sychronization of visual effects with sounds on systems
where going to a card with lots of images and/or lots of colors is not
instantaneous.

A new move command moves an object from one point to another.  This
effect is server-speed compensated which means an object will move the
same speed on all displays.  You can can control speed either by
setting the moveSpeed (in pixels-per-second) or by supplying a total
time for the movement on the move command line.

Non-dispatched events (events that occur during waits, visual effects,
etc.) are now buffered and delivered when a message has finished
execution.  This will eliminate the dropping of events that sometimes
occurred with earlier releases.

Fields now have an htmlText property that can be used for
import/export of HTML formatted text.  Support is limited to current
field capabilities, however (i.e, no in-line images, tables, or
list-levels).

Graphic controls have startArrow and endArrow properties to draw
arrowheads at the start and end of lines.  The arrowSize property
controls the size of these arrowheads.

The ask file and answer file commands now take a "with filter X"
clause that allows you to specify a file type.  For example,
specifying "*.mc" will show only MetaCard stacks.

MetaCard can now be run as a language-only program.  Providing a
MetaTalk script file instead of a stack will cause MetaCard to run
without opening a connection to the X server.  Specifying the -u
command line option also turns off the UI.  Your scripts must catch
the "startup" message as their main procedure, since the usual
openCard and openStack messages aren't sent.  This capability makes
using MetaCard a reasonable alternative to writing Perl scripts for
system administration and WWW CGI scripts.

MetaCard now supports alternate visuals.  Specify a visual with the
command line option [-v id], where id is a visual id as reported by
the xdpyinfo command.

Performance importing and displaying 24-bit images has been greatly
improved.  Image editing on 24 bit displays is also much faster.

MetaCard can now import GIF, JPEG, XPM, and BMP format images in
addition to the XWD, XBM, and PBM formats supported in earlier
releases.

MetaCard images now support a "filename" property, in which case the
image data is read from the specified file when the image is opened.
This will reduce memory usage for stacks that use lots of images,
albeit at some expense in extra load time and distribution complexity.

Images now have a dontDither property which can be used to tune
display of 24 bit images on 8 bit displays.

The new "prepare" command can be used to hide the start up processing
time when playing video clips.  Video clips can be prepared at
openCard or openStack time, and then when the "play" command is
executed they will start up immediately.  The play command now
supports pausing movies, and single stepping them forward or back.
The audio tracks in video clips are now played along with the video.

XAnim is now distributed as a stand-alone executable.  This will make
it easier to upgrade XAnim in the future independent of the MetaCard
engines, and also allows multiple movies to be prepared and played at
the same time.

The script execution engine has been completely rewritten.  The 2.0
interpreter is about 8 times as fast as the 1.4 interpreter overall,
supports debugging and profiling, and can now process binary
information.  MetaTalk scripts should now run at speeds comparable to
equivalent scripts in Perl or Java, approximately twice the speed of
Python, and up to 10 times the speed of Tcl and ksh (as always with
benchmarks, your mileage may vary depending on the mix of operations
your scripts perform).

A script debugger and profiler stack is now available.  The debugger
supports breakpoints, tracing, step into and over, and continue (run)
commands.  Local and global variables can be viewed and set.  When the
script debugger stack is open, expressions evaluated in the Message
Box are in the context of the running script.  The script profiler can
be used to show how many times each statement in a script is executed,
and how much time each statement takes to execute.  The dialog box
help for this stack has brief directions on how to use it.

A breakpoint command has been added which will cause the debugger to
break if it is running.  The command is ignored if the Script Debugger
stack is not open, preventing unwanted interruptions.

The script editor has been greatly improved.  It now has a menu bar
that can be used to select insert relevant messages, commands,
functions, and properties.  Terms can be looked up in the MetaTalk
Reference by selecting them and choosing "Lookup Selection..." from
the Tools menu, or by right-clicking on them.  Commands, functions,
and properties can be colored by choosing "Colorize" from Tools menu
(useful when trying to find misspelled property names, or cases where
property names have been used as variables).  Several additional
Emacs-compatible features have been implemented: incremental search
(Control-s), backward-page and forward-page commands (Control-x [ and
Control-x ] respectively), set mark (Control-space), and kill region
(Control-w).  An external editor can now be called from the Script
Editor window, and scripts can be opened directly into the external
editor.

Many global variables that were used to pass information between the
engine and the interface have been converted to properties to reduce
the pollution of the global name space.  This will cause adaptations
of MetaCard tools stacks (specifically the error dialogs, and the ask
and answer dialogs) to stop working.

Multiple commands can be executed on a single line by separating them
by semicolons (;).  While this feature can be very useful in the
Message Box, its use is discouraged elsewhere.

Evaluating an uninitialized variable as a number causes it to return 0
(it used to cause an error).

Boolean expressions no longer cause errors if their values are not
"true" or "false" (this used to cause an error).  Anything except the
value "true" is considered to be false.

Functions can be called with call-by-reference arguments.  Putting an
@ character before a parameter name in the handler indicates that
setting that variable should affects the value in the calling
function.  No change is needed in the calling function (this feature
is modeled on the "reference" construct in C++).

A new modifier to the repeat keyword (for each) can be used to greatly
improve performance of scripts.  For example, if the variable "var"
contains 64K of data, the first repeat loop takes about 130 times as
long to execute as the second (even greater savings are achieved with
larger data sizes):
  repeat with l = 1 to the number of lines in var
    put line l of var into dummy
  end repeat
  repeat for each line l in var
    put l into dummy
  end repeat

A switch keyword has been added with a syntax similar to the C switch
keyword.  It can be passed a single parameter in which case the case
expressions are compared with that value, or without a parameter which
causes the cases to be evaluated until a "true" value is returned.

A format() function has been added with a syntax compatible with the C
printf function.  This is most useful for padding strings with spaces,
or controlling the format of numbers with more flexibility than is
possible with the numberFormat property.

The new matchText() function can be used to perform regular expression
(regex) matches.  MatchText() takes a variable number of arguments,
the third and later of which are call-by-reference variables used to
store the matched substrings delimited by ()s in the pattern string.
The matchChunk() function works similarly, but returns pairs of
numbers that are the start and end characters of the matched
substrings.

Variables now support associative arrays.  The syntax is to use the
familiar "[]" characters to specify an index.  The index can be a
number (e.g., somearray[1]) or a string (e.g., a2["somestring"]).  The
keys() function can be used to determine which elements have been set
(e.g., keys(a2) returns "somestring").  Multidimensional arrays can be
implemented by separating the values by a comma (e.g., a3[1,2]).
Unlike some less friendly languages (Perl and Tcl), spaces are *not*
significant in MetaCard's use of the comma operator (e.g., a4[1,3] is
the same as a4[1, 3]).

Objects now support custom properties (also known as user-defined
properties).  Two new types of handlers (getprop and setprop) have
been added, which are called when custom properties are referred to.
Custom properties can also be with an index, just like variables used
as associative arrays.  A new property customKeys can be used to get
or set the list of custom properties of an object.

When a control's lockLocation property is set to true, setting the
width or height of the object no longer changes the position of the
topLeft corner.  When lockLocation is false, it's the loc that isn't
changed.  This feature simplifies and improves performance of geometry
management scripts since you don't have reset the left property every
time you set the width property.

Attempting to close a stack using the window menu sends a
closeStackRequest message to the current card of that stack which can
be used to implement a modal "save changes" dialog.  If the message is
not handled, or is "passed", the window will close normally.

List box style fields now support the autoHilite property which can be
used to suppress hiliting in fields that the *application* must
control (like the script field of the script debugger).  A
toggleHilite property has been added to allow a more natural (but not
Motif style guide compliant) method of selecting multiple lines in a
list box.  The noncontiguousLines and multipleLines properties have
been renamed to noncontiguousHilites and multipleHilites, which are
better names for these properties (the names were originally adopted
from SuperCard even though we didn't really like them).  A
threeDHilite option is available to give hilited lines a 3 dimensional
look.

Scrollbars now look like real Motif scrollbars.  This required making
a small change to the colors defined in 2.0 the Home stack.  If you
use an old Home stack, they won't look right.

Stack icons (for minimized windows) are now windows and so are in
color.

The behavior of the "send" command has been changed back to the 1.2
behavior: the execution environment of the called handler is now
changed to be the object that was sent the message (i.e. "this stack"
is the stack containing the object who's script is executing).  A
"call" command has been added that supports the 1.3/1.4 behavior
(i.e. "this stack" is the stack containing the object who's script
*called* the other handler).  Though this is incompatible with the
HyperCard use of the "send" command (which is why it was changed in
1.3), after careful consideration we've come to the conclusion that
the HyperCard team made a mistake ;-)

********************* MetaCard 1.4 release notes **********************

A new message, rawKeyDown, has been added.  One parameter is passed,
the X KeySym from the raw X KeyPress event.  This message can be used
to catch keys such as page up/page down, pause, and print screen,
which don't have their own messages.

Response times for buttons and fields placed over large images has
been improved.  The improvement is dramatic in some cases (e.g., with
full screen images displayed over a network).

To reduce conflicts with colormap hogs like Mosaic and Netscape
buttons and fields now use the same color substitution algorithm used
for images.  Though you may get strange colors occasionally using this
method, you're less likely to get invisible or very hard to read
characters.

The functions tolower and toupper have been added which convert a
string to all lower-case or all capital letters, respectively.

A -m command line option has been added which will disable use of
memory mapped file I/O.  Though this will slow stack loading, it will
allow the use of MetaCard on some OS variants that lack this system
call.  If MetaCard crashes on startup, give this a try.

A lockcursor property has been added so that you can prevent the
cursor from reverting to the current tool's cursor when all pending
handlers have finished executing.

The Solaris 2.X engine is now built on a Solaris 2.3 system, and
support for the DPS extension (EPS objects) has been implemented.

Global variables now *must* be declared before they can be used.  In
previous versions, as long as the global had been declared in some
handler, it could be used in any other.  This "feature" has been
removed to improve HyperCard compatibility and reduce the incidence of
certain types of scripting errors.  A warning has been added so that
if a literal shadows the name of a global variable, at least you'll
know about it.

The XAnim integration is complete.  New features include support for
QuickTime and AVI format movies, support for monochrome systems,
support for scaling movies (scale), setting their frame rate
(frameRate), and leaving the last frame of the movie on the screen
(dontRefresh) when it finishes.  Movies played back directly from disk
are no longer imported, which reduces memory usage considerably,
albeit at a small cost in performance.  Since colormap calculations
are done up front now, start up time for videoClips is somewhat longer
than it was in earlier versions, but playback should be smoother.

A small version of the tools stack (mcmini) is included in the
stack.tar.Z file.  This stack should be distributed with your stacks
instead of the full mctools since it takes up less disk space and RAM.

Shared memory for the SGI and SPARC engines has been turned off by
default since most SGI and SPARC servers are broken (the shared memory
extension doesn't support clipping).  Disabling it slows image redraw
by about 25%.  You can turn it back on by supplying the +s
command-line option, or setting the screenSharedMemory property to
true, but if the servers haven't been fixed, images may be
unrecognizable with shared memory enabled.

An embedded version of MetaCard is now available.  The engine is
distributed as a .a file that you can link directly to your
application.  The same API as is used for externals is supported.
This speeds calls to external functions by about a factor of 40, makes
it easier to debug externals, and makes it easier to distribute
applications since it reduces the number of files.  The embedded
engine also has the restrictions against non-Home stacks creating
objects and editing scripts removed.

There is a new color license screen.  You'll need to relicense new
Home stack to see this, however, since the screen is actually an image
stored in the Home stack.

Fields now support tabstops.  You can set the tabstops to a single
value, in which case the tabstop spacing is repeated at that rate, or
to a list of offsets specifying the position of each tabstop.

Images have a pixmapId property, so that you can use them to display
images produced by external applications.  A new card in the external
tutorial demonstrates how to use this feature (it's a cellular
automata program called "The Game of Life" which is pretty interesting
viewing).

Color management has been reworked to minimize the consequences of
running out of colors when displaying images with many colors.

Fields now support multiple selected lines, and noncontiguous
selections, and field selections are retained even when the field
loses the focus.  You can get the selected text with the selectedText
and selectedLines functions which now can take a field description as
an argument.  There is also a new hilitedLines property which returns
a list of numbers.  Fields also have a tabStops property which can be
used to implement tables.

The lineOffset function can be used to determine what line a string
appears in.  In addition, the lineOffset and offset functions can take
a number of characters to skip, which should improve performance when
using offset to scan through large strings.

Buttons can now be used as containers for storing text, and can be set
so that this text is used to create a menu panel.  This makes
producing and modifying option menus.  Note that you'll still need to
create menu panels as stacks if you need to put things other than
simple buttons in them, or if you need to change the menu contents at
the time the menu is opened.  A menuPick message is sent to the button
when a menu item is chosen from a menu.  The selectedLine and
selectedText functions can be also be used with buttons to determine
what was chosen the last time the button was used as a menu (these
functions actually access the "label" property, which is what is
changed when a menu item is chosen).

The operation of option menus was changed: when the menu panel is
closed, it automatically sets the label property of the button.  This
should be backward compatible with the existing mechanism, though it
may be confusing if the menu panel was setting the "name" property
instead of the "label" property of the button.

Groups now automatically resize to fit their children when the
children are resized, and have margin properties which can be set to
preserve space around the children.

A lockLocation property has been added to all controls which can be
used to prevent the accidental movement of objects when selecting
them.  Setting this property also disables the automatic resizing of
groups. 

Scrollbars now have a style and can be set to look and behave like
Motif scale widgets.  They also have startValue and endValue
properties (floating point numbers), and the ability to show the
current value.

Properties pageCount and currentPage were added to EPS objects to
support viewing multiple page PostScript files.

The mouse() function now takes an argument, which is the button number
to check the status of.  If omitted, it checks mouse button 1, so "the
mouse" is equal to "mouse(1)".

New properties playLoudness and playDestination were added to support
changing the volume and destination for sounds.  The playLoudness
property can be set for individual audioClip objects making it
possible to balance sounds recorded at different levels.

Cloning fields once again clones all of the text within the field and
cloning buttons clones the hilite state.

HyperCard 2.2 stacks can be imported, and HyperCard compatibility has
been improved in general.  Due to the lame design of color support in
HC 2.2 (it's implemented as XCMDS), color information can't be
imported (if only they'd done it right instead of shipping an ugly
hack...).  Buttons now support a family property for compatibility
with HC 2.2.  Use of this feature in MetaCard is discouraged since
MetaCard's native support of radio groups is superior.

Externals can now call back to the engine without having the engine
call them first.  This worked to a limited degree in 1.3, but was not
supported.  Now it is.

A completely new mcdemo stack was developed by a professional graphic
artist, greatly improving the initial impression of MetaCard, though
it is also much larger than the old stack.

********************* MetaCard 1.3 release notes **********************

A formattedText property has been added that can be used to get and
set text preserving wordwrap.  This feature is used to support the new
FAQ stack that can import and export the old format of FAQ.

Minor changes to the external interface should eliminate the problems
that have been reported concerning calling externals in tight loops.
External programmers should use the new external support files in
external.tar.Z.  A new external example has been added that exercises
all of the callbacks.  Get external.tar.Z if you want to try it.  The
"External Test" stack is now opened from the "External Tutorial" stack
in the new Tutorials front-end stack.

HyperCard importing now supports all known text and image attributes.
Sound resources are also converted, but aren't resampled and so can't
be played back on systems without 8 bit linear sound format support
(i.e. they won't play back on SPARC systems).  HyperCard includes
support for importing cursors and icon resources, image masks, and
conversion of high-bit set (ISO Latin-1) characters.  Improved
compatibility in the scripting language (e.g.  doMenu) has also been
implemented.

Colors are now fully cached on the client side, which will speed up
applications that require navigating among cards with multicolor
images on them.

The "send" command no longer changes the the card (or stack) before
the destination handler begins running.  This change was made to
improve HyperCard compatibility.  If your scripts send messages to
handlers in other stacks, you'll need to set the defaultStack at the
top of the destination handler to restore the old behavior.  Lock the
screen and use "go" if you need to send a message to another card.

The HP 700 engine now requires HPUX 9.01 or later.  You should install
patches PHSS_3103 and PHKL_2837 if you'll be using audio on HPUX 9.01
or 9.03.

The XT example application (in external.tar.Z) has been converted to
be compilable with both ANSI and K & R 'C' compilers.  In addition,
the event handling has been modified to make communication with
MetaCard more robust.  A new external demo is also included which
demonstrates how to use all of the MetaCard callback routines.  The
external example stack has been moved.  It is now in the mchelp stack,
and is accessible from the Tutorials stack.

The openCard and openStack messages are now delivered *after* the card
has been redrawn.  This change was made to improve HyperCard
compatibility.  preOpenCard and preOpenStack messages have been added
that get sent when the openCard and openStack messages used to get
sent.  Dialogs that do lots of control manipulation in openCard
handlers (e.g. the standard properties dialogs) should have their
scripts changed to use these new messages to eliminate unnecessary
screen redraws and to improve performance.  A script has been added to
the Utilities stack to do this semi-automatically.

The problem with the shell() function and processes the run for very
short times has been fixed.  This was most commonly a problem with
shell built in commands, e.g.: put shell("echo $HOME")

VideoClips can now be imported into stacks, and playing VideoClips
no longer causes the script to block at the play statement until the
movie has finished playing.  A new "mcfli" stack is part of the
distribution (but is not included on floppy distributions due to its
2.5 MB size).

The algorithms that maintain the stackFiles property have been
redesigned (again).  Hopefully this will solve the stackFiles growth
problems found in earlier releases.

Undo for deletes and object movement.

Select multiple objects by dragging out a rectangle.

Cut/Copy/Paste work on multiple selected objects.

Cut/Copy/Paste/Clone now clone the card *data* as well as the objects.
Please check any of your scripts that clone cards for compatibility.
The algorithms have also been made more robust and cutting and pasting
of cards between stacks is now supported.

A new selection algorithm for graphic objects (now you have to
actually click on part of the object, rather than being able to click
anywhere in the rectangle).

FLI/FLC animations can now be played back using the "play" command.
The syntax is "play videoclip <flicfile> [looping] [at loc]".

Display of EPS files (both EPSI and EPSF format) is supported on
systems with DPS extensions (IBM, SGI, and DEC).  Import is supported
on all platforms with a new "eps" object.  The EPS object has been
improved to support transparency and setting PostScript on the fly
(makes a nice graphing system when combined with a package like
gnuplot).

The on-line documentation has been reformatted (resizable dialogs!)
and brought up to date with the functions and properties added for
1.3.  New tutorials are in the works, as are expanded examples in the
Reference and Concepts & Techniques stack.

shell() has been rewritten to eliminate <defunct> process problems on
SCO and missing data problems on RS/6000 systems.  The shell used can
also be changed from the default /bin/sh.  The stderr of the commands
run is now combined with stdout, so please check your scripts for
compatibility.  Open process shares some of these improvements, and
process management is easier since processes opened "for neither" now
self terminate (no need to close them).

A kill function has been added for sending signals to processes
started with open process.  In a addition, "signal" messages are now
sent to MetaCard cards when SIGUSR1 and SIGUSR2 signals are received,
so subprocesses can pull the engine's chain too.

Nested groups are now fully supporting in the scripting language
(e.g., button "OK" of group "inner" of group "outer" of this card)

Printing now handles ISO Latin-1 characters and does a more accurate
job formatting text.

Object graphics: Ovals, rectangles, and polygons that can be changed
with scripts.  See the new demo stacks for examples.  A simple marker
system allows building real-time scatter plots.  Whenever possible,
the property names and terminology used in SuperCard were adopted, so
books on SuperCard may also be of some use on using these properties.

Limited printing support is now provided (some images and graphic
objects don't print yet).  There is no support for selecting printers:
only on printers with the "Standard 35" font set will fonts remap
correctly.  Other printers will stop processing when a missing font is
encountered.  This will also likely be a problem when viewing ps files
with DPS viewers.  Note that you must bring up "Print Setup" dialog
for each stack you want to print from.  Be sure to set the print
command to work on your platform.

Audio files can now be imported into stacks for cleaner distributions.
Audio playback is now supported on the SCO ODT and RS/6000 platforms,
although the SCO support is already obsolete (a patch release that
uses NetAudio will be produced later).

New dialogs for setting colors (including via HSV) and other
properties are included, and the standard properties dialogs keep
better track of which object they apply to.  A new mainStack dialog
makes rearranging stacks easier.

A large number of small memory leaks have been patched.  All known
double-delete problems (which caused crashes on some platforms (most
frequently SGI)) have been fixed.

Deleting stacks on close works better.  Be careful with this property
since MetaCard doesn't warn you to save yet.  This property only works
on mainStacks and when the mainStack and all substacks are closed.

The multiple selection and alignment of groups now works, and nested
groups are now supported.  Note that groups now return "group" as
their type instead of "background" so scripts that look for groups by
type will have to be changed.

Minor changes in the scripting language have been made to improve
HyperCard import capability For example, the "number of lines" in a
container has been changed to be compliant with HyperCard.  If the
last character in a field is a return, "the number of lines" will
return 1 less than it used to.  Although this will break some scripts,
it is necessary for compatibility.  It would be a good idea to grep
your stacks for this phrase: grep "number of lines" filename

The HyperCard "compact" command is supported.  This command will
drastically reduce the size of some stacks that have large numbers of
cards repeatedly added and then deleted from them.  It has little
effect on most other stacks, however.  This command is automatically
invoked by the "save" button in the "File" menu, but only when saving
a mainStack will the substacks be compacted.

The menuButton property has been renamed to menuMouseButton.
menuButton is now a function that returns the name of the button that
is controlling a pulldown or option menu.  This new function is useful
if you want to use the same menu on multiple buttons, since now you
can tell which button to change the name of in a closeCard or
closeStack handler.

A new "importer" dialog simplifies image importing, and a new
"snapshot" feature allows capturing images directly from the screen.
The "snapshot" feature can is invoked with the "import snapshot"
command.

Multiple object selection, alignment, and group/ungroup are improved.
Shift-clicking on a selected control removes it from the selected set,
and ungrouping and then regrouping preserves the original groups
attributes.

Multiple object selection, alignment, and group/ungroup are supported.
Shift-clicking with the pointer tool will add a control to the
selectedObjects.  The new commands "group" and "ungroup" can be used
to group the selectedObjects, and a layout dialog can be used to
resize and align objects before they are grouped.  Rectangle based
selection of objects is not implemented yet.
     
Most engines take advantage of memory-mapped file I/O.  This
greatly speeds stack loading on some platforms (SGI and Solaris 2.1
load 3-5 times faster).

Scrollbar properties are now saved.

An optimization in field load/save reduces the size (and load times)
of field intensive stacks (e.g. address books) up to 30%.

Stacks now wait for externals to initialize when they open to allow
external calls to be made in openStack handlers.

HyperCard stacks can be opened with the regular "go" or "toplevel"
commands, rather than having to use the "import" command.

Command line arguments and environment variables are now accessible
from the scripting language.  Command line options are $0 $1 ...
Environment variables (which can be both read and written) are
accessed as $variablename.

Groups can be selected and moved around.  They can also show borders
and their names in the border.  Double clicking on a control in a
group will bring up the "Group Properties" dialog.  This is the
beginning of the end of the dreaded "Edit Groups" dialog and
"background" editing mode.

A new root window mode has been implemented.  Using the "-r" command
line option will open the specified stack in the root window.  Note
by default MetaCard grabs mouse button 1, but you can override this
with the "-b 3" option.

The font substitution system has been redesigned.  Performance on Mac
and Sun X11/News systems is vastly improved.

Importing HyperCard stacks: both HyperCard 1.X and 2.X stacks can be
imported, and the stacks can be in any of three formats: raw binary,
MacBinary, or BinHex.  To import a stack use the import command in
the Message Box: 'import stack from file "filename"'.

"it" is now a local variable instead of a global as it was in earlier
releases.  Declaring "it" in a "global" statement will make it global
again, although this is discouraged for obvious reasons.  If you've
cloned the "ask" or "answer" dialogs, the clones will have to be
changed since they probably rely on "it" being global.  You'll
probably have to create a global variable to replace it.

A "local" keyword has been added.  It can be used either within a
handler to improve readability, or *outside* handlers to create a
variable with a scope of the whole script (like a "static" in a 'C'
module).  The "global" keyword can also be used outside handlers,
which will save a little typing.  We recommend putting local and
global keywords at the top of the script.

HyperCard compatible chunk expressions:  "the name of card button 1"
is now different from "the name of background button 1".  Stacks now
have a property ("HCAddressing") which determines how addressing works
when you don't specify "card" or "background".  When it is false (the
default), it will look on both for an object.  When true, it will look
only on the card for buttons and only on the background for fields
(the weird HyperCard way).

Message order: Card messages and messages from card objects are now
sent through backgrounds/groups.

Shared memory putimages.  These speed putimages by a a factor of 2 to
6 depending on platform, which improves object animation performance
by about 25% overall.  The improvement will be even greater for movies
(to be supported later).  SPARC users should verify that they are
using a kernel that has shared memory installed (the default
GENERIC_SMALL kernel doesn't).  SCO users should increase the number
of shared memory segments per process (the default is only 6).  The
shared memory server extensions don't always work like they're
supposed to, causing problems in image display and editing.  If they
don't work for you, put a "-s" on the MetaCard command line to turn
off shared memory.  You can also turn it on and off selectively with
the "screenSharedMemory" property.

start using.  This HyperCard "feature" to insert stacks into the
message passing hierarchy is now supported.  Though largely unecessary
due MetaCard's to the mainStack/substack architecture, you are
encouraged to try this feature.  But beware of spaghetti code.  A
global property "usingNames" can be used to detect spaghetti code, but
currently can't be set directly.

Button label and stack title properties:  These can be used to have
the object display a text string different from the name.

Read from stdin and write to stdout.  These are useful when using
small MetaCard applications in shell scripts and the like.  Just
substitute the constants stdin and stdout for the file name.

Open process for update.  In addition, it is no longer necessary to
close processes that terminate on their own.  This new capability is a
natural for building GUI front ends to programs such as mail and ftp.

Kill process <name>.  Kills a process opened with "open process".

The openProcesses and the openFiles.  Functions that produce a return
separated list of the things already opened.

read from <something> for <xx> [units]
write <stuff> to from <something> as [units]
Units can be characters, words, items, or lines, and also int1, uint2,
int2, uint2, int4, uint4, real4, or real8.  The latter set can be used
to read and write binary information.  If multiple ints or reals are
read or written, they are in the form of comma separated numbers.
Don't count on real values being portable.  Note that all reads and
writes are big-endian.  DEC and Intel users will have to wait for a
byteSwapIO property.

Global property noPixmaps.  Defaults to false.  When true, causes
stacks to draw direct to screen, improving performance (slightly in
most cases but dramatically in a few) and reducing server memory
usage.  The down side is that objects will flicker annoyingly,
especially when dragging objects, painting, or typing into scrolling
text fields.  Note that only stacks opened after the property is set
to true will obey it.  I you put a "-n" on the command line, noPixmaps
will be set before the first stack is opened.

The menuMode "cascade" can be used to implement cascading (pull-right)
menus.

********************** MetaCard 1.2 release notes **********************

A new command line option "-pointer" has been added to work around
bugs in pointer focus mode olwm.

A new demo stack is included.  It demonstrates some of MetaCard's
hypertext and multimedia capabilities.

New properties: colormap and firstPixel. These properties can be used
to set the colors used by all MetaCard windows.  This is primarily
useful for using MetaCard with animation players such as PACo, but can
also be used for colormap animation.

Improved HyperCard compatibility.  The word "the" can be left out of
many more property and operator expressions than in previous versions.

SPARC workstations can now play .snd or .au format (the Sun/NeXT sound
format) files.  The HP-9000/700 can play files in .snd and linear 16
formats.  The IRIS engine can play .snd format sound files as well as
the native AIFF files.

No format conversion is supported in MetaCard nor is the ability to
import sound files into stacks.  Utilities are available that will
perform the format conversions, a public domain package called SOX
being the most popular.  Contact MetaCard Corporation for further
information.

See the 'play' command in the MetaTalk reference for details.  The
'looping' parameter can be used to make the sound play continuously
until stopped (with the 'play stop' command) or replaced with another
sound.

Button properties that are used for buttons that are used in menus
can be set using this dialog.  In general, however, it is still
recommended that you clone one of the existing menus rather than
trying to build them from scratch:
copy button "File" of stack "MetaCard Menu Bar"
paste #paste the copied button into the current topStack
set the menuName of the selectedObject to "my menu"
clone stack "File Menu" #then set its name to "my menu"

The font menus in the menu bar now apply to the currently selected
object if there is no text selection.  In addition "strikeout" has
been added to the style menu, and a color menu has been added to the
menu bar.

An "itemDelimiter" property allows you to change the item delimiter
from a ',' to some other character.  This is primarily useful when
parsing a tab delimited file for use in text fields (which don't
handle tabs yet).

"lock error dialogs" command command causes the engine to send an
"errorDialog" message instead of opening the "Execution Error" dialog
box.  This feature is used in the Message Box to bring up the "Script
Error" or "Execution Error" dialog depending on the type of error.

8 bit character support: You can generate the high 127 characters in a
font by pressing mod3 with another key.  On Sun's the Alt-Graph key is
mod3, on other keyboards it may be bound to the Scroll-Lock key, or it
may be unbound.  To bind it, use xmodmap: xmodmap -e "add mod3 =
Scroll_Lock"

Note that this mechanism may change if a international standard for
generating these characters is brought to our attention.  So far, no
standard method has been discovered, and the various OEM defined
compose-key sequences are incompatible across workstations.  In
addition, the compose key features in Xlib seem to be broken or
unimplemented by some vendors.

To figure out which keys will generate which characters, you can look
at any of the ISO 8859 Latin 1 fonts and do the mapping from the high
128 to the low 128 in your head: xfd -fn fixed

Improved HyperCard Compatibility: This may be a good thing or a bad
thing depending on your goals and your existing code.  The most common
problem will be broken geometry management routines.  MetaCard 1.2
only accepts integers for object coordinates.  You'll probably have to
use the 'trunc()' function or possibly the 'div' operator to fix
geometry management routines.  Setting the width or height properties
will probably require resetting the left or top properties as the
'location' of an object is no longer changed when the size is.

The handler name specified after the "end" keyword must match the name
specified after the "on" keyword.

Text between handlers is now ignored.  Thus, you can comment out a
whole handler by putting "--" before the "on" keyword.

Support for keyboard traversal, mnemonics, and global accelerators.
You have to turn on keyboard traversal for all controls (including
groups) in your existing stacks before they will accept the keyboard
focus. Set the traversalOn property to true or use the button in the
Utilities stack.  You'll probably also have to reorder your buttons
since they probably won't be tabbed to in the right order.

Set the tabGroupBehavior property of groups if you want to use the
arrow keys to navigate withing the group instead of the tab key.

Horizontal scrolling and horizontal scrollbars for fields.  Setting
the style of fields to scrolling does not turn on horizontal
scrollbars.  You have to turn them on manual by setting the hScrollbar
property to true.  hScrollbars don't come and go automatically like
they do in Motif.  If you want to emulate this, you'll have to check
the formattedWidth property and set the scrollbar properties
accordingly.

Support for the HyperTalk 'click', 'drag', and 'type' commands for
synthetic events and for drawing pictures on the fly has been added.
The graph animation demo stack uses the drag command to draw bar
graphs.

The HyperTalk 'mark', 'unmark', 'convert', 'ask', and 'answer'
commands are now supported.

The 'import' and 'export' commands now support masks.  See the description
in the reference for details.  PBMPlus has a mask generation feature
which may be useful for this.

History has been added to the Message Box.  Use the control-p and
control-n key sequences to retrieve previously typed commands (as in
ksh).  Control-u clears out the field.
  
The "Utilities" stack has also been improved by including a script
editor (and documentation viewer) in the stack.  Since the Utilities
stack was originally distributed as part of the Home stack, to use it
you'll either have to relicense the new Home stack, or delete your old
Utilities stack and use the new stand-alone stack provided.  If you
choose the latter, you'll have to type the following commands into the
Message Box:
delete stack "Utilities"
topLevel "mcutils"
set the mainStack of stack "Utilities" to "Home"
save stack "Home"

New visual effects and automatic server speed compensation.
The property serverSpeed no longer does anything.
