About - Features - Installation - Usage - Registering - Thanks - Support

AE Monitor version 1.6.0 • revised 04/26/2004

Æ Monitor tracks Apple Events as they occur and displays them in a customizable window. It also creates source code for your application to replicate captured events. Events are grouped with their replies, so it's easy to understand the sequence of events:


The main Æ Monitor window

The monitor window can be minimized to a Ticker window that displays events as they occur:

The Ticker window

 

  • Monitor one application, or enable session-wide monitoring of all processes
  • Create source code to replicate Apple Events from your application and easily export it to your development environment.
  • Event rules let you take actions as events occur, based on any number of criteria
  • Event grouping reveals sequence of events
  • Event filtering allows you to specify exactly which events to display
  • Monitor window floats on top of other applications for quick access
  • Compatible with Jaguar and Panther
    (May also be compatible w    ith 10.1, but this is untested. Not compatible with Mac OS 9.)
  • "Ticker" window minimizes display size while still displaying timely data

New features in version 1.6:

  • The Event Data Browser is a new display format for the event data area that shows a browseable tree-style list of the event data
  • The Custom AEGizmo String plugin allows you to create custom strings that incorporate AEGizmo strings for use in other development environments
  • The details area now displays application signatures
  • The Perl Command plugin has been enhanced with options to turn off the "use Mac::AppleEvents::Simple" string and allows you to choose from typeApplSignature, typeProcessSerialNumber, and typeKernelProcessID process targeting.
  • You can now adjust the data display settings from the data area contextual menu
  • The Copy command in the details window now respects the text selection

Other improvements:

  • Removed the non-functional More Information button from the REALbasic Method plugin
  • Removed the obsolete Bug Reporting button from the Preferences dialog
  • Plugin preferences are now preserved as defaults when you switch between them
  • The REALbasic method edit window Cancel window can now be activated by the Escape key
  • The event mode rule condition now works properly
  • The Perl Command is now more syntatically correct (if such a term applies to Perl :) )
  • The Perl command now escapes the ", \, $, and @ characters
  • Fixed a cosmetic problem with the Set Background Color window
  • Fixed a problem with the ticker that caused events to wrap around if the application was left running for a long period of time

 

To install Æ Monitor, copy the Æ Monitor folder to your Applications folder.

Æ Monitor captures Apple Event data by tracking changes to /var/tmp/console.log under Jaguar, or /Library/Logs/Console/(yourusername)/console.log under Panther. In order for Apple Event debugging information to appear in console.log, several environment variables must be set for each application to be monitored.

AE Monitor can momnitor applications in two ways.

  • One application at a time

    AE Monitor lets you monitor one application at a time by dragging an item into the AE Monitor window. AE Monitor will set up a shell with the appropriate environment variables and use it to launch the item. If you drop a document, the document will be launched just as though you double-clicked it in the Finder.

    Note that in order for this to work, the document's application can't be running when you attempt to monitor it; AE Monitor must launch it. However, if the application was originally launched by AE Monitor, monitoring will continue to operate.

  • Session-wide monitoring

    Æ Monitor accomplishes this by setting the Apple Event debugging environment variables for your entire login session. These variables are installed into the file ~/.MacOSX/environment.plist. Every process launched in your login session inherits the variables in this file and its Apple Events are reported to console.log.

    Use the preferences dialog to install and uninstall the session-wide environment variables. You must log out and log back in for the settings to take effect.

 

Monitor Window - Monitoring - Exporting Event Data and Code - Event Filters - General Preferences - Event Rules - New Event Preferences - Ticker Window - Code Generation Notes

The Monitor Window

