Ladies and gentlemen, please welcome User Experience Technology Manager, John Galenzi. Well, good afternoon. Welcome to session 142. This is one of many of the sessions here at the conference on the Aqua user experience in Mac OS X. And this session really is, as I said on Monday in the Aqua overview session, is really the mirror session of that one. And this one presents the material from the Aqua overview session really from an API point of view, so from the programmer's point of view.

Speaking through all of the material that was presented in the Aqua overview session, item by item, and telling you how to implement these things within your apps as a developer. So to walk you through this content, I'd like to bring on stage Guy Fullerton, a member of the high-level toolbox engineering team at Apple.

So Aqua is the next generation user experience for Mac OS. But it's more than just a whole bunch of pretty pictures on the screen. It's behaviors, it's functionality, and it's your entire experience when using Mac OS X. And the key for you as developers is that Aqua is not complete until your applications take advantage of it, until we have lots of applications on the system that take advantage of it.

So I'm going to show you the steps that are required for your application to aquify. And it's really not a very difficult process. A lot of the functionality, the toolbox, and lower-level system services will do for you automatically. I'll also show you how to avoid certain problem areas when you're doing your code and aquifying your application. And lastly, I hope to give you some kind of level of insight into exactly why Aqua is the way it is, so that when your application needs to do some sort of custom user interface element, you can better match the rest of the Aqua experience.

So the most striking thing about Aqua when you first see it is probably the windows. They're obviously drastically different from Mac OS 9 in appearance. And there's several cool technology features that we've built into Mac OS X that make using Windows much more of a pleasure. One thing about Windows that may not necessarily be obvious the first time you start using Mac OS X is the fact that we have a brand new layering model. On Mac OS 9, when you select an application, either by clicking on one of its windows or choosing it from the application menu or something like that, all of that application's windows come to the foreground.

On Mac OS X, we don't have that behavior. When you click on an application's window, just that one window comes to the foreground. This is beneficial for a couple reasons. The main reason it's beneficial in any case is that users have a very document-centric way of working, and this facilitates it very easily.

So there's a couple things as application developers you need to be aware of with respect to this functionality. The first is that because just one of your windows can come to the front most, And that does bring your application to the foreground, but just because your application is at the foreground, you can't assume that all your windows are visible.

If you have some sort of status window, you might want to bring that forward in addition to just the one window the user clicked on. Similarly, the Toolbox will automatically bring all of your application's floating windows to the foreground when any one of your windows comes to the front.

And to make it easier on your lives, your window list has not changed at all in this model. You will only see your windows in the window list and you won't have to watch out for any other applications' windows. And if your user does want to bring all of your app's windows to the foreground, there's a couple mechanisms to do that. I'll talk about one a little bit later on, but they can always click on your applications icon on the Doc to bring everything forward at once.

So Mac OS X automatically double buffers your window content for you. This has several cool advantages. The first is a user advantage, and that is that drawing appears very snappy. If you create a Mac OS 9 window, just a normal Mac OS 9 window, and you don't go through any effort of double buffering it, and you make individual quick draw calls or appearance primitive calls or other calls that draw, you'll see each individual draw operation take place one after the other, and it looks kind of clunky.

Well, on Mac OS X we automatically redirect the drawing into the off-screen buffer for that window, or what you can think of as an off-screen buffer, and then later that gets blit to the screen all in one fell swoop. It has a very crisp, snappy appearance to it. Additionally, the fact that we buffer windows lets us take advantage of Quartz in really cool ways to do shadow compositing or translucency effects and things like that.

So, like I mentioned, when you're drawing with Quick Draw on Mac OS 9, individual graphics operations take place one at a time. And on 10, they still take place one at a time, but they write to some off-screen buffer. Typically, your application does not need to manage that buffer and the timing that's used to transfer it to the screen. The Toolbox does that for you in probably 99% of the cases.

When you do some drawing and then you re-enter the event loop, we will automatically flush all the windows that need to be flushed. If you do have some cases in your application where sort of intermediate frames of the drawing might make sense to display or if you're doing some kind of animation without calling into the event loop, you can always manually flush by using the QD Flush Port Buffer API.

