Revolution
Version  1.1.1 (build release 2)
Runtime Revolution Ltd. <http://www.runrev.com/>
1st April 2002

This file contains installation instructions, upgrade information, and last-minute updates. For complete Revolution documentation, open the Revolution application and choose "Revolution Documentation" from the Help menu.


_______________________________________

CONTENTS:
  What is Revolution?
  Upgrading to version 1.1.1:
	What's new?
	Issues addressed in this version

  System requirements
  Installation on Mac OS & OS X systems
  Installation on Unix & Linux systems
  Installation on Windows systems
  License information and the Starter Kit

  Version history
  Limitations and known issues

  Contacting Runtime Revolution
_______________________________________



WHAT IS REVOLUTION?

Revolution is an integrated development environment for Mac OS, OS X, Unix, and Windows computers. Using Revolution's user interface layout tools and built-in Transcript programming language, developers can create standalone, double-clickable applications for any supported platform.

With Revolution, you use familiar WYSIWYG tools to lay out your user interface, then write the code that ties it all together. Run and test your application right in the development environment. No matter what platform you use for development, a simple Preview command shows you how your application will look in Windows, Unix, or Mac OS. Finally, either release your application as a file distribution that runs in the freely-downloadable Revolution runtime, or build true double-clickable applications for release on each platform you want to support.

For more information about what you can do with Revolution and to join Revolution's developer community, visit our web site at <http://www.runrev.com>.




UPGRADING TO VERSION 1.1.1: WHAT'S NEW?

Version 1.1.1 is primarily a maintenance release, addressing issues that affected stability for some developers. In addition, the following features have been added:

- Extensions and additions to the Internet library
- Ability to communicate with arbitrary devices
- New file manipulation commands
- New database support including Valentina database support on Mac OS , OS X, and Windows systems and MySQL support for Mac OS X systems.

Important!  Whenever you upgrade to a new version, be sure to make a backup copy of all your stack files before saving them with the new version. This ensures that in case of a problem or incompatibility, you can go back to an older version temporarily until the problem is resolved.

--- New Transcript terms ---

"close driver", "dontUseQTEffects", "libURLErrorData", "libURLftpUpload", "libURLSetFTPMode", "libURLSetFTPStopTime", "libURLSetLogField", "libURLVersion", "open driver", "read from driver", "revCopyFile", "revCopyFolder", "revdb_columnisnull", "revdb_columntypes", "revdb_dbtype", "revdb_querylist", "revdb_queryblob", "revDeleteFolder", "revMoveFolder", "revRotatePoly", "write to driver"

--- Changed and extended Transcript terms ---

"answer color", "cachedURLs", "htmlText", "http", "launch", "open process", "rename", "revdb_connect", "URLStatus"


Changes and new features include:

--- Expanded Internet support ---

You can now use the "URLStatus" function to monitor both uploads and downloads via "http" or "ftp" protocols. If an error occurs while uploading or downloading a file with "get" or "put", the error message now appears in the "result" function. The "libURLErrorData" function returns detailed information on any errors encountered during the most recent transfer.

The "cachedURLs" function now returns only URLs that have been successfully downloaded.

The mode (active or passive) of FTP transfers can be set with the new "libURLSetFTPMode" command. The "libURLftpUpload" command allows non-blocking uploads to an FTP server. Use of the "load" command for both "http" and "ftp" downloads is now fully supported.

--- Device driver support ---

The new "open driver", "read from driver", "write to driver", and "close driver" commands can be used to control peripheral devices, get data, and send data through communications peripherals that are not connected to the standard serial ports.

--- New file system features ---

Deleting folders has been made easier with the new "revDeleteFolder" command, which can remove folders that are not empty. The new "revCopyFolder" and "revCopyFile" commands copy all attributes of files and folders, including Mac OS resource forks. The "revMoveFolder" command moves a folder and its contents to a new location.

The "rename" command now can be used to move a file or folder on Mac OS and Windows systems in addition to changing its name.

