OSA Menu 1.1
Written by Leonard Rosenthol
Copyright ©1992-1997, Leonard Rosenthol.

Installation

If you are reading this, you've already done the installation!

In addition to the files contained in this folder, the actual OSA Menu extension has been installed into your Extensions folder (which is in your System folder). That's why you had to restart your Mac, so now you're all ready to use OSA Menu.

System Requirements

OSA Menu requires System 7.0 (or later) and an OSA compliant scripting language (AppleScript, UserLand Frontier, QuicKeys, tclScript, MacPerl, etc.). OSA Menu is 32-bit clean, '040 cache, PowerMac, AV and virtual memory compatible. In other words, as long as you have System 7.0 (or later) and a scripting language it will work!

Description

The OSA Menu is an iconic system menu (like the Help menu) that appears on the right side of the menu bar. Its menu items are scripts: choose an item from the menu and the script will run. Some commands are always available, and some are only available within particular applications.

Generally the target of the script is the active application, and scripts that operate on the user selection are particularly useful. Scripts in the OSA Menu act like extensions to the command set of the application.

The main advantage to scripts in the menu is that you can call them up with one mouse click without leaving the current application. This is most useful in applications that are scriptable (such as the Finder, StuffIt, FileMaker Pro, and many others), but require you to switch to another application. BUT NO MORE!! Now you can just choose the script you want to run from the OSA Menu.

The scripts live in a folder called "Scripts" in your System folder, and each application gets its own subfolder of the "Scripts" folder with the scripts specific to that application as well as a "Universal Scripts" folder for scripts that you wish to access in all applications.

What's in the Menu

The menu has four parts:

• The top menu item is "About OSA Menu" which displays an About box.



• The second section contains the fixed commands. There are three of them:



• Start Recording, which turns on the OSA recorder. When recording, this menu item reads "Stop Recording".



• Open Script Editor, which will allow you to quickly launch your script editor of choice



• "Preferences", which allows you to configure some aspects of OSA Menu.



• Next are the universal scripts, which always appear.



• At the bottom are the scripts for the active application.

At the end of each set of scripts is an underlined command that, when chosen, tells the Finder to open the folder for those scripts. For instance, when FileMaker Pro is active there is an 'Open " FileMaker Pro Scripts" Folder' command that opens the "FileMaker Pro Scripts" folder. These folders are like the Apple Menu Items folder: any script files placed in them immediately appear in the scripting menu. They must be compiled scripts (including Applets and Droplets), not text files. You can also place folders in these folder, to create a hierarchy of scripts to help you organize your scripts.

Command Keys

It is possible to assign a command key to a script by using a special naming convention. If the name of a script ends with a '\' followed by another character, then that character will be used as the command key for the script. For example, the script named "Time Check\T" will have a command key of "T" in the menu.

If you are using MacOS8, or running the Appearance Manager extension under System 7, you can also have "extended" command key equivalents including the use of the shift, control and/or option keys. To use them, you add the first letter of the key name after the '\' followed by a + followed by the key. For example, the script named "Special Time Check\S+T" will have a key equivalent of command-shift-T in the menu, and "More Time Checking\OC+T" would have an equivalent of command-option-control-T.

Preferences

Support UserLand MenuSharing Protocol

When checked (the default), this informs OSA Menu that you wish it to enable applications with the ability to support the MenuSharing Protocol defined by UserLand Software. The applications that are supported by default are the Finder, FileMaker Pro, NisusWriter and the MPW Shell. You can use your favorite resource editor to add applications via the 'OSMs' resource.

Display Iconic System Menu

When checked (the default), this informs OSA Menu that you wish it to display the iconic menu on the right hand side of the menu bar. Since at this time the only way to reenable this feature, after disabling it is to delete your preferences, it is recommended that you only disable this feature if you know what you're doing!

Run Scripts

You can now choose from a selection of ways in which OSA Menu will run the scripts you select. The MAIN REASON that this feature is necessary is due to some applications that make STUPID assumptions about when Apple events will arrive. If you don't have any problems when running scripts with OSA Menu, you shouldn't need to change this preference. If you do, or are just curious, here is some information about the different modes.

• Fast is the default mode for OSA Menu and is the way that OSA Menu 1.0 & 1.0.1 always worked. It works by executing the script immediately and also causing it to run faster in the current application using a technique called "send-to-self".



• Compatible is a slight variant of Fast which works much like Fast does EXCEPT that instead of executing the script immediately, it asks the Apple event Manager to wait till the next event loop and THEN execute the script.



• Very Compatible is quite different from all other methods in that instead of OSA Menu running the script, it instead uses another application (the default is OSA Runner) to run the script. Although this is the most compatible way to run scripts, it is also the slowest since it has to find & then launch OSA Runner. (see below for more details on OSA Runner, and how to use other programs to do the same job)