So on Mac OS X, we automatically turn on buffering for you. And in this case, we've got an API called QDIsPortBuffered, and this tells you when a given port is buffered. I'll get to something else in a second. So essentially what this means is now that we're automatically doing an off-screen buffer for you, if your application on Mac OS 9 was doing its own off-screening or own double buffering through GWorlds, you don't need to execute that code on Mac OS X. So you want to use the QDsportBuffered API when it returns true to conditionally turn off your own GWorld support for your Windows.

Additionally, each buffer for a window has its own device depth, and the Windows Server in Quartz will automatically do the dithering if it happens to be rendered to a device that has a lower bit depth than the Quartz buffer. So you don't even need to bother doing device loop when you're running on Mac OS X.

On Mac OS 9, of course, we don't do any automatic buffering. So it might behoove you to leave your GWorld drawing code in there and conditionalize it just to run on Mac OS 9 using the QD isPortBuffered API. You'll also want a device loop on Mac OS 9 just like you always have. It'll make sure you draw properly across all devices. I should make another note that the QD flush port buffer API, even though it does nothing on Mac OS 9, is still perfectly safe to call.

So one of the ways we take advantage of Quartz is through window shadowing. Window shadowing is important for a number of reasons, one of which is the fact that unlike Mac OS 9 Platinum windows, an Aqua window does not have a thick border around the edge, and the window shadow is one of the ways you can help differentiate the edges of your windows. This also lets us do cool usability features, like the fact that the frontmost window actually has a darker, deeper shadow than the rest of the windows in your application to make it stand out a little bit better.

But not all windows necessarily need shadows. You might have a case in your application where you're displaying a window. For instance, if you've got a scroll bar and you pop up a little window that displays the page number that the user will have scrolled to when they log into the scroll bar, it may not make sense to display a shadow on that window. So you can turn off the shadow in two ways. The first way is by calling create new window to build that window. If you pass in the no shadow attribute, of course we're going to create a window that doesn't have a shadow.

The second way does not work yet on DP4, but by the time we ship the final version of Mac OS X, it will work. We have a change window attributes API that's been around since I think Mac OS 8.5 that allows you to dynamically turn on and off certain window features, and the shadowing will be one such feature.

Now the fact that we have your Windows buffer means we can do other cool things like drag the window around live. Of course, this will only work if you call the standard Toolbox Drag Window API. A lot of you have custom dragging code for your windows, typically implemented with drag ray region or direct drawing to the screen and doing your own pattern XORing and stuff like that. That won't work on X. First off, because drag ray region will not have the behavior you expect.

We'll go into a little bit more detail on that on the Carbon enhancement sessions. Drawing to the screen just really doesn't work on Mac OS X. In DP4, there are ways to get it to kind of work, but it's not going to draw to the buffer, so it's just not going to work out, and I'd say avoid it. If you do need some custom dragging behavior, you can always take advantage of Carbon events and hook into the drag window functionality to do certain custom dragging.

So of course another real cool feature of Mac OS X is the Dock. And as you've seen, Windows can minimize down to the Dock. The Toolbox tries to do as much of this work for you as possible. In fact, it's basically free for your application. Any document window, which is one that has the collapsible bit, the collapsible attribute turned on for it, will automatically minimize down to the Dock when you click the Collapse box. Now in Mac OS 8, I believe, we introduced the Collapse Window suite of APIs, which worked with Mac OS 8's window shading behavior.

The Collapse Window API allowed you to window shade and unwindow shade windows. So in Mac OS X, we're reusing these APIs to do the minimization process. Additionally, calling Select Window on a window that happens to be minimized will un-minimize it from the Dock and bring it to the front in one operation.

So when a window is minimized, there's a couple of things you need to be aware of. The first is that the window is still visible. This has several key advantages. If a window is minimized in the dock, say a progress window, you can continually update the progress window.

And if the user clicks on the dock to unminimize the window, it'll unminimize immediately in its currently drawn state, which is good. Also, it's still in your window list, so you need to be aware of that. We have an isWindowCollapsed API, which has, again, been around since Mac OS 8. If it's true, your window is in a minimized state.

