cocoaModem Macros

Kok Chen, W7AY [w7ay (at) arrl (dot) net]
Last updated: July 1, 2006

Index (User's Manual - Macros)

General Information
Aural Monitor
Accessibility (Incremental Speak and Voice Assist)
Macros
RTTY Interfaces
PSK Interface
MFSK Interface
Hellschreiber Interface
CW Interface
ASCII Interface
SITOR-B Receiver
HF-FAX Receiver
Versions
Part II



Macros

Macros in cocoaModem are operations that allow you to represent text and compound actions with the press of a single button.

In the simplest form, macros are used to send QSO messages that you use very often, such as CQ messages, sign off messages, etc.

cocoaModem macros also allow you to fetch strings that have been saved elsewhere in the cocoaModem database.  These strings include your own call sign, the call sign of the station you are working, brag tapes, etc.

cocoaModem also has what is called “event macros.”  These macros function the same way as if a particular button in cocoaModem is clicked and in some cases represent functions that are not available through buttons.

Any simple text inside a macro body is treated just as a keystroke that you have typed, such as text that you have typed into the transmit text view in the RTTY interface.

The simplest macro is actually not a macro at all but a text formatting nomenclature for non-printing characters.  I have adopted some of the common representation that is already familiar to C language programmers and Unix users.

The cocoaModem text formatting macros in cocoaModem are

	\n	linefeed (generates a Baudot CR/LF (RTTY), and a newline in PSK31)
	\r	carriage return (Baudot CR in RTTY, carriage return in PSK)

\n serves as a newline character for both RTTY and PSK31.  In the RTTY interface, this macro causes cocoaModem to send a carriage return followed by a linefeed character.  This makes it compatible with mechanical Teletype machines.  In PSK31 mode, it sends a single newline character.

Use \n wherever you usually type in a carriage return.

\r is useful right before sending a \n in RTTY to someone who uses an old mechanical teletypewriter as a way to insert extra delays for the teletypewriter’s carriage to settle down. You almost never need to do this nowadays.

cocoaModem string macros (which retrieve strings from different databases) start with a percent character, some of these are

	%c	send your own call sign (see User Info Sheet)
	%C	send the call sign of the station you are working (see QSO Info)
	%h	send your own name (see User Info Sheet)
	%b	send your brag tape (see User Info Sheet)

All of the above string macros assume that you have the proper fields already filled in in the database.  Read the sections in Information Panels to find the location of these strings and how the data is stored in the locations.

The following macros switches cocoaModem's state between receive and transmit modes.

	%[tx]	switch mode to Transmit
	%[rx]	switch mode to Receive

You can invoke up to six arbitrary AppleScripts from a Macro. The "Macro Scripts" are defined in the AppleScript tab in cocoaModem's Preference panel:

You use the Browse button to navigate to, and select a scpt file. These AppleScripts are known as [a0] through [a5]. You can then insert %[a0] through %[a5] inside the macro bodies (just as you would insert %[rx] and %[tx]).

The %[aN] macros can be used standalone (i.e., using a Macro button to do nothing but invoke some external AppleScript). They can also be part of some other macros.


Macro Dictionary

An online cocoaModem macro dictionary is available by going to the Window menu in the Menu Bar and selecting the Macro Dictionary item.

The dictionary is organized in multiple sections as an outline view. Click on the arrow next to a topic to expand the view to show the macros that are associated with that topic. See Figure 10 below.

Figure 10 - Macro Dictionary

Executing Macros

Macros are executed by pressing one of the buttons in the row of buttons that is below the transmit text view of the RTTY and PSK Windows (see Figures 8 and 9).

Unused macros (like those shown in Figures 8 and 9) have the “Mcr #” caption on them. The following section shows how to change these labels and to create live macros (and also how to make unused macros buttons show up with a blank caption).

In addition to clicking the macro buttons themselves, macros can also be executed by using keyboard shortcuts.


Editing Macros

Macros are created and changed by pressing the Edit button at the end of the row of the Macro buttons.

When you press Edit, a message sheet will drop from the cocoaModem window.

A Cocoa Sheet is a dialog that is attached to an application window. It was introduced with MacOS X and you may have used it in places like the Printer Setup dialog without even realizing it.

Figure 11 - Macro Sheet

Each row in the macro sheet corresponds to one of the twelve Macro buttons at the bottom of the interface windows. There are two text fields associated with each macro button. The shorter text field will become the caption for the corresponding macro button (choose any short name that you like, including spaces and symbols) and the longer text field is the macro body itself.

HINT: If you don’t like the appearance of the “Mcr #” captions on unused macro buttons, you can replace their captions in the macro sheet with a single space character, but leaving the macro body field itself empty (to make sure that the message field is empty, select all of the message field by applying command-A after clicking on the message field, and then hit the delete button).

Each interface mode in cocoaModem has its own set of macros. If you want to share macros between the different modes, you can always Export from one macro sheet and Import it into another macro sheet.


Option and Option-Shift Macros

Once you have edited the macros so that the buttons no longer read Mcr 1, Mcr 2, etc., you might notice that the captions in the Macro buttons will change back to Mcr 1, Mcr 2, etc. whenever you hold down the Option key while the mouse is inside the cocoaModem window.

The reason is that cocoaModem supports three different sets of Macros for each interface mode. Holding down the Option key gives you the second set of macros and holding down the Option and Shift keys simultaneously gives you a third set of macros that you can use. There is no difference between these sets except for the need to press the option or the shift keys.

You edit the different macro sheets in a similar fashion. If you click on the Edit button while the Option key is depressed, you will be editing the second set of macros. The header at the top of the macro sheet reminds you which macro set you are editing is.

Similarly, if you first depress both the Shift and Option keys before clicking the Edit button, the option sheet that appears is the third (Shift-Option) macro set.

When you depress the Option and/or the Shift keys, the captions in the macro buttons will change to reflect the set of macros you have selected. This allows cocoaModem to have 36 different macros per mode, without adding to the screen clutter.


Keyboard shortcuts for Macros

Instead of clicking on the row of macro buttons, you can also use keyboard shortcuts to invoke the macros. Command-1 will invoke the first macro, Command-2 will invoke the second macro, etc. Macro 11 is invoked with Command-(minus sign) and Macro 12 is invoked with Command-=.

The alternate sets of macros are similarly invoked. For example Command-Option-1 invokes the first macro in the second set and Command-Option-Shift-5 invokes the fifth macro of the third set (this is actually more natural than this description leads you to think!).


Importing and Exporting Macros

Macros can be saved to a file and later retrieved.

When you edit a macro sheet, you will see two buttons at the bottom left of the sheet for importing macro into and exporting the macros out of that sheet. These buttons take you to standard file opening and saving dialogs. You can navigate to any folder that you have access to retrieve or save a sheet of macros. Note that each macro sheet (normal, option and option-shift) is independently imported and exported.

You can copy from one sheet to the other by simply exporting from one sheet and importing into the second sheet. You can export a macro sheet from RTTY and import that into a PSK macro sheet. Similarly, you can e-mail an exported sheet to another cocoaModem user. Finally, it is a good idea to export all your macro and stash the files somewhere in case you need it in the future.

Like the Preference file, an exported macro sheet is in a standard XML formatted file and can be opened using the MacOS’s Property List Editor. Since it is just a text file, it can also be opened using a text editor such as TextEdit or BBEdit. It is however, not recommend that you directly edit the files. The best way to change a macro in a sheet is to import the sheet, edit the macro within cocoaModem and then export the sheet when you are through editing.

• cocoaModem > 
• User's Manual > 
• Macros >