The monitor window consists of three sections:

  • The toolbar features several buttons:
    • Start / Stop: Starts and stops Apple Event monitoring
    • Ticker: Hides the monitor window and shows the smaller ticker window
    • Preferences: Activates the Æ Monitor application and shows the Preferences dialog
    • Hide Details: Minimizes the details area of the window to the bottom of the screen. When that area is minimized, this button changes to "Show Details".

      •
  • The event list displays Apple Events that have occurred:
    • In this example, the Script Editor issued the 'aevt/odoc' Apple Event to the Finder (blue arrow). The Finder received the event (orange arrow) and replied to it (green arrow). Clicking on each event will show its details in the details area, below.
    • The pin on the right-hand side prevents the event from being deleted when event limiting is turned on in the preferences. Pinned events will not be deleted when you choose "Clear All Unpinned Events" from the event list contextual menu.
    • The white dot next to the pin indicates the background color of the event when the event is selected.
    • Control-click or right-click on events to display a contextual menu that allows you to copy event data and code, clear events, and perform other event-specific tasks.
  • The details area shows detailed information about the selected event:
    • The blue arrow indicates that this is an event that was sent from the Script Editor to the Finder. The listings below indicate the class and ID of the event, the return ID set by the originator of the event, the transaction ID, and whether or not a reply is required.
    • The right-hand area can show several different kinds of information about the selected event, including the raw console dat captured by AE Monitor and the different kinds of source code that can be generated. Right- or control-click in this area to display a contextual menu that you can use to change what data is displayed; this setting is also available in the preferences window.
    • The two dividers can be used to adjust the sizes of the details area and the event data area.

     

Monitoring

AE Monitor can monitor events in two ways:

  • One application at a time

    AE Monitor lets you monitor one application at a time by dragging an item into the AE Monitor window. AE Monitor will set up a shell with the appropriate environment variables and use it to launch the item. If you drop a document, the document will be launched just as though you double-clicked it in the Finder.

    Note that in order for this to work, the document's application can't be running when you attempt to monitor it; AE Monitor must launch it. However, if the application was originally launched by AE Monitor, monitoring will continue to operate.
  • Session-wide monitoring

    To enable session-wide monitoring, you must first install the environment variables as noted in the Installation section.

    To begin monitoring, press the Start button in the monitor window. Apple Events will begin to appear in the monitor window as they occur. If you have the Select New Events preference turned on, events will be selected as they appear and their details will be shown in the details area.

Events are grouped according to their 'return ID' attribute, so replies to events and event receipts will appear grouped with their source event.

 

Exporting Event Data and Source Code

Æ Monitor offers several ways to manipulate event listings:

  • Drag and drop

    AE Monitor provides you with four different ways to drag data to other applications, using the Shift and Option keys while dragging. In the preferences, you can specify which data format will be used for each combination of keys:


  • Contextual menu: Control-click or right-click on an event to display the event's contextual menu. Event data can be copied, or you can copy source code that replicates the event. You can also create filters for the processes referenced in the event or clear events from the contextual menu.

 

Event Filters

Æ Monitor features event filtering, allowing you to specify which events should be displayed. For example, you could ignore all events coming from the Dock, or only show replies from any application.

The Event Filtering preferences

The "All Events" filter is created automatically. As events occur and are captured, they must be approved by each filter, starting with the "All Events" filter and progressing down the list. Therefore, if an event is not approved by the "All Events" filter, it will be discarded and will not be considered by the other filters.

In the example shown above, events that the Script Editor receives will not be shown, but events sent to the Script Editor as well as their replies will be displayed.

You can create filters using several methods:

  • The New Filter button has options for creating blank filters; select an application from the hard drive to filter; or create a filter for a running application.
  • You can Control-click or right-click on an event in the monitor window and create a filter for the sender of recipient of an event.

 

General Preferences

The General preferences dialog

 

Several additional options are available in the General preferences tab:

  • Show only the newest n event groups: As events accumulate in the monitor window, the oldest n+1 event group will be removed from the list.
  • Start monitoring when application is launched: When you launch the application, monitoring will be turned on automatically.
  • Event details area data format: This is the format that will be shown in the monitor window's detail area. If a format has settings that you can adjust, the Settings button will become available. This setting is automatically updated if you choose a different data format from the details area contextual menu.
  • Plugins: Much of AE Monitor's functionality is implemented as "plugins", small pieces of code that are isolated from the main application. In the Plugins preferences, you can turn off plugins that you don't need, such as extra data formats.
  • Bug reporting: These settings are used to identify you when you send a bug report from the application menu.
  • Install and uninstall environment variables: Use these buttons to install and uninstall the environment variables necessary for session-wide monitoring.

 

