Creating Sherlock Channels

Before you create your interface, think about how it will be used. This is all users will ever see of your hard work, so it's worth taking the time to get it right. Get a vision in your mind of what it will look like. Sketch it out. Don't overload it with unnecessary widgets, but don't make it just an Aqua-ized search interface either.

Open up our project in PB, then open the Channel folder and within that the Channel.nib folder. This is where the localized interfaces are stored. Double click en, which will open Interface Builder, the other edge of the Apple's main tools sword. This is where you'll create our channel's interface.

We will start by adding a row of buttons to the bottom edge of the window. Clicking on either the table or the "HTMLView" box you'll see eight dots surround the two widgets. These are handles, and you can resize that table and the HTMLView with these since they are connected in a split view. Drag the bottom center dot upwards, shrinking it until it has about double the margin it previously did from the bottom edge of the window. Under the Cocoa-Views palette (you may need to press command-/ do make it appear) click on the item with a button and a text box. Drag the button labeled (coincidentally) "Button" to the lower left corner of the window.

The Aqua HIG

As you drag the button, you'll see dashed blue lines appear. Those are there to help you create an interface that complies with the Aqua Human Interface Guidelines (HIG), which is a document that specifies how many pixels different widgets are to be from each other, how they're supposed to be used, and aligned.

Fortunately, Apple realized that developers wouldn't be able to remember the exact specifications so the blue lines are there to help you create your interface correctly. In the case of the button you just put on, align it with the left hand side of the split view and the bottom of the window.

To change the text on the button, double click it. Type "Enlarge Font" and press enter. One guideline to remember when creating the interface is that utility buttons, or buttons that aren't going to be used often should be small. To make this button small, press "command-shift-i". This bring up a window where you can change many different properties of the button, but for developing Sherlock channels, we'll only use a few of the panes. Press "command-1" to open the attributes pane and check the "Small" check box in the "Options" section.

Now you'll need to re-align the button with the bottom left of the window again. You can now load your channel in Sherlock (if you already have Sherlock open you'll need to reload the channel by pressing command-r) and see the new button! Now try the steps above to create a similar button, but this time in the lower right corner with the text "Get more Sherlock Channels".

Springs

Now reload the channel and try resizing the window. See the problem? The new button doesn't stay in the corner like you would expect it to. The problem here is that we didn't set the springs. Springs are how your buttons are "pressed" against a particular side of the window as it is resized. The other button stayed in the same place because the window isn't resized from the left side.

To set spring open the info window for the button and press command-3 , which opens the Size pane. In the Autosizing box you can see a faint square with four lines coming out of it and four lines inside of it. The box represents the widget and the eight lines are how you determine the way the object is resized. To keep the button in the lower right corner, click the top and left outside lines which should change them into springs. The spring from the top is pushing the button to the bottom of the window and the spring on the left is pushing the button to the right of the window. Now add springs to the first button to keep it in the lower left corner.

Create another small button just to the left of the "Get more Sherlock Channels" button called "About". Now add one last button, "Shrink Font" to the right of the Enlarge Font button. Be sure to set the springs properly!

The last thing to do to make this part on the interface look right is to adjust the SplitView to be the correct distance away from the buttons. Click on the SplitView and drag the bottom center dot toward the buttons until the blue dashed lines appear.

After you save your changes, you can now look at your channel in Sherlock and see the new buttons. As you develop your own channels remember: if your widget is showing up in IB but not in Sherlock, you probably didn't set the springs.

Adding Other Widgets

Now to adjust the top part of the interface. First, we'll only need one column in our table, not two, so we'll delete one. Click the table once (which selects the NSSplitView), then double click the table (which selects the NSScrollView which contains the NSTableView), then double click on the table again, which finally selects the table itself.

In the table's attributes change "# Colms:" to 1 and press enter. Close the info window and you'll see one column with a title in it, but it still appears like there's two columns. Move the cursor over the column divider and drag it all the way to the right of the table (don't worry if you drag it too far and the other end of the table looks like it disappearing).

We'll also want to get rid of the text above the search box, since it's not what the box will be used for. If you'd still like to provide help or instructions, there is a better way. Click the search box, open up it's info, and click command-4 to open up the Help pane. Here you can type something like "Enter the key words you want to search for in this box".