--- Additional database support ---

You can now use the "revdb_connect" function to connect to Valentina databases, in addition to MySQL, Oracle, and ODBC databases. Valentina is a fast, efficient single-user database engine for Mac OS, OS X, and Windows systems. A demonstration version of Valentina (with a ten-minute connection limit) is included in Revolution distributions for these platforms and is located inside the Revolution folder.

The Valentina database engine can be licensed from Paradigma Software. For more information about Valentina, visit their web site at <http://www.paradigmasoft.com/product/vxcmd.html>.

The new "revdb_columntypes" and "revdb_columnisnull" functions can be used to test the data in a specified database field. The new "revdb_queryblob" function can handle BLOB data objects containing large amounts of binary data. The new "revdb_querylist" function can be used to fetch data from a database into a variable. The new "revdb_dbtype" function can be used to find out what kind of database a connection ID is associated with.

The contents of the Database Manager's "Help" tab has been moved to the Revolution Encyclopedia for this release. Look in the documentation for the article titled "About connecting to and using SQL databases".

--- Miscellaneous Transcript changes and additions ---

- The new "dontUseQTEffects" property can be used to constrain visual effects to use the built-in routines instead of QuickTime. This addresses an issue where QuickTime-based visual effects were cosmetically unsatisfactory on slower systems.

- The new "revRotatePoly" command rotates a line, curve, or polygon graphic through a specified angle.

- The "answer color" command now takes an optional default color.

- The "htmlText" property now uses "<a> </a>" to enclose text whose "linkText" property is not empty.

--- Miscellaneous other changes and additions ---

Important!  The Script Editor's behavior has changed. It no longer asks whether to save changes when you close the Script Editor. If you close without applying changes, any changes will be lost.

- Progress is now shown in the Distribution Builder when downloading a needed engine.

- On Windows systems, the ".rev" extension is now automatically registered to Revolution.

- The limit on the number of stacks shown in the "Recent Stacks" submenu in the File menu has been increased.

- The "Development Guide" page of the main Documentation window now shows a category-based listing of all topics in the documentation. The "Encyclopedia" page has been removed. (All Encyclopedia topics can now be found on the "Development Guide" page.)

- You can now search the full text of a documentation section, instead of only the topic titles, by holding down the Option or Alt key while pressing Return in the Find box at the top of the window.




UPGRADING TO VERSION 1.1.1: ISSUES ADDRESSED IN THIS VERSION

--- Compatibility issues ---

- Compatibility of the Carbon (OS X) engine with Mac OS is greatly improved. It is still recommended to use the Mac OS engine on Mac OS systems for best results. If you want to try using the Carbon distribution of Revolution on Mac OS 8.0 or later, make sure you have the latest version of CarbonLib installed in the Extensions folder.

- Problems that caused the PPC (Mac OS) engine to crash on Mac OS 7.6 and earlier have been resolved.

- Problem causing menu items in Image Library to be inappropriately disabled on Mac OS systems has been fixed.

- A crash bug that showed up when using tool tips on OS X systems has been terminated with extreme prejudice.

- Development environment cosmetic glitches on OS X (mostly involving option menus) have been fixed.

- Problem where short menus sometimes displayed incorrectly on OS X systems has been fixed.

- On Unix systems, the Colors palette has improved stability.

- Exceeding the Starter Kit limits under Windows NT no longer causes a crash.

- The Database library now works under OS X.

- Problem that could cause crashes on Windows systems if you quit with open database connections has been fixed.

--- Development environment issues ---

- Issue that caused the Application Overview and message box to open offscreen after changing monitor resolution has been fixed.

- Closing a stack after saving no longer asks to save changes again.

- Using the contextual menu for a control no longer sends a "mouseUp" message to the control.

- Cutting text in the Script Editor is now considered a change and enables the Apply button.

- Cosmetic problems when scrolling in Icon Chooser have been fixed.