Event Rules

AE Monitor features rules, similar to the rules present in many email applications. As rules occur and are logged, they are checked against the rules. If the conditions in the rule are met, the actions specified in the rule are executed. Rules are evaluated from the top of the list to the bottom of the list; you may move rules up and down within the list with the up and down buttons.

You can optionally have AE Monitor report action errors as they occur. If an error occurs, a dialog will appear in the monitor window; if the ticker window is showing, the text of the error message will apear in the ticker.

Each rule can have any number of conditions and any number of actions, and you can enable and disable rules. Disabled rules are ignored as events are logged.

 

New Event Preferences

The New Events preferences area allows you to specify the attributes of events as they are added to the monitor window. You can specify the background color of the event, and whether or not the event is selected, collapsed, or pinned. To do so, either select the appropriate checkboxes, or directly manipulate the sample event

 

The Ticker Window

The Ticker window

The ticker window allows you to minimize the monitor window while still receiving a notification when Apple Events occur. As events occur, they will appear on the right-hand side and scroll to the left.

Control-click or right-click on the ticker window to display a contextual menu with several options:

  • Start / Stop Monitoring
  • Show Monitor Window hides the ticker window and restores the monitor window.
  • Fast - Normal - Slow determines the scrolling speed of the ticker data
  • Hold freezes the ticker display until you Resume it. When the ticker display is on hold, events continue to accumulate and will be displayed when the display is resumed.
  • Preferences... activates the Æ Monitor application and displays the Preferences dialog.

You can also Command-drag the ticker data and scroll left and right to see data that is not displayed in the ticker window. As you drag, three vertical lines will indicate the start and the end of the available data.

The ticker window can be repositioned by dragging it to the desired location. It may be sized by placing the mouse cursor over the left and right-hand sides and dragging left and right to adjust the window's width.

Double-clicking the ticker window will hide it and restore the monitor window.

 

Code Generation Notes

  • REALbasic

    REALbasic code can be generated in two formats: native REALbasic code, or REALbasic code that uses a Declare and an AEGizmo string. The native code is much eaiser to read and customize, but cannot represent all Apple Events due to the limitations of REALbasic's Apple Event support. Some of the Apple Event structures that REALbasic cannot natively represent include certain comparisons ("every folder where the size is greater than 100") and 'null' parameters in lists

    The AEGizmo code format can replicate any Apple Event, but is hard to read and modify.
  • Receive and Reply events

    Æ Monitor allows you to create code for receive and reply events; however, it is not mean to be used as-is to reply to an event your application has received. If this feature is important to you, please file a feature request.
  • File references

    References to files and folders are received in AE Monitor as FSSpecs and are rendered in code as paths. This may not work if the file or folder does not exist when the code is generated.
  • Disclaimer

    Every efforts has been taken to ensure the accuracy and syntax of the code Æ Monitor generates. However, while it's not hard to automatically generate code, it's enormously difficult to generate perfect code because of the incredible variety of expressions and data found in Apple Events. Therefore, as is standard practice, the code Æ Monitor generates comes with no guarantee. Please review any external code you incorporate into your application.

Until you register, Æ Monitor will operate in unregistered mode, with a light red "Unregistered!" graphic over the monitor window. After a 30-day trial period, Æ Monitor will still run, but you will not be able to start monitoring.

Special thanks to all the beta testers, especially John, Dennis and Chris, who kept me very busy during the beta testing period.

Also thanks to Charles Yeomans for his MacIcon class.

E-mail me at the following addresses:

Feature requests: Visit this web page or use email: aemonitor-features[A/T]oxalyn[D/O/T]com

Bug reports: Visit this web page or use email: -bugs[A/T]oxalyn[D/O/T]com

Registration questions: -register[A/T]oxalyn[D/O/T]com

Anything else: -general[A/T]oxalyn[D/O/T]com

© Eric M. Williams • 2003-2006