Edit Scripts With

Now that there are a number of other script editors available to replace Apple's, OSA Menu now gives you a choice of which one to use when editing a script, either directly via option-selecting a menu item or when an error occurs.

Run Droplets with Finder selection

When checked (unchecked by default) this will cause OSA Menu to get the list of currently selected items in the Finder and pass them to the droplet's "open" handler, just as if you had dropped them on the droplet's icon.

Use Simple Menus

When checked (unchecked by default) this will cause OSA Menu to show a simpler menu, removing all the items in the second section (Recording, Script Editor and Preferences). This feature takes effect immediately and doing so will make the "Preferences" menu item inaccessable. In order to get back to full menus, you either need to delete your "OSA Menu Preferences" file and then restart OR hold down the option key when choosing "About OSA Menu".

Special Features

• Any of the subfolders of the Scripts folder, or any particular script, can be an alias. This is very useful for network installations so that all users can have the same scripts in their menus.



• If you hold down the Option key when selecting a script from the menu, instead of running the script, the Script Editor will be launched (if not already running) and the script will be opened for editing. This will only work for standard scripts - applets and droplets will be run as if double-clicked in the Finder.



• If you hold down the Shift key when selecting a script from the menu, instead of running the script, the Finder will come to the front with the script selected.



• The "path to me" command in AppleScript is supported by OSA Menu so that if you use this in your script, you will get back the full path to where the running script is located.



• Users of Userland Frontier 5.0 (and later) and put any type of exported object into OSA Menu and have immediate access to it! Choosing it from the menu will open/run it, unless you hold down the option key in which case it will come up ready to be edited.



