This is the Tapir Tutorial. Reading this document should help you understand what Tapir is all about, and how to utilize its features to create menu applications.
When you launch Tapir, you should see a window that looks something like this:
It is perhaps easiest for me to simply explain what each control does, in turn.
This field contains what will be the name of your menu application. This name will appear in the "Quit" menu of your app, i.e. "Quit MyApp", and will default as the name of your application package.
The image well allows you to change the default application icon. This icon will appear on your
.app application package in the Finder. To change your application icon, simply drag an image file to the well or select the "Change App Icon" menu item.
The command field is perhaps the most important control in the Tapir window. Here you must type in the command whose output you wish your menu to receive. In the Tapir window in the image above, you can see the command
/bin/echo Hello, World. This particular command will give the output
No shell expansion is performed on the command string you supply, so you'll have to produce an absolute path to the program you wish to execute. As you can see, the full path to
echo is supplied. Similarly, you will have to provide a full path to the application you want to run. You can supply as many arguments to the program as you like e.g.
You can set the output of your command to go either into the contents of the menu ("In Menu" option) or make your command run periodically, setting the first line of output as the title of your menu ("In Title" option). For now, we'll just be looking at output that goes into the menu content. For information about the "In Title" option, scroll to the relevant section below.
This field allows you to set the number of seconds before your command times out. This can be important if you're calling a program that, say, contacts an internet server, but your connection is down. Without a timeout value, the menu would hang forever, waiting for a response. Don't set this value too low, though, as it may interfere with perfectly normal functionality.
Tapir supports bundling scripts with your app. These scripts can be executed by your command, thus making it possibly to distribute Tapir Menu Apps that depend on custom scripts or programs without requiring the user to install command line software. To execute a bundled script called
hello.sh, you would use the following command:
Bundled scripts are copied into the Resources directory of the menu application. Since the user-specified command is issued from within that directory, the command listed above will execute the script.
Your menu needs a title in order to be visible in the menu bar once your menu application is launched. You can select your title to be a text string, an icon, or a combination of the two. It is not recommended that you supply a very long text string, since this may cause your menu to be obscured by the menu bar of running applications.
You can select an image to use as icon by pressing the "Select" button. Ideally, your image should not be too wide, and preferably no higher than 22 pixels.
Menu Text Aesthetics
This should be fairly self-explanatory. You can configure your menu font, size and colour according to your needs. For specially arranged text output, it is often best to use a monospace font in order to preserve formatting.
Under this item, you can select what action to take when a line of your command's output is selected in the menu. While there are a number of simple presets that Tapir provides (e.g. "Copy to clipboard", "Open URL" etc.), the true power of this functionality is unleashed when you choose "Feed to Program", and type a command name into the text field which appears. The command in question (whether it be a script of your own, or a command line tool) receives the menu item's text as first argument, thus making the action arbitrarily extensible and definable by anyone with a little knowledge of scripting.
This button restores the values in all fields and controls to their default.
This handy little button allows you to preview your menu in action from within Tapir before creating the menu application.
This button sets in motion the process of creating a menu application according to the settings you specify. You are prompted for a location wherein to create the app, and it will be summarily done. After this, you should have a fully functioning Tapir Menu Application in the location you chose.
Tapir Menu Application
Now that we're clear on what all the different controls do, we can try creating a Tapir Menu Application. Go through the following steps:
- Set the "App Name" field to "DiskUsage"
- Set the "Command" field to "/bin/df -h"
- Set "Title of Type" to "Text only"
- Set the "Title String" field to "Disks"
- Change the menu font to "Courier 13" and set the color to red
- Make sure that the menu select action is set to "Do Nothing"
- Press the "Create" button to create your application
After this, you should have an application called DiskUsage in the location you specified. If you open the application, it will not appear in the Dock. However, a menu item with the title "Disks" should appear in the menu bar, next to the Apple-supplied (or other third party) menu extras. Assuming that you faithfully followed the instructions above, clicking "Disks" should produce the following menu:
At this stage, you have a fully operational Tapir Menu Application. This application is completely stand-alone and does not require Tapir to be present on the system of the person running it.
Tapir Title Application
If you choose "In Title" output, the Tapir application you create will behave somewhat differently. Instead of running a command whenever the menu is clicked, the command will be run periodically, and its first line of text output will be set as the title of the menu. Let's take a look at how such an application is created.
When your output selection changes, the window will shrink and reveal new options that are only appropriate for this configuration, namely "Exec Interval". This allows you to specify the interval between updates to the menu title.
Now, let us create a new Tapir Menu Application which receives output in its title. We shall call this application SwapMenu, and we want it to display the current disk space used by swap files on the startup volume. Our configuration would look something like this:
As you can see, the execution interval is set to 60 seconds. Updating this information once a minute should be sufficient. Our command, "
/usr/bin/du -hs /var/vm", will print out the total size of the folder
/var/vm (which contains Mac OS X memory swap files) in human-readable format. A timeout value of 5 seconds should be just fine -- this isn't a very processor intensive command.
Now we can just press the "Create" button, specify a location for our application and try opening it. If all went well, we should have a fully-functioning Tapir Menu Application which displays swap file usage, updating the value every 60 seconds.