Temperature Converter Tutorial
(Level: advanced)
Note that screenshots are from version 1.8.
Creating Cocoa nibs is recommended in OMC 2.0

In this tutorial we will create a simple droplet application with one dialog. The dialog will have two edit fields: one for Fahrenheit value entered by user and second for displaying Celsius value calculated by our code. The dialog will also have a "Convert" button which will be triggering the calculation. This button will not be closing the dialog, we will use standard close box in window's title bar instead.
First we need to decide what scripting language we will use to convert Fahrenheit to Celsius.  It can be done in shell script, Perl, PHP, AppleScript, etc.
In this example we will use regular bash shell (default in Mac OS 10.4)
with little help from 'bc' calculator tool. Plain shell does not allow floating point calculations so we will delegate it to 'bc'. You can type the following in Terminal:


fahrenheit_value=73
celsius_value=`echo "scale=2; ($fahrenheit_value - 32.0) * 5.0 / 9.0" | bc`
echo $celsius_value

We set the special bc variable 'scale' to 2 which means that the result will use 2 decimal places in floating point precision. We enter the formula and pipe the whole text to 'bc' because it usually operates on files and does not take the text parameter directly.
When we have the basic conversion script figured out we can start designing the dialog. We will create a nib file with Interface Builder (developer tools need to be installed of course).

Start Interface Builder and create a new Carbon nib with Window or Dialog.
Save it on your desktop as "converter.nib".

carbon_nib


If the inspector floating window is not visible go to Tools menu and select "Show Inspector". Same for control palettes.



Click on the new dialog window and edit its properties in the inspector.
Important thing is to check the "Compositing" mode for this window because OMC relies on it. We want to have a "close" button for this window. We don't allow to resize it. In this example we will make it a utility window. Utility window is similar to floating window but it does not hide when the application goes to background. It always stays on top instead.

 

Switch to control palette and see what buttons you can add.
 



Add button, by dragging from palette to your new dialog window.
Double click the button and name it "Convert".



Change button attributes to make it "default"
Change control properties to assign OMC! signature and control ID. This step is optional for this button because we will not be directly accessing this button in our command.
Add command ID 'Conv'. This ID will be broadcasted when the button is pressed and OMC will try to find a command description with this ID end execute it.

 

Switch to text controls in palette, add static text and edit fields by dragging them to your dialog.



When all items are added and named, the dialog should look like this:




The final step is to change properties for both edit fields
Signature should be 'OMC!' as for all controls designed for OnMyCommand, for control IDs let's use the next available numbers: 2 and 3.

 


After all those steps, when you click on the dialog window you should see something like this in the inspector:




Now we can save the nib file and exit Interface Builder.
The next step is to create a command description which will use the nib dialog and do the calculation. The easiest way to edit command is by using OMCEdit.
We start with the first command where we set  nib parameters. Nib filename (without ".nib" extension) must much the name of the file we created in Interface Builder. Window name must also match. Please note that it is not the window title that we assigned to our dialog. Instead, "Dialog" is the name identifying the window in nib resource.
Make sure the command has 'top!' id. This is the command that will be executed on droplet startup. You may notice that the command is empty — this is on purpose. In typical use you set up a dialog to ask user for some input and then you get values from dialog, close it and do something using those values when the dialog is okayed. In such case you would write a script here. But our Temperature Converter is very simple, it does nothing when the dialog is closed. Our dialog only shows converted value and it is the whole meaning of its existence. So where the actual conversion happens?




The actual conversion happens in subcommand. If you are familiar with programming you may think of it as an event handler.
We need to create a subcommand with Command ID='Conv' to handle the notification sent from "Convert" button.
Now let's slightly modify the original script to read value from first edit field and set the result in the second one.
Reading values from nib dialog controls is easy. You enter special object __NIB_DIALOG_CONTROL_XXX_VALUE__ where XXX is ID assigned to control in nib dialog. In our case, control with ID=2 is the Fahrenheit edit field.
Setting control value in nib dialog is slightly more complicated. We don't have a direct access to dialog controls in shell command and we have to use a helper application "omc_dialog_control" located in "Contents/MacOS/" of our droplet.
It should be called as follows:

__MY_BUNDLE_PATH__/Contents/MacOS/omc_dialog_control __NIB_DLG_GUID__ 3 $celsius_value

__NIB_DLG_GUID__ is a special object set by OMC to identify current dialog —  OMC design allows more than one dialog at the same time.




Please note that our subcommand does not have any nib settings entered. We don't want a second dialog invoked when executing this command. See the picture below.




Now you should select both "Converter" command items and export them to separate plist file. Go to "File" -> "Export Selected Commands". Save as "Command.plist" on your desktop. Now drag the Command.plist onto OMCEdit.app icon.
Choose icon from the dialog and press "Build" button. Save on desktop as "Temperature Converter".




Find the "Temperature Converter.app" on desktop and ctrl-click on it. Choose "Show Package Content".




The final step is to copy the converter.nib we created in Interface builder to the droplet resource folder. It should go into "Contents/Resources/English.lproj". Now you can close the window.




Double click "Temperature Converter.app" to test if it works. You should see the dialog you created and pressing "Convert" button should calculate the Celsius value.  The window should float on top even if the droplet itself is in the background.
The complete droplet is available in "OnMyCommand/Droplets/Example Droplets".