There might be certain functionality in your application that you'll want to turn off for certain minimized windows. For instance, if you have a Windows menu with an arrange or tiling item, you probably don't want to arrange or tile your minimized windows. It'll look kind of odd to the user if there's a hole in the arranging that you did.

The Dock doesn't just show minimized windows in it. It also shows application icons or possibly documents you've added to it. And of course you're going to want a good icon for your application to show in the Dock when it's running. Now the Dock uses 128-bit by 128-bit icons, which are obviously much bigger than the 32 by 32 icons. If you don't provide a 128 by 128 icon, we'll take your 32 by 32 icon and scale it up. And as you've seen in some of the demos, it can look kind of clunky and it really doesn't give your app a good feel to it.

So we're going to talk more about this in two different sessions. There's an application packaging session and an icon services session. The icon services session will tell you how to build up the icon ref, the 128 by 128 icon ref. And the application packaging session will show you how to stick that into your application's bundle.

So, obviously the menus in Aqua went through a visual transformation, but there's a more subtle transformation that we did that really increases the usability of Aqua, and that is a little bit of menu bar reorganization. Under Mac OS 9, Mac OS 9 obviously has a very long history, and so commands kept getting added to it and added to it. And after time, it became kind of clunky, and things aren't necessarily arranged in the best possible way.

So in Aqua, we tried to rectify that. The leftmost menu in the menu bar is the application menu. This is the menu in which you put all of the commands that only pertain to your application. As you can see, Quit and About, things like preferences and the Hide and Show items.

Building an application menu is something you'll all recognize as familiar. From a resource standpoint, it's essentially just an Apple menu. Create a normal Apple menu which has the Apple character as its title. Put your About item in it just like you always have. Put a separator in it just like you always have. On Mac OS 9, when you're running on CarbonLib, we detect the Apple menu.

We automatically populate it with Apple menu items, and we even handle all the selections for you. When you run on Mac OS X, we do a couple different things. First off, we populate it with all the standard application menu items: Quit, Hide, Show, Preferences, and all those. Secondly, we change the name of the application menu to be that of your application.

Now, a lot of today's applications have very long names. You know, you've got a company name, the actual app name, typically a version number on it. That whole string is not appropriate to throw into the application menu. But by default, the toolbox will. So, we've come up with a scenario so that you can actually create a short version of your application's name specifically for stuffing into the application menu title.

And this is by one item in your application bundle's info P list. We'll talk more about that at the application packaging session as well. Now, if you don't provide one of these short names, we'll take your application's long name and truncate it, probably some place in the middle where it doesn't necessarily make sense. So, you really need to provide a short application name if your application name is at all non-trivial.

So, like I mentioned on CarbonLib, we handle most application menu selections for you automatically. But when your app needs to do a few other things, you need to handle your About item the way you always have, but then again, you already have code to do that, so that's no change.

We added a Quit and Preferences item to it, but it's your responsibility to handle those items. When a user chooses the Quit item from the application menu, we'll send you a standard Quit application Apple event. Handle that the way you always would, you know, bring up your Save/Don't Save dialogs and shut down your application as appropriate.

When they choose the Preferences item, we send you a brand new Apple event called Show Preferences. When you receive this Apple event, you'll want to obviously display your preferences. Everything else in the application menu is handled automatically right now. We deal with the hide and show items automatically. The services isn't quite wired up yet, and we'll have more details on that later.

Now a lot of applications have either complex preferences, or they have plugins which need preferences, or they might even have just multiple preferences items for historical sake. We made the Preferences menu customizable so that you could add multiple Preferences items or even delete it if you need to. The Preferences item in the Application menu has a command ID associated with it. It's all lowercase, p-r-e-f, just like you would expect.

and you can find the position of that item in the Preferences menu by using a new Menu Manager API. In fact, we have a whole suite of new Menu Manager APIs that are designed to let you deal with menu commands, menu items, sorry, on a command basis. You can find them, hide them, show them, things of that nature. So once you've found the Preferences item, you might want to change its name, you might want to hide it, you might want to add other items, but you can customize it however you need to.