But now that we've removed the help line, we'll need to re-adjust the interface so that there isn't a gap along the top of the interface. Under the size pane of the text box, enter 10 in the y text box (make sure that Top/Left is selected in the list above the box). Drag the rest of the widgets in the top row to align with the button and drag the split view to be the correct distance from it.

In my opinion, the rounded text box looks better than the square one so open the text box's attributes and check Rounded in the Options box. Another change you'll want to make is to allow users to press the Return key from the search box to start a search. Open up the attributes for the search button and in the pop-up menu to the right of Equiv: choose Return. We'll also want to add a button next to Search for people to get the latest hints after they've done a search (remember what I said earlier about fully thinking your interface through). Drop a regular size button next to Search and title it "Newest Hints".

Setting the Paths

Now we will need to set paths for each new widget. Open a widgets info window and then the Sherlock pane (command-7). You set a path be entering a name in the Name text box, and the complete path will be shown in the "Data Store Path:" box below. Set the name for "Get more Sherlock Channels" to "GetMore", the "Newest Hints" button to "NewestHints", and the "About" button to "about". You might be wondering why you don't need to set names for the two font buttons, but we'll cover that later in this tutorial.

Setting the Window Size

Sherlock depends on the code to tell it how small to allow the user to make the interface. We want to make sure the minimum size specified in our code matches the size of the window in IB. Open the window's size pane in it's info. Here you see it's width (w) and it's height (h). Copy those two values down and in PB open up Channel.xml in the Channel folder. Near the top you'll see the line:

Change the width and height values to whatever you copied out of IB. You're now done with the interface and are ready to move on to coding. Quit IB (saving your changes of course) and get ready to dig into PB.

Next Time

In the second part of this tutorial, which will publish on Tuesday, April 1, you'll get into the code. Just as you spent time thinking about your interface before you made it, you should also spend time thinking about your code--what you want it to do and how you want it to react to the UI. There is a tremendous difference between code that just works, and code that is fun to work on.

Harold Martin is a freelance software developer and author. Visit him at his blog.

If you have any additional tips for effectively building Sherlock channels, please chime in.
You must be logged in to the O'Reilly Network to post a talkback.

Showing messages 1 through 4 of 4.

Too bad about the speed
2003-03-29 10:56:40 anonymous2 [Reply | View]

Too bad there is nothing that can be done about the speed of Sherlock. Oh yeah, I just bought Watson and that made so much faster.

Creating Sherlock Channels article
2003-03-28 21:23:21 billbarstad [Reply | View]

I'm totally unfamiliar with Apple developer software. To be sure, I have it all on disk. As a hobbiest, I'd like to get to know it. I was hoping this article would be of help. I got through moving environment.plist to .MacOSX, but the next step lost me completely. It wasn't easy dealing with the Propery List Editor either, as your instructions were incomplete and therefore confusing. Perhaps it's just that articles at MacDevCenter.com aren't aimed at beginners. I wish they were!

Bill Barstad

Creating Sherlock Channels article
2003-03-30 23:25:29 jeblucas [Reply | View]

I actually found the instructions rather easy to follow. I'm guessing you found Property List Editor confusing because after a simple Splat-N for the new document, you have to click New Root, then click the dropdown widget next to Root to get the New Child button to appear and so forth. Given the lack of options--this would seem to be fairly intuitive next step--I don't think it was necessary to mention it. Entering the "1" value as a string, also largely intuitive, though the "Number" option might throw one off there. The next step, if I follow, is simply to go to your hard drive, open the Developer folder, then the Applications folder, then Project Builder--it's in the same folder as the Property List Editor if that Finder Window is still available.

The rest of the instructions are equally as good, with a fair balance between, do this, do that, and work it on your own. I think the author is trying to present Creating a Sherlock Channel, not Creating This Specific Sherlock Channel Every Time. If you mess with the widgets enough, you'll get it worked out.

Creating Sherlock Channels article
2003-03-29 13:36:47 Harold Martin | [Reply | View]

Are you saying you don't know where the Developer Tools are located on your hard drive? Or do you need aditional instructions on getting started? If you would like help (which I would like to offer you) please be more specific on the details of your problems.
Thanks!
Harold Martin

Creating the Interface (and Thinking It Through)