CocoaSuite Manual

Introduction

CocoaSuite is suite of utilities that enhance the ways in which you can control Cocoa applications. It allows you to:

Add new or reassign existing menu shortcuts
Execute any menu command through customizable Mnemonics
Execute any menu command via customizable mouse gestures
Use the track pad on your laptop as virtual scroll wheel or jog dial

Additional features:

A Text Snippets menu enables insertion of arbitrary text anywhere in your applications where text input is possible
A Scripts menu that lets you execute Scripts (AppleScript, shell scripts perl, python etc.) from your applications

All features can be mixed freely. For instance, you can assign a Menmonic to insert text into your application. Or use a Mouse Gesture to execute a script. The possibilities are endless.

CocoaSuite also works with Java Swing applications when they are run using java 1.4 or later.

Menu Shortcuts

To modify menu shortcuts select Cocoa Suite/Menu Shortcuts... from any Cocoa Applications main menu. A panel like this one will appear:

The pull down menu in the first column reproduces the entire menu from your application. Here you select the menu entry to be modified. Click the Add button to add a new menu shortcut.

The second column represents the current or newly assigned menu shortcut. With any row selected, simply type the shortcut you wish to assign.

The third column is the global flag. If checked, this menu shortcut will be activated in all Cocoa Applications where the corresponding menu entry is found.

Select any shortcut and click the Delete button to delete that shortcut.

Note: When you delete a shortcut, the corresponding menu entry will not revert to its previous menu shortcut, it will retain the shortcut just deleted. The change will only be visible the next time you start the application. Newly-defined shortcuts, however, will go into effect immediately.

Note: While a row is selected, Cocoa Suite intercepts all shortcuts. That means you can not use Command-W to close this panel.

You must close this panel by clicking OK in order to activate the new settings. If you close the panel clicking the Cancel button or any other means, Cocoa Suite will revert to the settings in effect when the panel was opened.

Note: In current OS X versions, Command-H to hide an application is implemented at a higher level, before Cocoa Suite has a chance to intercept it. That means that you can not assign Command-H to another menu command. You can, however, assign another menu command to hide the application. In that case, both Command-H and your newly assigned shortcut will hide the application.

Note: In some applications, some menus do not exist until they are accessed for the first time after the application is launched. An example is the Message/Transfer menu in Mail.app. Because of this, any shortcuts assigned to such a dynamic menu will only become accesible after you visit this menu with your mouse. This must be done each time the application is launched to activate the shortcut.

Tip: Not only can you define new menu shortcuts, you can also redefine existing ones. Example: Most NeXTSTEP/OPENSTEP users will be used to Cmd-D being Find Previous. In some OS X applications that is true, such as TextEdit for example. However in Safari Cmd-D is Add Bookmark. Thanks to CocoaSuite you can now set Cmd-D to the more traditional Find Previous.

Mnemonics

First, we need to explain what Mnemonics are. Mnemonics are extensively used in machine language programming. For example, in some processor code the number 42 could be the command to multiply two values. It would be very hard to memorize all those numbers and their meanings, especially when they change amongst processor types. So the Mnemonic mul is commonly assigned to the number representing the multiplication command, and it is the job of an assembler program to translate the mnemonics into the numbers the processor will understand.

Cocoa Suite will let you assign Mnemonics to menu commands. For example, let us assume you occasionally need the menu command Format/Text/Align Right, but not frequently enough to remember the official shortcut. You could assign the Mnemonic ftar to this menu command.

Mnemonics are especially useful with Text Snippets (see below). For instance, you could assign the mnemonic adr to a menu entry in the Text Snippets menu containing your postal address.

To define a Mnemonic, select Cocoa Suite/Mnemonics... from any Cocoa Application's main menu. A panel like this one will appear:

The pull down menu in the first column reproduces the entire menu from your application. Here you select the menu entry to be executed for this Menmonic. Click the Add button to add a new Mnemonic.

The second column represents the Mnemonic. Double-click and type in the desired Mnemonic here. Hit the enter key to lock it in.

The third column is the global flag. If checked, this Mnemonic will be activated in all Cocoa Applications where the corresponding menu entry is found.

Select any Mnemonic and click the Delete button to delete that Mnemonic.

Note: You must close this panel by clicking OK in order to activate the new settings. If you close the panel clicking the Cancel button or any other means, Cocoa Suite will revert to the settings in effect when the panel was opened.