The next menu over in the menu bar is the File menu. This hasn't changed a whole lot, but it's important to understand what it's for now. It's the place that you put all of your document-specific commands. There should be nothing that pertains only to the application here, or stuff that contains the document content. So as you can see, the File menu no longer has a "quit" command.

Now the last menu we'd like everyone to adopt is a window menu. This window menu becomes particularly important now that we have a different layering model. If your windows are intermingled with another application's windows, it's important to offer an easy way to the user to get at the other windows in your application. And of course if you add this, it'll show up in your CarbonLib versions as well, and I'm sure your users will find it useful there as well.

Unfortunately, we don't have an automatic window menu support, but we're looking at what it'll take to do that. So for the time being, if your application does not already have a window menu, you just need to add a few standard commands to it and then add one item for every window in your application. If the user chooses one of the items that pertains to one of your windows, just call Select Window to bring it forward. One of the standard commands is Minimize Command, and when the user chooses Minimize, you should collapse the frontmost window.

The other standard command is Bring All to Front. If they choose that, you want to bring all of your application windows to front, obviously, and you do that by calling Set Front Process on your application's process serial number. This is also a really good place to put any tiling or arranging functionality if you offer that in your application.

So, all right, you've just laid out your menus for Aqua. Well, what should they look like when they're running on Mac OS 9? Well, the answer is they should look like Mac OS 9 menus. The file menu should still contain the quick command and your preferences item should be wherever you normally put it in your Mac OS 9 product.

To facilitate this, we've added a bit to the menu manager's gestalt. That's the Aqua layout bit. If you see this bit turned on, you want to change the way your menus are laid out. Of course, there's a number of different ways you can do that. You might have a set of different mbar and menu resources in your app and change which one you load based on whether or not the bit is set.

Alternatively, you can go ahead and leave the quick command in your file menu and remove it when you're running under Aqua, or maybe dynamically add it if you're running on Mac OS 9, or do whatever you need to do. You also conditionally want to move your preferences item around. So before I go any further, I want to give you a demo that's not exactly related to Aqua, but I've got some ulterior motives, so bear with me. So if I can get the demo machine.

I've just got a very simple application here, and I don't know if it's shown up very well in some of the other demos, but Aqua menus are transparent. You might have seen that before. But we've been working on the menu manager a little bit. Besides just adding some APIs to deal with the command IDs, we've also added dynamic menu support. So while I've got this menu pulled down, I can change the modifier keys that I hold down, and it changes the items that are displayed.

I'd like to go back to slides. So between those two facts and the fact that in Mac OS 8 with the Appearance Manager, we also introduced a whole bunch of new menu item glyphs and the full keyboard command suite-- you can assign control, option, shift, and those things to your menu command modifiers.

Between all those features, there's basically no reason not to adopt the system menu def for your text-based menus. That, in fact, is the only way to get translucency for your menus. Right now, translucency is not supported in custom MDEFs. And of course, when you adopt the standard MDEF, you're going to have maximum future compatibility as well.

So in my opinion, the absolute best feature of Aqua is Sheets. This is the way modality always should have been. Sheets are a way to associate an individual dialog or alert directly to the document which it applies. And this is probably the individual hardest thing to implement for Aqua, but even as such, it's not very hard.

The Toolbox tries to take care of as much work for you as it possibly can. We run the Genie effect, we deal with the document modality, and we also deal with the window grouping. When a sheet's pulled down on a window, you can actually click the document window and move both the window and the sheet around.

So the work you have to do, like I said, is very simple and it's four basic steps. The steps you're pretty much used to for all your normal Windows with a slight twist. To create a sheet, use the Create New Window API, and just tell it, "Hey, it's a sheet class window." All right, that gives you the sheet.

But before you can actually display it, there's one thing you need to do. In the Carbon event session, we mentioned how a lot of our new functionality was only going to be accessible via Carbon events, and this is one of those pieces of new functionality. When a Genie Effect is about to run, we need to show the window and have the windows image ready immediately so we can run the Genie Effect with the real bits. In order to do that, we need your application to respond to the K event window draw contents apple event. Sorry, Carbon event.