- Problem where nudge arrows in Alignment and Basic Properties occasionally stayed pressed after the mouse button was released, causing the selected control to fly uncontrollably across the stack window and out of sight, has been addressed.

- Application Overview now displays and updates objects more reliably, in particular nested groups and groups being edited.

- Properties palettes have several fixes, update more reliably, and have improved stability.

- "New" button on the Toolbar now works more reliably.

- Message box now resizes properly under more circumstances.

--- Distribution Builder issues ---

- Distribution Builder no longer unexpectedly deletes files.

- Distribution Builder now respects the name of the data folder you set.

- Building a standalone application no longer leaves an extraneous file in the folder.

- Distribution Builder now builds multiple distributions more reliably on Unix systems.

--- Printing issues ---

- The "revPrintField" command now handles tab-delimited text in fields correctly.

- Issues when printing multiple pages from the documentation have been fixed.

--- Other issues ---

- The Support email form has been updated.

- EPS objects created with the "create" command are no longer enormous by default.

- A group placed with the "place" command when the Browse tool is being used is no longer automatically selected.

- Import of HyperCard stacks has been further improved for greater stability.

- On Windows systems, the menu bar can no longer be maximized.

- Script error reporting, particularly when encountering compile errors, is improved.

- The dialog boxes used for the "answer" and "ask" commands now lock messages. This addresses a problem where using these commands in handlers that respond to a focus change (such as "openField") sometimes produced unexpected results.




SYSTEM REQUIREMENTS

(Memory and disk requirements below are for the Revolution development environment, not for applications created by Revolution.)

For Mac OS systems:  Any 68K or PPC Macintosh system with:
   Operating system: Mac OS 7.1 or later
   Memory:
      at least 48M total (128M total recommended)
      at least 20M free (48M free recommended)
   Disk space: 20M free
   QuickTime 3.0 or later required for video features (4.1 recommended)

For OS X systems:  Any OS X-capable Macintosh system with:
   Operating system: OS X 10.0.3 or later
   Memory: 128M total
   Disk space: 20M free
   QuickTime required for video features

For Unix & Linux systems:
   Operating system:
      FreeBSD and BSDI
      HP-UX 10.20 or later
      SGI IRIX 5.3 or later
      Linux Intel 1.2.13 ELF or later
      Linux PowerPPC 2.0X ELF or later
      AIX 3.2.3 or later
      Solaris x86 2.5 or later
      SPARC Solaris 2.3 or later
      SPARC SunOS 4.1.x or later
      Darwin (command-line scripting only)
   Memory: 48M total
   Disk space: 20M free
   Xanim required for video features

For Windows systems:
   Operating system:  Windows 95, 98, Me, NT, 2000, or XP.
      (Windows 3.1 is supported with certain limitations.)
   Memory: 48M total
   Disk space: 20M free
   QuickTime 3.0 or later required for video features (4.1 recommended)




INSTALLATION ON MAC OS & OS X SYSTEMS

To install Revolution on your Mac OS system, download the file <http://www.runrev.com/revolution/engines11/revolution.sit> from the Runtime Revolution web site, then unstuff the file with StuffIt Expander. To install Revolution on your Mac OS X system, download the file <http://www.runrev.com/revolution/engines11/revolutionosx.sit>.  (You can also download Revolution from the Runtime Revolution FTP site at ftp.runrev.com.) This creates a folder called "Revolution" which contains all components of the development environment. You can place this folder anywhere on your disk.

(Note: To install Revolution on a Mac OS or OS X system, you must unstuff the file on a Mac OS or OS X system.)

Start up the Revolution development environment by double-clicking the Revolution application inside the folder. If you want to uninstall Revolution, simply drag the Revolution folder to the trash.

On Mac OS systems, the first time Revolution starts up, it sets a preference in the File Exchange control panel to associate Revolution files created on other platforms with the application. (Specifically, it maps the extension ".rev" to the creator "Revo" and the type "RSTK".) This ensures that Revolution files you download or copy from PC-formatted media will be properly registered in the Finder as belonging to Revolution.