To use Mnemonics, select Cocoa Suite/Mnemonic... from any Cocoa Applications main menu, or, more commonly, use the keyboard shortcut for it. By default Cocoa Suite will assign F12, (that can esily be changed by changing the appropriate Menu Shortcuts entry). This panel will appear:

Now simply enter the mnemonic (e.g. ftar as described above), and the corresponding menu command will be executed.

Note: As soon as Cocoa Suite finds a matching mnemonic it will automatically close the Mnemonic input panel and execute the corresponding menu command. That means you can not begin a longer mnemonic with a text sequence already in use for a shorter mnemonic. Example: If you previously assigned sup as mnemonic, you could not use the word super as new mnemonic, because the Mnemonic input panel would close as soon as it ses the input sup and execute the corresponding command.

Note: In some applications, some menus do not exist until they are accessed first. An example is the Message/Transfer menu in Mail.app. Because of this, any mnemonic assigned to such a dynamic menu will only become accesible after you visited this menu at least once with your mouse.

Tip: The F12 default key for Mnemonics is just a predefined Menu Shortcut. You can change it just like any other Menu shortcut.

Virtual Jog Dial

Note: The virtual jog dial function was conceived especially with laptop owners who use the track pad in mind. Although the instructions below are written for track pad users, they can also be used with graphic tablets or the mouse.

You may be familiar with a Jog Dial. A Jog Dial can be found on any iPod, some video recorders and/or their remote controls, digital video processing equipment and many other devices. Basically, it is a circular-shaped knob of sorts that can be rotated left or right to trigger some kind of scrolling event, or to fast forward or reverse through music or video.

Cocoa Suites virtual jog dial allows you to quickly scroll through long documents or web pages, or to operate any user interface element containing a scroll bar.

By default Cocoa Suite will use Option-Command to activate the virtual scroll wheel. The chapter Preferences explains how to assign other modifiers instead.

By pressing and holding these modifier keys, the track pad on your laptop will be converted into a virtual jog dial. Now by simply moving your finger in a circular motion over the track pad you can scroll.

In addition to the function of a physical jog dial, Cocoa Suite's virtual jog dial detects how you start your motion. If you start by moving your finger up or down, Cocoa Suite will scroll up and down. If you start by moving your finger left or right, Cocoa Suite will scroll left or right. Once the initial movement is detected, the scroll process will be locked into either horizontal or vertical motion. Continue moving your finger in a circular fashion to scroll, you can reverse the direction at any time.

Cocoa Suite expects you to start your motion near the top edge for horizontal scrolling, or near the right edge for vertical scrolling.

To switch between horizontal and vertical scrolling you need to briefly release and then hold again the modifier keys. This will allow you to scroll in a new direction.

Tip: By moving your finger in larger circles you will scroll faster!

Virtual Scroll Wheel

Note: The virtual scroll wheel function was conceived especially with laptop owners who use the track pad in mind. While the instructions below are written for track pad users, it can also be used with graphic tablets or the mouse.

Note: As most users feel the jog dial function is more powerful, the virtual scroll wheel function is disabled by default. Please see the chapter Preferences for instructions how to enable it.

Cocoa Suite lets you convert your track pad into a virtual scroll wheel. Three different modes are available:

Mixed horizontal and vertical
Horizontal only
Vertical only

Use is easy: Press the modifiers assigned to any of the virtual scroll wheel functions, and start moving your finger over the track pad. With the Horizontal only virtual scroll wheel function move your finger left or right to scroll left or right. With the Vertical only virtual scroll wheel function move your finger up or down to scroll up or down. And with the Mixed horizontal and vertical virtual scroll wheel function move your finger in either direction to scroll.

When you reach the end of the track pad, simply lift your finger and move it to the opposite end of the track pad and continue, just as you would do to move the mouse.

Text Snippets

The Text Snippets Menu offers you a quick and easy way to access frequently used Text Snippets such as Addresses, Mail Signatures, phone numbers, frequently used sections of text in correspondence, or even entire templates for letters, programs, and any other frequently used sequence of text.

Note: It is not recommended to use Text Snippets for passwords, credit card numbers or other sensitive information, as the text is stored in your home partition without any encryption!

To add a text snippet, select Cocoa Suite/Text Snippets/Manage Text Snippets... from any Cocoa applications main menu. A panel like this will appear:

On the left hand side of this panel is a list of previously defined text Snippets, along with a column used to mark a Text Snippet as global (accesible from all Cocoa applications). When you select one of these text snippets, the text area on the right will show the contents