You simply do this by installing the event handler. And when you receive the event, do your normal window drawing. You can call draw controls or draw whatever custom content you need to. and so we'll send you this event, we'll have your bits already ready, and we will run the Genie effect and spin your window out.

So to actually run the Genie effect and show the window, you call Show Sheet Window. This window is just like Show Window except it takes an extra parameter, and that parameter is the document window to which it applies. This API does a couple things. First, it associates the sheet with its document. It'll run the Genie effect, and then it sets up the system to deal with the proper modality of that sheet to just its document.

The other important thing to note is this API returns immediately, just like Show Window. It doesn't put you into some sort of funky modal state and we only exit after the user's done with the Genie. That doesn't happen. Show Window returns immediately, and your application must continue with its normal event processing.

And it's just that: normal event processing. You'll receive events for the sheet just like you would for any other window, and you can handle them just like for any other window. And if you want to take advantage of Carbon events to make your life a little bit easier, you can do that too.

So the user interacts with your sheet for a while and ultimately they're going to click a button or do something in the sheet that means dismiss it. And to get rid of the sheet and thereby animate the Genie effect, you call Hide Sheet Window. This also unbinds the sheet from its document. And like any other window, you just dispose it when you're finished with it. Alternatively, you could keep it around for a later use of Show Sheet Window if you want.

So the vast majority of Sheet use is usually very simple. You'll typically want to do save dialogs, print dialogs, or custom alerts and things of that nature. And we've offered a standard alert API for a little while now, and we made an equivalent of that using Sheets, and it's called Create Standard Sheet. So Create Standard Sheet has mostly the same parameters as Standard Alert. You can customize the message text, the explanation text, you can customize the buttons a little bit.

The one difference is that Create Standard Sheet takes an Event Target Ref. An Event Target Ref is one of the Carbon Event objects to which events can be sent. This target is particularly important because when the sheet is ultimately dismissed, we are going to send the event telling you what the user clicked directly to that event target.

So you create your Sheet window, you call Show Sheet window, and from that point on, it's handled automatically. Create Standard Sheet will automatically install enough Carbon Event Handlers onto the Sheet window such that all of the event processing for that Sheet is handled for you. You won't receive any events for that Sheet via Waitnext Event.

So when the user manipulates the sheet and finally clicks one of the buttons, the Create Standard Sheet API set up some stuff so that we will call Hide Sheet Window for you automatically. And then we send a particular Carbon event to the event target you provided. It'll be OK, Cancel, or Other, depending on whatever button the user clicked.

So the navigation services and printing teams have come up with a new suite of APIs to let you take advantage of their dialog services in such a way that they use Sheets. You should definitely check out the sessions that they discuss this at to find out all the details there. But in general, they try to make your lives as easy as possible and do as much of the work for you as possible.

So one of the other major changes with Aqua is the system font. We're now drawing with Lucida. And in fact, it's even a little bit bigger than you might be expecting. On Mac OS 9, the system font was charcoal. Before that, it was Chicago. But in both cases, it was 12-point.

The system font in Lucida is 13-point. The small system font is 11-point. And additionally, there's a few cases where we render the font with special effects in certain cases. The push button, for example, has a slight shadow, as does the window title. And in fact, the window title is rendered in 14-point. So there's a few nuances there.

So despite the fact that Lucida has a larger point size, it still has the overall same metrics as Charcoal or Chicago. I think Charcoal and Chicago have a 16-point overall line height. Lucida is roughly equivalent, definitely does not go over 16. Similarly, the small system font has an overall line height of 13 points. One important fact to note is that Lucida is, on average, a little bit larger, a little bit longer than Charcoal or Chicago, so you might need to take care there.

Of course, your applications are going to want to use AquaText wherever they can. If you use the standard system controls, windows, and menus, we're going to take care of all that for you automatically. But I know your applications do a lot of custom drawing. We've implemented a suite of Appearance Manager Aqua-savvy Theme Text Drawing APIs.