To install Revolution on a Darwin system, download the file <http://www.runrev.com/revolution/engines11/Darwin.gz> and decompress it into a directory. The Darwin version of Revolution is intended for development of command-line scripts, and does not support the Revolution development environment or user interface.




INSTALLATION ON UNIX & LINUX SYSTEMS

To install Revolution on your system, first download the correct file for your Unix flavor from the table below, then gunzip and untar it:

    FreeBSD and BSDI: <http://www.runrev.com/revolution/engines11/unix/bsd.tgz>
    HP-UX: <http://www.runrev.com/revolution/engines11/unix/hp9k700.tgz>
    SGI IRIX: <http://www.runrev.com/revolution/engines11/unix/iris.tgz>
    Linux Intel (see also "RPM Linux installation" below):   
       <http://www.runrev.com/revolution/engines11/unix/linux.tgz>
    Linux PowerPPC: <http://www.runrev.com/revolution/engines11/unix/linuxppc.tgz>
    AIX: <http://www.runrev.com/revolution/engines11/unix/rs6000.tgz>
    Solaris x86: <http://www.runrev.com/revolution/engines11/unix/solintel.tgz>
    SPARC Solaris: <http://www.runrev.com/revolution/engines11/unix/solsparc.tgz>
    SPARC SunOS: <http://www.runrev.com/revolution/engines11/unix/sparc.tgz>

(You can also download these files from the Runtime Revolution FTP site at ftp.runrev.com.)

To start up the Revolution development environment, run ./revolution. If you want to uninstall Revolution, simply delete Revolution's directory.

--- RPM Linux installation ---

There are two options for installation on Intel-based Linux systems. You can use the Redhat Package Manager (RPM) distribution or the standard .tgz distribution described above.

To install the RPM distribution, download the file
<<http://www.runrev.com/revolution/engines11/unix/revolution-1.1.1-i386.rpm>> from the Runtime Revolution web site.

Then install Revolution as root by running the following shell command:
  rpm -ivh revolution-1.1.1-i386.rpm

Revolution is installed in the /opt/ directory. 

To start up the Revolution development environment, run ./revolution. If you want to uninstall Revolution, run the following shell command:
  rpm -e revolution-1.1.1




INSTALLATION ON WINDOWS SYSTEMS

To install Revolution on your system, download the file <http://www.runrev.com/revolution/engines11/revolution.exe> from the Runtime Revolution web site, then double-click the file to install it. (You can also download Revolution from the Runtime Revolution FTP site at ftp.runrev.com.) This creates a folder called "Revolution", which contains all components of the development environment.

Start up the Revolution development environment by double-clicking the Revolution application inside the folder, or choose Programs > Revolution 1.1.1 > Revolution 1.1.1 from the Start menu.

If you want to uninstall Revolution, remove it using the Add/Remove Programs Control Panel.




LICENSE INFORMATION AND THE STARTER KIT

Upon installation, Revolution is configured in Starter Kit mode. The Starter Kit edition includes all functionality of Revolution, including the ability to build applications for all supported platforms. (The only limitation is on the length of scripts you can create in a single object.) For more information on working productively within the Starter Kit edition's script-length limitation, see "Using the Starter Kit" in the Revolution documentation.

You are welcome to use the Starter Kit to create working applications for any platform. Applications created with any edition of Revolution, including the Starter Kit edition, may be redistributed on any supported platform. Please see the License file in the Revolution folder for specifics.

To remove the length limit on scripts, you must purchase a license for Revolution. Multi-user, cross-grade, and educational discounts are available. To see license prices and options, or to purchase a license, choose "License Revolution" from the Help menu and follow the instructions.

If you are upgrading Revolution from a previous version, choose "License Revolution" from the Help menu to re-enter your license key.




VERSION HISTORY:

Version 1.1.1: April 1, 2002
- Made changes and updates to Internet support.
- Added support for communicating with arbitrary drivers.
- Added support for Valentina databases and OS X database support
- New Transcript terms:
close driver, dontUseQTEffects, libURLErrorData, libURLftpUpload, libURLSetFTPMode, libURLSetFTPStopTime, libURLSetLogField, libURLVersion, open driver, read from driver, revCopyFile, revCopyFolder, revdb_columnisnull, revdb_columntypes, revdb_dbtype, revdb_querylist, revdb_queryblob, revDeleteFolder, revMoveFolder, revRotatePoly, write to driver
- Changed Transcript terms:
answer color, cachedURLs, htmlText, http, launch, open process, rename, revdb_connect, URLStatus

Version 1.1: November 5, 2001
- Changed file format to accommodate new features.
- Added SQL, Oracle, and ODBC database capability.
- Shifted HTTP support to Internet library and added FTP support.
- Added support for OS X.
- Removed support for Alpha Digital UNIX and SCO Open DeskTop
- New Transcript terms:
aliasReference, alphaData, alternateLanguages, answer color, answer effect, armedIcon, backgroundBehavior, blendLevel, combine, create alias, dateFormat, delete URL, disabledIcon, extents, flip, imageData, imageSource, intersect, jpegQuality, keysDown, linkClicked, linkColor, linkHiliteColor, linkText, linkVisitedColor, longFilePath, maskData, matrixMultiply, median, merge, monthNames, mouseDownInBackdrop, mouseUpInBackdrop, paintCompression, popup command, QTEffects, record sound, recordFormats, recording, recordLoudness, resetAll command, revdb_closecursor, revdb_columnbyname, revdb_columnbynumber, revdb_columncount, revdb_columnlengths, revdb_columnnames, revdb_commit, revdb_connect, revdb_connectionerr, revdb_connections, revdb_currentrecord, revdb_cursorconnection, revdb_cursorerr, revdb_cursors, revdb_disconnect, revdb_execute, revdb_isbof, revdb_iseof, revdb_movefirst, revdb_movelast, revdb_movenext, revdb_moveprev, revdb_query, revdb_recordcount, revdb_rollback, rotate, shortFilePath, showFocusBorder, specialFolderPath, split, standardDeviation, stop recording, transpose, union, useSystemDate, visited, visitedIcon, waitDepth, weekdayNames
- Removed Transcript terms:
executionError (supplanted by errorDialog)
scriptError (supplanted by scriptParsingError)

Version 1.0 - July 1, 2001
- First version of Revolution.




LIMITATIONS AND KNOWN ISSUES:
Please report other bugs or issues to <support@runrev.com>.

- Font, size, and style changes cannot be applied when the text selection is empty (a blinking insertion point) and no objects are selected. To apply a font, size, or style change to text, select the text, then choose the correct command from the Font menu.

- Copying and pasting between programs supports only plain text, and styles are lost. (Copying and pasting text within Revolution preserves styles.) To work around this limitation, see the "htmlText" property in the Transcript Dictionary section of the documentation.

- Selections in an image object cannot be copied (although you can copy and paste an image object as a whole within Revolution). This issue will be resolved in the near future.

- The new open driver syntax is not yet supported on OS X.

- Setting the "explicitVars" property to true will cause instability in the Revolution development environment. This issue is being actively investigated and will be addressed in a future version.

- Scrollbar objects whose style is "scale" or "progress", when they are oriented vertically, do not have the native appearance on Mac OS and Windows systems; vertical scale and progress bars always are drawn with the Motif appearance. (This limitation does not apply to scrollbar objects whose style is "scrollbar", or to horizontal scale bars and progress bars, which are always drawn with the correct native appearance for the current platform. It also does not apply on Mac OS and OS X systems when the "lookAndFeel" property is set to "Appearance Manager", which uses the standard system routines for display of user interface objects such as scrollbars.)