To define a new text snippet click the Add button. Double-click in the newly added row and enter a menu title for the text snippet in the new empty row in the list on the left, and optionally click into the second column to make the snippet as global (available from all Cocoa apllications). Enter the text for this Text Snippet in the text area on the right side of the panel.

To delete a Text Snippet select it in the list on the right hand side of the panel, and then click the Delete button.

Once one (or more) text snippet has been defined and you close the panel via the OK button, a new menu entry for it using the title you just entered will appear in the Text Snippets menu. Selecting this menu entry will cause the assigned text to be inserted at the current text cursor position.

Note: You must close this panel by clicking OK in order to activate the new settings. If you close the panel clicking the Cancel button or any other means Cocoa Suite will revert to the settings in effect when the panel was opened.

Tip: Assign a Mnemonic, Menu Shortcut or Mouse Gesture to your frequently used Text Snippets!

Scripts

Note: To define a new script for the scripts menu you need to be familiar with one or more of the various scripting languages available under OS X. However please visit the Cocoa Suite web site for a growing repository of helpful scripts for all kinds of applications. They are easy to install.

The scripts menu is modified just like the Text Snippets menu, please read that chapter.

The big difference is what happens when you select a script defined in the scripts menu. Cocoa Suite will attempt to execute the script. What happens is of course entirely up to the script.

Note: script developers: By default Cocoa Suite will attempt to execute the script with AppleScript. However if the first line of script begins with the character sequence #!, the script will be saved with the executable flag set, and Cocoa Suite will attempt to execute that script. This allows you to use any scripting language available on or for OS X, such as shell script, perl, python and many others.

Gestures

What are Gestures?

Gestures allow you to execute functions in a program by clicking a mouse button (optionally with a modifier key pressed) and move the mouse in a certain pattern. The gestures are represented by a combination of up, down, left and right motions. The gesture decoding engine is quite forgiving. For instance a gesture left - down - right - up - left can be achieved by drawing an uppercase G. This allows for gestures that are easily memorized. Gestures are actually much more intuitive than it may sound.

It is unclear where the notion of gestures first appeared. Most sources mention them in combination with experimental pie menu implementation in the 1970s. Lately they have been found in the web browsers Opera and Mozilla.

Tip: Gestures are especially useful in situations when you are using your mouse and don't want to move your hands to the keyboard to execute a command.

How to Use Gestures

Using gestures is easy, and after little training, comes surprisingly natural:

The application must be active (selected), not in the background.
While the mouse is over a window or panel belonging to the application, press any modifiers and/or mouse buttons configured to activate the gesture function. By default that is control-option (no mouse button) for laptop users, control-option+mouse button for single button mice, and the middle mouse button (scroll wheel) for mice with 3 or moure buttons. See the Chapter Preferences for instructions how to change this.
The gesture cursor (an small image looking like a mint candy) appears
Make the gesture
Release the mouse button and/or modifiers

To abort a gesture, simply hold the mouse still without releasing any button until the gesture cursor disappears. Alternatively, press another modifier or mouse button in addition to the ones pressed.

You can use a combination of mouse key and modifier that is already in use by the system. For example, option and the left mouse button. Option-click work as usual, Cocoa Suite will detect there was no gesture input and forward the mouse event unmodified.

If you need to perform an Option-drag, wait until the gesture expires and the normal mouse cursor reappears, Now you can proceed as usual.

Defining Gestures

Cocoa Suite comes with some built-in gestures for a few programs. It also comes with some default gestures for menu commands common in most Cocoa programs. You can overwrite any of the predefined gestures and make as many new gestures as you like. Any gesture can be either local to that application or global.

To modify gestures select Cocoa Suite/Gestures... from your application's main menu. A panel like this one will appear:

The pull down menu in the first column reproduces the entire menu from your application. Here you select the menu entry to be executed for this Gesture.

The second column shows you pictograms of defined gestures, and the third column is the global flag. If checked, this gesture will be activate in all Cocoa Applications where the corresponding menu entry is found.

To delete a gesture, simply select a row and click on the Delete button. To add gestures click on the Add button and an empty gesture definition appears.

To assign or change the function of a gesture, select a menu entry in the first column.

To set or modify the gesture, double click on the gesture field in the second column. A large (mostly empty) panel appears, Make a gesture, the panel disappears and the a pictogram of the gesture entered will be displayed.

Note: Overlapping lines are drawn at a slight angle to each other in the pictogram, so you can tell them apart. For example, a left-right movement appears as a "greater Athan" symbol. An up and down movement looks like an inverted "V", etc. When you make the gesture you would still make a left-right or up-down gesture, the movements should not be at an angle, although Gestures recognition engine is tolerant of some degree of variation.