They actually build upon some earlier Appearance Manager technology using the Theme Font IDs. This was a set of meta fonts you could request, like "Just let me use the system font," or "Just let me use the small system font," or "The small bold system font." So this suite of APIs lets you draw or measure or truncate any number of these meta fonts in an Aqua-savvy way.

And in order to make your lives easier, we've tried to make these APIs relatively equal to the Quick Draw Text APIs that you've grown to know and love. We have an equivalent to the TE Text Box API, we have an equivalent to String Width, we have an equivalent to Trunk String, and those things.

So Aqua obviously changed all the widgets and all the controls, so they have a brand new look. In addition, we've added a few new controls and added some features to some of the older ones. So I know you saw slide changes on the previous slide, and I should go into some background here.

So in DP3, when everybody first saw Aqua, the controls were much bigger than they were in Platinum. I think push buttons were around 26 pixels tall, pop-ups were maybe 24. Everything in general was larger. And we heard a lot of feedback about that. You told us that it was going to be very difficult to relay out all your dialogs. And we took that feedback to heart.

And so now in DP4, all of the controls are basically the same, use basically the same metrics as their Platinum equivalents. The heights for the controls are mostly maintained. There are a few cases where we won't shrink below a certain size. For instance, you can't create a push button that's six pixels tall. That kind of defeats the purpose. And a few controls' widths do increase slightly.

There's a number of reasons for this. Like I mentioned before, Lucida as a system font is slightly wider than Charcoal and Chicago. So if you're using static text items or if you have certain controls that have a lot of text in them, you might find that you need to widen it a little bit to show it on the same number of lines you used to be.

Additionally, a few of the controls, like push buttons, have a more rounded appearance. The end caps on Platinum push buttons were practically square, so you could cram a lot more text onto the button image. But an Aqua one is more rounded, and if you start cramming the text on, the text might write off the edge.

So you'll probably need to widen your dialogs or widen the items out in your dialogs and controls a little bit. But to help... So we didn't want to wreck your investment in your dialog layout, so we tried to make it such that your layout effort was about equal to a localization effort, but not more than that.

And the other benefit is that if you take a dialog that you've implemented to look really good in Platinum, and you relay it all out for Aqua, and you take that same dialog and run it back on Platinum again, it's still going to look good. So you should be able to get away with just having one set of dialog and control resources for your application.

So I mentioned before that we've got a number of new controls, and I'd like to take you through them one by one. So the first one's the round button. You've probably seen this either in the Finder or in the Help Viewer. It's generally used as a navigation button, you know, forward, backwards, home, things of that nature. And you can customize its content through an icon ref.

Of course, we have a new creation API for this one as well. We're adding a whole slew of new creation APIs for all the controls. We'll go into details on that in the Carbon enhancement session. But we've got one for the round button to make your life easier.

You may not have seen the disclosure button before. This right now is only showing up in the open and save panels. It's used to, for lack of better words, expand and contract the dialog. If you click it when the dialog is in its small state, it expands to the large state, giving you more information. Got a creation API for that one.

So when we introduced Mac OS 8, we introduced a progress bar control. And that was really cool. People used it for progress. But other people started using it for relevance ranking, including our own products. Sherlock used it for its relevance ranking indicator in searches. But we redesigned the progress bar for Aqua, and its appearance really isn't suitable anymore as a relevance ranker. So we've introduced a new control called a relevance bar, and it's perfectly suited for relevance ranking. We use it in Sherlock, obviously.

While I've got this slide up, the bottom half of that Sherlock window is another new control we're adding. It's not just an Aqua control, but it's also available on Mac OS 9. It's called the Data Browser, and we have a complete session on that. It is a super list manager replacement, or you can think of it that way. It's a totally modern control that's both Aqua-savvy and Platinum-savvy. It does all the list management and UI that you would ever want, draws those header buttons, deals with the shadowing effect underneath the header buttons, and all that wonderful stuff.

So like I mentioned, we've had the Progress Bar for quite some time now, but I've seen some apps that still didn't realize that. It's been available since Mac OS 8, but there are still applications out there that use the old fill-rec technique to do progress. It's going to look really crummy under Aqua, so please, please, please start using the Progress Bar control.