• Users of the Userland Frontier, can give any shared menu an icon for a title instead of text. Just set the menu title to IFAM(###) where ### is the ID of an icon family stored in either OSA Menu, the OSA Menu Prefs file (in your Preferences folder) or the OSA Menu Icons file (also in your Preferences folder). Feel free to add your own icons to the OSA Menu Icons file - that's what it is there for! Currently, the following icons are available, shown here with their IFAM numbers.

  	IFAM(128)		IFAM(132)		IFAM(136)
  	IFAM(129)		IFAM(133)		IFAM(137)
  	IFAM(130)		IFAM(134)		IFAM(138)
  	IFAM(131)		IFAM(135)		IFAM(1024)

Caveats

• If you move the Scripts folder after the Mac starts up, the folder will not able to be found by the OSA Menu and you're scripts won't work. So, don't move it!

Special Note for users of PreFab Player^TM:

In order to allow the doMenu() command available in Player to operate, OSA Menu must take some interesting liberties with your scripts. OSA Menu will automatically detect the presence of Player and if your script name starts with a <> (option-shift-v) will execute scripts in a special mode which will usually have no visible ramifications UNLESS your scripts bring up any dialogs or alerts (like via ScriptError or DisplayDialog). If you do this in your script, it is recommended that you put an "activate" command before the command that will display the alert. This will make sure that the alert comes up in the front application rather than in the back.

Troubleshooting

I hope that you won't have any problems with OSA Menu, but if you do, you can contact me using any of the following means:
Leonard Rosenthol
America Online: MACgician
Internet: leonardr@lazerware.com

*** DO NOT CONTACT MY EMPLOYER ABOUT THIS PRODUCT ***

Aladdin Systems, nor Adobe Systems have anything to do with it, other than letting me release to you for free, so please send all comments, suggestions, complaints, large sums of money, etc. to me personally!

Version History

• 1.0 - First public release (1/21/94)



• 1.0.1 - Minor update (5/9/94)



• Fixed the famous "-108 error" when running a script in the Finder



• Improved general stability and memory management



• Script properties are now updated correctly



• 1.0.2 - Feature addition update (8/9/95)



• ADDED PREFERENCES! (See "What's New in OSA Menu" for details)



• When an error occurs, you can now open the script for editing!



• Fixed a bug when run in conjunction with "DoubleTrouble".



• Option/Shift selecting items with menu key equivalents now works!



• Errors that occur when running a script are now reported nicely.



• Added explicit support for PreFab Player^TM & its doMenu command



• You can now run scripts from OSA Menu while they are open for editing!



• 1.1 - Feature addition update (x/x/x)



• Added a LOT of new features! (See "What's New in OSA Menu" for details)



• Recording, hierarchical menus, FinderMenu/MenuSharing, etc.



• apps launched by OSA Menu are now always launched in foreground



• when launching an app, OSA Menu now draws the name in the menubar



• fixed a STUPID bug which was keeping exemption lists from not working :(



• OSA Menu now creates & uses a separate preferences file & icons file



• Finally fixed the dreaded -600 error when using PreFab Player



• fixed a bug where application scripts with key equivalents wouldn't work :(



• Support for MacOS8 including the Appearance Manager



• Support for new "Simple Menus" mode

Thanks to

• Richard Clark - for writing the original "Scripting Menu" at MacHack '92.



• Jens Alfke - for writing the "Scripting Menu" that Apple never shipped, and for pioneering some techniques.



• Donald Olson - for helping out with OSA questions & being an all around dude & 1/2!



• Jon Pugh - for harassing me about problems & suggesting how to fix them!



• Jim Walker - for working with me on working around the OS8 Finder stupidity



• Aladdin Systems - for letting me work on this and release it to the world!



• Adobe Systems - for letting me continue to work on this and release it to the world!



• Apple Computer - for NOT shipping their "Scripting Menu", so that I could do mine



• The AppleScript Team, Dave Winer, Doug Baron, Don Brown, and Tim Endres - for their respective OSA compliant environments w/o which this program wouldn't make any sense!



• All my beta testers - for reporting bugs that I had to fix so you wouldn't find them!

I would like to especially recognize Chris Borton and Robert Hess. These two gentlemen were both friends of mine and important members of the Macintosh developer community who were taken away from us MUCH too soon. I miss their presence every time I write software, and their feedback doesn't come.

Legal Stuff

Although copyrighted, this software is being licensed to you for your use free of charge. However, ownership of and interest in this software shall remain with the author. Use and distribution of this software is governed by the following terms in an effort to reasonably ensure that this software will remain freely available and that no one other than the author will derive a commercial benefit from distributing this software.

LICENSE AGREEMENT

"You," "your," and the "user" refers to any person or entity which acquires or uses this software.

"Software" refers to any computer programs identified at the start of this documentation file, together with all codes, techniques, software tools, formats, designs, concepts, methods, ideas, and documentation associated with the computer program(s). The term also includes all copies of any part of the software and documentation.

"Author" refers to the author of this software, Leonard Rosenthol.

This software is owned by the author and contains valuable and proprietary information of the author. If you violate any part of this agreement, your right to use this software terminates automatically. In the event of termination of this agreement, you must destroy all copies of this software and derivatives of this software in your possession and cease distributing the same.

This software is being licensed to you as provided by the terms of this agreement.

You may:

1. Use this software on as many computers as you want at any given time.

2. Make as many backup copies of this software as you want.

3. Alter the software in any manner you see fit FOR YOUR OWN PERSONAL USE. Such altered versions should not be distributed. The creation of such derivatives shall not diminish the author's title to this software.

4. Terminate this agreement at any time by destroying all copies of this software and derivatives of this software and cease distributing the same.

You may not:

1. Create any derivative works from this software for distribution.

2. Reverse engineer, disassemble, decompile, or otherwise attempt to discover the logic or source code to this software.

OSA Menu may be distributed for non-commercial purposes.

It may also be freely distributed via wire or electronic communications (BBS's and online information systems) for the sole purpose of use by their customers.

Contact Leonard Rosenthol at the addresses within this document if you wish to distribute this software in a compilation or for commercial usage, or if you have any questions about its redistribution.

Disclaimer of warranty: In using this software, you understand and agree that this software is provided "as is" without warranty of any kind. The entire risk as to the results and performance of using this software lies entirely with you, the user. The author does not make any warranties, either expressed or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this software.

In no event shall the author be liable for any consequential, incidental, or special damages whatsoever (including without limitation damages for loss of critical data, loss of profits, interruption of business, and the like) arising out of the use or inability to use this software. Because some states do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitations may not apply to you.

Although the author would appreciate any feedback and bug reports, the author shall not be responsible for correcting any problems which you discover or otherwise help you maintain and use this software. Furthermore, the author may at any time replace, modify, alter, improve, enhance or change this software.

Complete agreement: This agreement constitutes the entire agreement and supersedes any prior agreements between you and the author concerning this software. This agreement cannot be amended, modified, or waived except in writing.

General: If any provision of this agreement shall be found to be unenforceable, it shall be deemed severed from the remainder of this agreement.

This agreement shall be construed in accordance with the laws of the State of Pennsylvania. Any arbitration or litigation relating to this agreement shall take place in the State of Pennsylvania. The parties further submit to waive any objections to personal jurisdiction of and venue in any of the following forums: U.S. District Court for the State of Pennsylvania, Pennsylvania Superior Court for Philadelphia County, Philadelphia County Municipal Court or any other forum in Philadelphia County, for any litigation arising out of this agreement.

U.S. GOVERNMENT RESTRICTED RIGHTS This Software is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the government is subject to restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at 48 CFR 252.227-7013, or in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at 48 CFR 52.227-19, as applicable. The contractor/manufacturer is Leonard Rosenthol.

All trademarks are held by their respective owners.