It is also possible to assign gestures to context menu commands (the context menu is the one you get when you control-click or right-click your mouse button in the window):

Open the window or panel that contains the desired context menu.
Define a gesture as explained above, but single click instead of double click on the gesture column (so that the new entry is selected).
Right or control click in the previously opened window or panel and select the desired contect menu entry. It will not be executed but rather be assigned to the gesture.
To stand apart from the other commands, Context Menu commands will be prefixed with Context Menu: in the Gestures panel.
Remember to select OK to close the Gesture panel if you want to keep the Gesture you just created.

An example for this is the Open in new window context menu entry available in most web browsers when you right-click or control-click on a link, you can assign a Gesture to this.

To execute a Context Menu gesture, start making the gesture over the link. It is the gesture start point that decides which context menu will be used.

Piggy-Backing Gestures

You can assign the same gesture multiple times. When you then use this gesture, Cocoa Suite will try any matching entry starting from the top. Any entry for which the menu command either can not be found or is disabled will be skipped, and the first enabled one will be executed. Note that you can rearrange gesture definitions via drag and drop to change this order.

This is handy in a number of situations. For example, many programs have the Save menu entry disabled until a file was saved first with Save As... and has a file name assigned. In that case, you can assign the same gesture to Save and Save As... (make sure the definition for Save is listed first). That way you can always use the same gesture to save a file, no matter if it has a file name assigned or not.

Another example is Safari or Camino, where you can assign the same gesture to Close Tab and Close Window.

Preferences

The Preferences panel let's you modify the behavior of Cocoa Suite. You can get to the Preferences panel by selecting Cocoa Suite/Preferences... from any Cocoa applications main menu. It consists of 3 different panes: Mouse Setup, Flavor and Advanced. These panes are described below.

Note: Any change made to Cocoa Suite/Preferences is global to all applications.

Mouse Setup

This pane allows you to select which combination of modifiers and mouse key activates the various functions Cocoa Suite offers. For each function you can define two separate combinations. This is useful for laptop users that use their laptop both with and without an external mouse.

The pane looks quite complex, but upon closer examination you will see that it is fairly self- explanatory. On the left-hand side is a checkbox for each modifier/mouse combination to enable/disable it. In the Modifier Keys section you select the desired modifiers (none, one or multiple selection allowed), and in the Mouse Buttons section you select which mouse key (or None).

The default values should give you a pretty good starting point.

Note: The name of the function is grayed out when the enable box is not checked, and it is red if either a duplicate or an invalid combination is detected. The only invalid combination is just the left mouse button with no modifier, as that would interfere too much with normal use of the mouse.

Flavor

This panel allows you to select the color scheme for Cocoa Suite to please you and to work with your overall color schemes.

Select one of the predefined colors, or find your own color by moving the slider at the bottom of the panel. The color will be used for the various cursors, the trail of the mouse gestures and the Cocoa Suite icon in the Cocoa Suite menu entry.

Advanced

You should not normally need to change anything in this pane:

The minimal gesture size determines the sensitivity to mouse gestures. 15 pixels should be a good value for almost any situation, and it is not recommended to change it. In very special circumstances (for instance when using a pen on a graphic tablet where you are used to making smaller movements) reducing that value slightly may help.

The abort gesture after setting indicates the time after which mouse gestures time out. While learning gestures it may help to increase the value a little from its default of 500 milliseconds, 750 or 1000 might be a good choice. For situations where you frequently need the gesture key/mouse combination selected for gestures also for their normal function, it may help to reduce the timeout to around 300 milliseconds.

Make window under gesture key is useful in situations where you may want to make gestures on windows in the background (those not active or selected). For example, closing or minimizing a window you are not currently using. This only works for windows of the same application as the selected/active window. Typically you should be fine with leaving this option enabled.

Draw gesture feedback, when selected, causes mouse gestures to leave a trail while you draw them. That makes gesture input a little easier. However, on slow machines or machines with little memory, this can be turned off for performance reasons.

Change Log

Version 1.0: First Release

Minor updated to localizations
Fully functional demo, expires after 30 days unless licensed

Version 1.0 RC: Release Candidate

Added Japanese localization and manual, with many thanks to Tai!
Added French localization, thanks to Renaud Préat!
Fix typos
Minor visual changes

Version 1.0 Beta 1: Beta test

Feedback

Please send any feedback and bugreports to support@cocoasuite.com

CocoaSuite is a product by BITart

CocoaSuite Manual

Contents