If you can't use the Progress Bar control, we have an appearance primitive to make your life easier. Keep in mind that right now there is no way to get the appearance primitive to animate the way the Progress Bar does on Aqua. The actual, sorry, the actual Progress Bar control is the only way to get animation of the Progress Bar on Aqua.

So a few of the controls you've grown to know and love have been enhanced slightly. Sliders and scroll bars support a new feature which is called Scroll to Here. Scroll to Here works such that if you click in the page up or page down area of the scroll bar, the thumb jumps automatically to that location. You can start tracking the thumb from that location.

Likewise, for sliders, you can click in the middle of the slider track and the thumb will jump automatically there. Of course, if you don't like that behavior, you can always option click in the track and you'll get the same behavior you're used to on normal Mac OS. And I believe there's a preference in the preferences application that allows you to toggle the default setting.

Now, Scroll to Hear is only available for live tracking variants of the controls. There's a couple technical reasons for it, but in general, just start using the live tracking variants of the controls. This is good for a couple reasons. Not only do you get the Scroll to Hear behavior, but also you're going to fit in a little bit better with the overall Aqua experience, which is about providing immediate live feedback to the user. It's much more satisfying if you can click on a scroll bar and start scrolling it and see the content move immediately. So please, please, please use the live variants.

If you had a chance to play with any dialogs under Aqua, you've seen that our default button no longer has a ring around it. Instead, it pulses. This happens automatically when you use the push button control, so long as that push button control has been tagged as the default button.

There's a couple ways to do that. The setDialogDefaultItem API is one way, and that API has been around for a long time. If you have a dialog, the simplest way is to just use setDialogDefaultItem. If you don't have a dialog, there's actually two options. The first and most high-level option is to call setWindowDefaultButton.

You can call that on any button in a window. You should obviously only call it on the one button you intend to be the default. Alternatively, you can call setControlData with a special tag and some special data on an individual control to do it as well. But in general, it's easier to just stick to the dialog and the window versions of the APIs.

So one important note I should make about default buttons is that a lot of your application code tends to depend on the old behavior of the toolbox in Mac OS 8 and Mac OS 9 where we patch quick draw to determine if you're calling frame around rect. And when we see that around a control, we go and we tag it as a default button automatically behind your back for you.

And that was intended to allow you to transition to the platinum appearance a little bit easier. But you know on Mac OS X, you can't patch and we're in the same boat as you guys. So we can't patch quick draw anymore. And if you're calling frame around rect around your default button, you're going to get around rect around your default button. It's going to look kind of bad.

As I mentioned before, the progress bar now animates. This is good because it gives the user a better indication that your machine is actually live and still running, even if your progress bar isn't updating. Maybe it's hit a snag in the internet connection if you're downloading a file or something like that.

It still gives the user some feedback. So the appearance manager under Aqua, to a certain extent, had to be gutted and rewritten from scratch. We did this so that we could take advantage of the cool drawing services that Quartz provides. And additionally, we obviously needed to offer some new APIs to your applications so that you could render your widgets manually using--in an Aqua-savvy way. And I give you one example of that before and that was the Theme Text APIs. We've got a few others as well.

So the new controls that we're offering are obviously backed by new appearance primitives. And if there isn't a primitive that directly applies to that control, we've probably enhanced Draw Theme Button to take care of that particular widget. There are a number of new theme button kinds that are used with the Draw Theme Button API. One particularly interesting constant is the KThemeListHeaderButton. Right now, that's the only way to draw a list header button the way you see in Data Browser, in the Finder, in Sherlock.

We don't offer a control to do that yet. Hopefully, Data Browser will serve your needs, but if you do find some needs, if you do find it necessary to draw those buttons on your own, we can probably do some kind of control for you. Just let me know. Of course, we have theme button constants for all the standard controls, all the new standard controls I just showed you, like the round button and the disclosure button and things of that nature.