- Recording a sound using the "record sound" command may produce unexpected results (such as a garbled sound file) if using the 22KHz ("better") sound quality with some versions of QuickTime. This issue is being actively investigated.

- Double-clicking a Revolution stack file to launch the Revolution application will open the stack without loading the development environment (which includes Revolution's menu bar). This behavior allows you to test your stack outside the development environment before you build a standalone application from it, but means you cannot edit stacks opened in this way because the development environment is not present. This issue is being actively investigated and will be addressed in a future version.

- Revolution does not fully support double-byte character sets (such as the ones used for Asian languages). This issue is being actively investigated and double-byte capability will be fully functional in a future version.

- Choosing "Import As Control" > "Snapshot" from the File menu causes the windows to be incorrectly displayed when they reappear.

- The "mouse" function does not always correctly report the state of the mouse button at the time it's called. This issue will be addressed in a future version. In general, it is recommended to handle the "mouseDown" and "mouseUp" messages rather than check the state of the "mouse" in a handler.

- On Mac OS and OS X systems, file paths are limited to 255 characters. This issue will be addressed in a future version.

- On Mac OS systems, the InputSprocket extensions have been reported to cause instability of some applications, including Revolution. If you experience instability and you do not require the sprocket extensions, try turning these extensions off in the Extensions Manager control panel.

- Some Windows graphics drivers have compatibility problems with Revolution, in particular with images. The primary symptom is that images are drawn in the wrong colors. If you see this symptom, make sure you have the latest drivers from the vendor of your graphics card, and try turning off graphics acceleration (in the Performance tab in the System Control Panel). If this does not fix the problem, please report the bug to your graphics card vendor.

- When using QuickTime 5, the controller thumb in a player does not always update properly while a movie is playing.  The workaround is to do something that will force the controller to be redrawn: for example, settting the player's "showController" property to false in a "preOpenCard" handler and back to true in an "openCard" handler, or the reverse with the "alwaysBuffer" property. This problem also does not appear if the stack's "resizable" property is set to false. This issue is being actively investigated with Apple.

- The "shell" function and "open process" command are not yet supported when using the OS X engine. (They are supported using the Darwin engine.) The "send to program" command is also not yet supported, but you can use the do as appleScript form of the "do" command as a workaround.

- In OS X, the accept datagram form of the "accept" command ignores datagrams received after the first one. This issue will be fixed in the next version.

A few cosmetic issues remain on OS X systems. These include the following:
- Default buttons do not "throb".
- Sheet dialogs are not yet supported.
- Text is drawn with QuickDraw, so text may look slightly different in Revolution and Revolution applications.
- In modal dialog boxes, mouse clicks are blocked if a tool tip is visible.
- The interactive form of the "import snapshot" command does not display a "marching ants" rectangle.
- Menu buttons whose "menuMode" is "pulldown" do not have the Aqua appearance. (This does not apply to menus displayed in the menu bar.)

If you encounter issues or problems not listed above, please report them by email to <support@runrev.com>, describing the problem in as much detail as possible. In particular, please include:
    * the platform and operating system version you were using
    * the steps that caused the problem to appear
    * whether the problem is reproducible

Revolution development environment errors are logged to a file named "sessionlog.txt", which is erased each time you start up Revolution. The file is located inside the folder "revolution/components/save/". If you are experiencing problems, please send this file to <support@runrev.com> along with your bug report.




CONTACTING RUNTIME REVOLUTION:

If you have any questions, comments, suggestions or criticisms about any aspect of Revolution, we want to hear from you - so please do not hesitate to get in touch. To contact us, send email to <support@runrev.com>, or choose "Revolution Support" from the Help menu.

We hope you enjoy Revolution!

 2000-2002, Runtime Revolution Ltd. All Rights Reserved Worldwide.
Portions 1992-2002 MetaCard Corporation.
Use and distribution of this application and all associated files is restricted by the Revolution Licensing Agreement.