So on Mac OS 8.5, we threatened to start doing themes with patterns in them. But we didn't really follow through with that. Well, now we followed through with it in Aqua. We actually have theme brushes that don't just represent RGB colors. They represent patterns. And if you want to draw backgrounds of either dialogues or windows or certain controls like tabs and placards in a theme savvy way, you'll need to use these theme brushes.

Additionally, if you're trying to save and restore the graphics environment around a call to, say, draw theme button, you'll need to use some APIs we added in Mac OS 8.5 dealing with drawing states. These drawing state APIs are a encapsulated way to save and restore and normalize the drawing state in a way that's completely pattern savvy. So I suggest you start adopting these immediately. If you find that your application comes up and patterns aren't quite aligned right or don't look quite the right color, it may actually be the necessity for your code to adopt these drawing state APIs.

So this is it. This is your chance. Your application could be the first one of its class to go out and adopt the Aqua interface. And that would mean that that's the one customers are clamoring for, because everybody wants to use the cool new stuff on Mac OS X. And we've tried to make that as easy as possible for you to adopt. Of course, if you use the standard system menus, controls, and dialogs, you're going to get most of this stuff for free. If you're already that far, great. You only have a couple of the steps you'll need to take.

The obvious choices are taking advantage of Sheets in any way you possibly can. You'll want to use Nav Services and Printing and their Sheet support. If you have custom Sheet support, you can use the Sheet APIs we're introducing directly in the toolbox. And then you want to relay out for Aqua to make your stuff look good.

Most importantly is probably the menu bar layout, so that you can give the user an overall good experience and an intuitive sense of where to find the right items in the menu bar. And then you want to relay out your dialogs to look good with the new Aqua metrics. So with that, I'd like to bring up John Glunze to lead us through the roadmap and some Q&A.

Thanks, Guy. So there's quite a few sessions that kind of relate to this stuff, not specifically to these APIs, but that relate to other Aqua APIs or other Mac OS X APIs that affect sort of the user experience. One is already passed, which is the Aqua Overview 140. Using Interface Builder is... Interface Builder is a great tool for prototyping your applications on 10 and getting the right look under Aqua.

Guy referred to Data Browser for this list manager on steroids, so to speak. Control that you can build into your applications and get finder-like lists and that type of behavior, that's in the Data Browser session. Icon Services in Aqua 147 on Thursday. That's a session you need to go to to learn how to create great icons, take advantage of Icon Services APIs to show those icons at different sizes, et cetera.

Navigation Services is... Talks about the open and save dialogs and new APIs in that regard and finding out how to do the proper open and save dialogs under 9 and 10 with the new APIs that are there and getting the right look and feel, sheets, et cetera, for opening and opening of files. Apple Help, again, like I said in other sessions, HTML Help is the way to go with help on Mac OS X. So that's the session you need to go to, and we're going to talk about help APIs, but also how to author the HTML Help in the right way.

Application Packaging and Document Typing, Session 144. It's not so much about the visual user experience of Aqua, but it relates to the Packaging Model on Mac OS X is a user experience related issue. You also need to know about the new document typing and file naming conventions that are on X and how that affects you and your users and your application development. This session will cover Carbon Enhancements 1 and Carbon Enhancements 2, which will go into more depth on some of the APIs that Guy has talked about and other APIs in Mac OS X that affect the user experience that you're going to deliver.

And then of course the Aqua Feedback Forum, which we're really looking forward to and we're going to invite you to attend. As well as the High-Level Toolbox Feedback Forum for giving Guy and his team and the High-Level Toolbox team feedback on the High-Level Toolbox. Those are the sessions that you should think about attending and we would encourage you to attend.

Who do you contact for more assistance as a developer? First of all, myself, if you need assistance in understanding Aqua or understanding how to do an application that really is going to take advantage of the rich, elegant user experience of Aqua, please get in touch with me. Specific to APIs, I would say that you should contact Guy.

If you have API issues, if you have requests for new APIs under Carbon or changes to APIs or those sorts of things, the other contact is David Wright. Both of us are in the Worldwide Developer Relations Organization and we'd encourage you to contact us with developer related issues around this topic. So I'd like to invite the High-Level Toolbox team up on stage for the Q&A.