Good afternoon and welcome to the what's new in HIToolbox session. I'm Guy Fullerton. I'm the manager of the High Level Toolbox team. In the past couple of years at WWDC our message has been about the future of HIToolbox development and I've said the future is Cocoa. Well today I want to talk about that in a little bit more detail and kind of give you an idea of what we do internally in terms of that future.

So post Leopard, we don't find plan to add a lot to HIToolbox. We plan to only add minor features. To give you an idea of the sort of minor features we would consider adding. For the Leopard interface, we added a few API to Leopard to allow your application to tweak that interface slightly and get it to load great under Leopard. That's the kind of thing we foresee adding to HIToolbox post Leopard.

We also plan on maintaining our existing bridges to Cocoa, but we've added all the bridges we plan to add there and we'll probably fix some bugs in those bridges. We'll fix some bugs in our critical technologies but that's about it. That's what we really plan to do for HIToolbox. So any of your HIToolbox code that is currently in existence out there that you're maintaining is at a crossroads. You've got a number of different ways to bring it forward to the future.

One way is to modernize it the Carbon way. Depending on your application, this way be a lot of work or it might be a little work but generally this involves getting rid of QuickDraw, drawing with Quartz instead, switching over to HIView compositing mode. And that will give you a few benefits. You will be able to get the resolution independence that way.

You'll be able to use new features like HICocoaView. You'll be able to use some of the new views in the past few releases but that might be a ton a work. Now it really depends on your code base. It might now be a lot of work for you, but if it is a lot of work for your application, now is that time to look and see if it's the right business decision to just go to Cocoa.

Now there's a number of different ways you can go to Cocoa. Clearly the most extreme way is to rewrite your app from the ground up. That might be a lot of work, but it might be less work than transitioning to modern Carbon. You can also adopt piecemeal. If you're revving your application and you want to add a new window for a specific function. Maybe you're adding a modern preferences dialog that matches the way Mac OS does preferences. Maybe this is the right time to implement that preferences window as a Cocoa window with Cocoa views. Using all the Cocoa technologies and the Interface Builder support and so on.

If it's easy to get to compositing in your application, you can use HICocoaView as a partial bridge. You can start adopting some of the new Cocoa views, or older the Cocoa views and dropping them into your application in various places and take advantage of cool functionality. And we're going to talk about that a lot more later in the session. Now a lot of these solutions require you to factor your applications in ways you may not have.

And that can be a lot of work, and that again comes back to potentially rewriting in Cocoa. So it's really up to you. You guys are the ones that are maintaining the code. You guys need to look and see what it's going to take to modernize it via Carbon, versus modernize it via Cocoa. If you do go ahead and decide to modernize it via Carbon realize that your getting yourself into a little bit of a dead end strategy because we're not planning on adding a lot of functionality to Carbon.

A great example of this, obviously, is 64-bit. I'm sure you all hear this. I'm sure some of you hissed at this when Bertrand talked about no Carbon UI in 64-bit. d But the fact is this is the plan. So we didn't go into a lot of details in the earlier sessions. I'd like to talk about some of the details now. Specifically the Carbon constructs that generate user interface.

Your controls, windows and menus will not be available in 64-bit. Some of the other associated technologies won't either. MLTE/Textension, whatever you call it. Is there purely there to do text editing in Carbon views, so that won't be available in 64-bit. I also have the HIObject listed up there.

That's only sort of not available in 64-bit. The HIObject APIs will be available in 64-bit purely for the construction of just a generic HIObject to use as a receptor for Carbon events. Speaking of Carbon Events, they're still in for 64-bit. You will still be able to create events, destroy events, send them to event targets, receive them, get and set parameters and so forth. But keep in mind that a huge portion of our existing Carbon events are all implicitly tied to controls, windows, and menus and none of those events will be sent to you. So you won't be able to listen to those.

But there are still some sort of interface agnostic events that will still get sent out normally. Another piece that's going to stick around is text input sources. This is, I believe, it's new for Leopard. It's a more modern set of interfaces to doing input method type technology. That is not tied implicitly to Carbon UI, so that will stick around for 64-bit.

So there's kind of deciding how to say this next thing. There's 2 other points that I want to talk about. I don't list all the HIToolbox technologies on these last 2 slides. To be completely honest we're still figuring out what's in and out. Some hard lines have been drawn. I've shown them on these slides, but if you've looked at the Leopard beta you may have noticed that all of the HIToolbox APIs are still there for 64-bit.

And that's because we haven't finished decideing what's in, what's out and dealing with all the resulting fallout. We plan to have all those decisions in the coming weeks. And we'll remove them for GM. So even if you do get excited and see that those APIs are there in the beta.

Please don't develop against them; you're just getting yourself into a dead end path. So with that out of the way, we did add a few things to HI Toolbox for Leopard and the first thing we'd like to talk about is adopting the new Leopard appearance. I'd like to bring Kurt up to take you through that.

Kurt: Thank you, Guy. So obviously the interface in Leopard has changed. The good news is that we've all been through minor changes in Aqua before. So as long as we're continuing to use the standard window controls. In theme brushes, the application interface should continue to load just great. There are a couple of changes related to Leopard changes however, that you may want to adopt.

First thing you probably noticed is that standard windows that have a toolbar rather than having this distinct look between the title bar and the toolbar. Now they have this unified appearance. This nice gradient from the top of the title bar to the bottom of the toolbar and you don't have to do anything to adopt this. This is just a change that we've made and you'll get this appearance for free as long as you're using a Carbon toolbar.

We did have a similar implementation back on Tiger, but we didn't publicize how to get that. So we're adding a window attribute and we're exposing that in Leopard. The K Window Unified Title And Tool Bar Attribute. So using this will get this similar appearance back on Tiger, but will have no visual effect on Leopard because you'll just continue to have the nice gradient.

Windows with the K Window Metal Attribute will get this full grey appearance. Again it's a consistent title toolbar look and then this full grey. We didn't change any of the metric for windows with this metal attribute so we continue to outset the frame for pixels or for points and on the bottom as well. But we don't recommend doing this. The recommended appearance is to just use the standard document window for your appearance. This allows the content to go up against the edges of the window and it has a really nice, clean look.

Some standard applications including many that Apple provides like in this case Finder or iTunes, iPhoto, and iCal have this section in the bottom of the window which we call the bottom bar where you can put your status information or some controls like buttons, like in iTunes there is a plus button to add a new Play List.

So since they are using the standard window, just a standard document window. You need to tell the toolbox somehow to draw this area. It's not just a standard theme brush; you can't just draw this look. It's nice gradient, so the toolbox needs to know about it. So we've added this new API called HI Window Set Content Border Thickness that allows you to set an inset into the content area of your window where this gradient will be extended.

Currently we only allow a content border on the top and the bottom of the window. You'll get this nice gradient. Since this is now in the content of your window you can draw in this area using stat, you know, just putting in your status information or drawing some buttons, and it's a nice clean look. Since this is in the content of the window, and your content is rectangular the default look is to get the square bottom corners.

We do realize, however that some applications may want them to be rounded so we've added the KHI Window Bit Round Bottom Bar Corners. This is only valid for windows that have the content border thickness for the bottom and even then if it's only big enough. And big enough is currently defined to be greater than 15 points and this is so that the masking of the corners looks good. It doesn't work with windows with the metal attribute. The metal windows have their own way of dealing with rounded or squared corners.

Also in Leopard you obviously noticed that the menu bar is transparent. So if you're having a toolbar in your window by using the utility window and positioning that underneath the menu bar, your users will see what you're doing and they'll think it looks pretty tacky. So that way that you correct this is to use a window that is using the toolbar window class, and you just position this below the menu bar. The toolbar window has no title bar so you won't get the look and you'll get the desired behavior.

Next I'd like to talk about HICocoaView. HICocoaView is a big deal and this is a new HIView that's available. It's only for compositing windows and it's a container for Cocoa views. Why are we providing this to you? Well there's 2 reasons. The first reason is that we have 2 separate frameworks implementing the same user interface. There's the high level toolbox and Carbon stack, and AppKit in the Cocoa stack.

And there's been some discrepancies. Some controls have a richer feature set than others, and some controls that just been implemented in one stack and not the other. So we want to be able to provide this consistent experience and allow you to take advantage of some controls that are available in AppKit.

And this basically is the second reason as well. We have a rich feature set in HI level tool box in terms of which controls you can use, but AppKit has a really has a super set of that. Including some controls like the NS Rule Editor, NS Token Field as examples.

Furthermore all new developments with new features are being represented in terms of NS views or Cocoa views. So if you want to use Core Animation or PDFkit or WebKit in your application, you really need to start doing this in terms of Cocoa. And we want to allow you a way to use these new technologies and pull them back into your Carbon applications.

As an example the decision was made for Leopard to integrate Finder and Spotlight. Now Spotlight had done all their user interface in Cocoa which was available back on Tiger. And we wanted to pull that into Finder as well. So when you execute a search in Finder, that whole section of the window is replaced with a single HICocoaView and now a rich NS view hierarchy is embedded in that area of the window.

It just reacts how it's expected to. The user doesn't even know that there's another framework that is operating in that area of the window, and that's really the idea. We just want to be able to allow you to leverage new technologies for Leopard's new development that you've done in other areas. In different application in the utilities as an example.

There's 2 ways to create in HICocoaView, the first is problematically. Just as a side note, when you're running in the context of run application event loop, like when you're responding to Carbon events that is being sent out of the event loop. We take care of setting up and disposing the auto release pool around there.

So you only need to create and release and auto release pool if you're out of the context of run application event loop. For example you're setting up your application initializing before getting into the context. Next you just create and initialize your NS view. In this case we're just creating an NS button.

Call the API HICocoaViewCreate the first parameter is the Cocoa NS view, second parameter is a set of options. Currently we only accept zero. And this API will return to you an HICocoaView which is an HIView, a Carbon view. So now you can use any of the standard HIView APIs on it in order to position it so its bounds, so it's HIViewLayout information and in this example I'm just adding it to a parent which will then display it in a window. The API also retains the incoming Cocoa view so you can go ahead and release it afterward.

The second way you create a HICocoa view is using Interface Builder. Now on the Leopard version on the version of Leopard that is available to you right now, there is no distinct HICocoaView in Interface Builder's library. We hope to have that addressed by the time we jam. So currently what you would be doing is selecting the custom HIView item in the Interface Builder library, drag it to your window, and in the inspector window change the class ID and make sure that it's com dot Apple dot HICocoaView. Then when this window is instantiated there will be empty HICocoaView container.

Then you'll programmatically set a Cocoa view in that HICocoaView. Using that HICocoaView set view. This API will do what you expect if the HICocoaView does contain an NS view already; it will release it before retaining the incoming one. And finally we have an API HICocoaView get view which will return the associated NS view.

So this is kind of new, we're using new technologies that we may not be used to. So what are these new changes we have to make? First of all since your going to be using AppKit most likely for some of these controls you need to make sure that you're linking to the appropriate frameworks. So link to the Cocoa framework. If you're using other things like QTKit, you'll have to make sure that you link against that framework as well.

You're now adding Objective-C C code to your files as well. The compiler will complain. It doesn't understand what these brackets mean basically. So you need to make sure that you compile your modules, your C and C++ files with the Objective-C or the Objective-C++ compiler. The way you do that in Xcode is you select the file, get info on that file, and make sure that the file type is set to Objective_C of Objective-C++.

During the initialization of your application, call NS application load. This will load and initialize AppKit to be run in a Carbon application. And finally like I mentioned before, set up an outer release pool around your code that creates NS objects if it's outside of the context of our application event load. Now because this is so easy to do, and I really want to encourage you to do it, I just wanted to run through a quick little demo of modifying a Carbon application to use on your AppKit technologies.

So first let me provide a little bit of context here. What I have here is just a simple Carbon application and just suppose you have an image processing application that brings up a dialog and this is the dialog that you'll see. Over here, well what this style would be for is to select an image from a particular library for example. So I present some libraries, plants, abstracts.

And then I have this view here which displays the images in the library where I can navigate between the different images. When the user finds an image that they like, they are able to add some tags to it like green grass. And then when they select the image, the image process application will go off and do whatever it needs to do.

For users this isn't a really great interface for the tags, because these really are types of tokens where, and it's kind of silly to ask the user to separate each tag by a comma. So as a developer I'm looking at this and thinking I'd really like to have a tokenized feel. Something like in Mail, in the To field, and when you add a name it turns into this atomic unit. And I know that the NSTokenField does that. So let's go ahead and modify this application to use an NSTokenField in that area.

So this is basically my interface. There is this data browser view over here. This is a custom Carbon view, the image browser view. Now if you've come to any of the last two years in WWC and watched our creative custom HIView sessions, we've gone through building a version of this kind of view.

So this is just that custom view that I've included the sample code in, in this mocked up application. The sample code for that view is available on the ADC web site. So you can download and see how we're doing that. But the meat of this is it really let's change this edit unit code text field to be an NSTokenField.

So I select the item and in the identity inspector I want to change the class ID to com dot Apple dot HICocoaView. I'm also going to, just for cosmetic reasons, increase the size of the field and I want to make sure to add a control signature and ID in. This is just so once the windows instantiated; I have a way to programmatically access that created view. So I add tags here and now I need to go about modifying my application.

Since I'm going to be bringing in some files related to AppKit I need to make sure that I am linking against AppKit, so in my external frameworks I want to make sure to link against Cocoa and the Cocoa dot framework is an umbrella framework which contains AppKit and Foundation.

Next, because I am going to be adding some Objective-C code to my C or C++ file, I want to make sure that I'm compiling with the correct compiler. So I select the main file, get info on it; verify that the file type is set to Objective-C or Objective-C++. Finally let's bring out the app or the main file. I'm bringing in Cocoa; this is just so I can bring in the headers so I know I have a reference to the NSTokenField. I add a constant so I can access that HICocoaView in the window.

Then in main I want to make sure that I call NS Application Load, this will initialize AppKit to be run in a Carbon context and then I set up an amount of release pool. This is because I'm going to be creating this window during the initialization of this app prior to getting into run application event mode. I want to free it, release that pool prior to getting the run application event load, other wise we're just having a pool that's leaking for lack of a better term.

I have this function called SetupWindow. This basically just sets up that data browser. It populates it with the library information. But this is where I'm going to set up that NS token field so I'm using HIView find by ID in order to grab the HICocoaView that is in that nib. Once that nib is loaded, I'm creating by allocating and initializing an NSTokenField and then call the HICocoaView Set View API.

Passing in my HICocoaView. In the second parameter is the NS view. This API will retain the NS view so you can go ahead and release it afterwards. Now assuming I haven't done anything wrong, let's see what it looks like now. So it's the same application I can navigate between these but this tags field should be an NSTokenField.

So this really does provide a nice experience to the user. It tokenizes this field. It does respond to focusing correctly as I tab you can see the different controls are still tabbing around, and it does get the same user interface that you'd expect like rollover works, dragging the items continues to work. So it just enhances the experiences the user so you've been able to add a control that has been implemented in AppKit, not in Carbon. A high level toolbox and use that in your Carbon application.

Finally I was looking through the example code, in the Leopard seed and I noticed that developer examples Quartz core. There is a Core Animation example where it's a Core Animation implementation of Cover Flow. I thought that was a really good, it's kind of a good sample code that I could be using in this application. It contextualizes the images better. You can use Cover Flow, and it's dynamic. You know, it's flashy. So let's go ahead and add Core Animation support in here as well.

So I'm going to go back to my main nib and replace this image browser view with an HICocoaView. So just like I did with the NSTokenField, I changed this to be an HICocoaView. Core Animation is in the Quartz core frameworks so I need to make sure that I link against the appropriate framework there and I need to offload tie as well on stage.

And just like with the TokenField, I go ahead and add some support here. Actually before I get into doing that, I should add the sample code from the Core Animation file into my project as well. So if you go in and look at that example, the Core Animation example which they call Covert Flow.

It's just an MVC. It's a standard Cocoa application where there's the nib and then there's the associated files that deal with the model, the view and the controller. And all I'm going to do is just take the nib, drag it into my resources, in this case I'm just going to copy it in.

I also want to create a group here in my source code for the Covert Flow and add some of my project. And that's basically all I've done. I haven't really updated the code and I'll talk about a little bit about what I've updated in that sample code when I'm done here.

Then like I said, now we go ahead and update the code itself. So the way the Covert Flow application is architected there's the controller and then we allocate and initialize that. It goes ahead and loads that nib up, so I need to make sure that I reference the controller.

Back in that same set up window function after I've set up the TokenField. I'm going to add this section of code. This basically does the same thing as what I do with TokenField. I have the controller, I allocate and initialize it. That will take care of loading any information from the nib.

I did a reference to my HICocoa and I associate the controllers view with my HICocoaView. Finally I have a function in here to update the viewable images, and the way I was doing that previously with the Image Browser view was using an API for that view to set its images and I changed that to set the images on the NS view.

Use the API HICocoa get view, this gets the associated Cocoa view and then I set the images using the set images on that view. Now this may be a little bit confusing and I intentionally left the code, the structures are called view. And that may be confusing but that's really just what the sample code for Covert Flow referred to these items as so I just didn't want to change any of the things and make it any more confusing than it needed to be.

And I mentioned that I did change the sample code just a tiny little bit. And what I did was I added an API on the NS view that would accept some images So when I get the set images message the view itself just messages the controller, and it takes care of putting the images into the model and then updating the view itself. So again, cross your fingers, make sure I didn't do anything wrong. And now we see that we've implemented Cover Flow using Core Animation inside my Carbon application.

So the point here is to move forward using, you know you have to get used to using Cocoa and start using it in your Carbon applications. And there are these new cool technologies and I want you to be able to use that in your existing apps to go ahead and update it. So to talk more about Carbon and Cocoa integration, I'd like to bring up Bryan Prusha, and switch back to the slides please.

Brian: Thank you ,Kurt. Alright to... continue on with the theme of adding Cocoa to your existing Carbon application. I'm happy to say that we've already started doing a little bit of that for you. Open and save panel, panels through Navigation Services have been completely reimplemented on top of Cocoas open and save panels.

The three things I want to talk about here, how this provides more consistency for the user some compatibility issues that you'll need to be aware of in your applications, and continuity. How this will help you move on to more AppKit and Cocoa technologies in the future. So because the Navigation Services dialogs are hosted by the Cocoa UI, the same look and feel, the same accessibility characteristics. So your users will have a seamless user interface that they haven't quite had before.

There always been a couple little glitches along the way. One cog yet with accessibility in the beta right now, no accessibility events reach the custom area at the bottom. This will be addressed before we ship. So let's look at some of that new UI that we have. Navigation Services is inheriting from Cocoa the new side bar that's shown up in Finder. Beautiful new icon view.

Updated searching capabilities and even a media browser so you can look at your music, your movies, and photos of your kid on your computer. Right. So we've got all the new UI. What does this mean for you in your application? Well we've done everything we can to make this as seamless as possible. With any luck you won't have to do anything to take advantage of this. It will just appear. But in some cases, your application will have the old Tiger look.

So let's talk about that. This will appear for 2 reasons. If somewhere along the way during one of the releases we've discovered an incompatibility with your client code in the way that we've made changes inside Navigation Services. One example of this would be the transition in Panther to compositing dialogs.

So we've made and added an applications this doesn't work around. And similarly this transition to Cocoa we may have found a compatibility issue with this new implementation. So if your code was doing something that we didn't expect with the API, or perhaps you were looking for specific dialog item, or Carbon control that no longer exists in the window.

So what can we do about that? First thing to do is to review the bugs that have been sent to you by Apple. Anytime we've made one of these applications this doesn't work around, we've sent a bug to you describing exactly what the issue is and what you can do to fix it.

So once you've looked at that, increment you CF bundle version in your info P list and that will tell the Navigation Services implementation to stop adding the applications to the specific work around. Then you'll see wherever crash or drawing glitch or whatever was keeping us from giving you the new UI. You can fix it and ship that in the next version of your app.

So one causality of the transition you may have already have noticed in your seed is that the Nav preview proc is no longer being called by Navigation Services. So if you used to have some navigation that looked like this, where we would pass you a rectangle for the entire preview column area which you can draw into. On Leopard it looks a little more like this.

So you'll just have the standard document icon for your application and plus at least you'll get back some mediate the user can see. So we weren't able to provide for. So one thing that we've done to address this is to add QuickLook support to the Cocoa open and save dialog which again are inherited by the Navigation Services. So if you write a QuickLook plug-in, you can ship that along side Leopard. And even existing customers customers of your existing application can take advantage of QuickLook in your previews here as well as the rest of Leopard.

Alright. I've said that we've done everything we can to make sure that this isn't something that you don't have to adopt, but there are things that you can adopt, if you want. The Nav Dialog Ref in Leopard is actually a subclass of NS Opener Save Panel, depending on what type of dialog that you have.

So one thing this means is that you can cast that Nav Dialog Ref to the NS open or save panel pointer and once you do that, you can have access to new API that already exists on the AppKit side. So if there's any APIs over there you've been lusting after, here's your chance.

So the first thing is that accessors are a-ok. Any of the setters and getters are things that we want you to be able to use. One exception on the beta is the API SetAccessoryView. Right now this will cause an exception if you try and do that. This has already been addressed in internal builds and of course we'll shift with the fix. But I wanted to make this... talk about this one specifically because as we move forward to resolution independence, adding a Cocoa accessory view will be your only option to achieve that.

The 2 things that we don't want you to use are the NS Open and SavePanel runtime APIs. If you created your dialog using the navigation services APIs, you'd execute it using NavDialogRun. With Navigation Services in the new implementation we've added a lot of hooks that only get installed when you use NavDialogRun.

If you try and do an end run around them using the NS Open Save Panel run time category those won't get installed and things will break. And similarly don't reset the delegate. Navigation Services itself is using the delegate to provide functionality for your application and make sure that everything continues to behave as you expect. So if you reset that, again bad things will happen.

So let's look and see what this will look like in code. You create a get file dialog with nav create get file dialog in standard wave and then we can do a simple cast to an NSOpenPanel because this is a get file dialog corresponds with the open panel.

We can use the API set prompt, which sets the text in the default button and what's cool is that instead of just being able to set this when you create your dialog, you can set it at any time during run time. I know that in the past some developers have gone and looked for that Carbon control, that default button and set the text manually. Well that button doesn't exist anymore on the Carbon side. So this is your accepted API to get at that.

So we created the dialog using navigation services, we need to use NavDialogRun. So the user does the doing, they select some item, they come back and again we can cast that to an NSOpenPanel pointer and use the files names API. What this does is return an NS array of NS URLs to the selected items on your disk.

So if any of you've had any trouble using Apple Event descriptor list to pull out all the individual Apple descriptors and get all the data out, this can be a very simple way to do the same thing. And because the dialog is an NS object you can call release if you want.

So hopefully this will give you ways to add piece meal, add bit by bit more and more Cocoa functionality to your application without having to do a wholesale rewrite. And if you do eventually move entirely over to Cocoa this is all this new API that you're using will not be thrown away, so you can keep that work. Alright. Next I'd like to bring up Eric Schlegel to continue talking about this transition.

Ok thanks BrYan. So we've been telling you a little bit about the ways in which we're trying to make it easier to use Cocoa in your application in your Carbon application, but we do also have some other features added to the toolbox in Leopard that are actually just specifically new features in the toolbox. So I'm going to talk about a few of those today. The first one is Spotlight for menus. Which actually isn't just a toolbox feature, but I'm going to talk about how it interacts with your with you Carbon application.

Spotlight for menus is the term for the feature in Leopard that adds a search field to the Help menu in every application and that search field is there to try to make the help system more accessible to users and to make it more something that is very visible to them so that they can find it and use it. And it lets you search all the text of the menu items in your application to find items with a specific sub string and item name and also to search through the help files that are bundled with the application.

So because this is interacting directly with your application's menus, you might think that you might have to do something specific to support it, but that's not really our design goal. Our design goal is to make this complete invisible to applications as much as we can. And there's nothing that you specifically need to do to support Spotlight for menus searching through your applications menu items.

But we've seen some compatibility bugs, and so I want to emphasize that if you do see problems with using the search facility in your application or with using Help menu in its modified state in your application, tell us about those bugs. File them in Radar please let us know about them. We can only fix them if you tell us about them so please do report those compatibility bugs, if you find them.

Another point I'd like to make here is the appearance of the Help menu. Previously it would be something that you could control; now the Help menu appearance is slightly different from that of the other menus in your applications. The menu item text is a little bit smaller, it's offset slightly. And this is all done to make the default Help menu appearance as synchronized with the appearance when you're showing search results. And that's under the system's control at this point. It's not something you can modify yourself anymore.

So even though we are trying to make this as compatible as possible with applications by default, I do have some tips about how you can potentially make your application work a little bit better with Spotlight for menus. The first one has to do with the hot key. You may or may not have noticed that in Leopard pressing command shift question mark which previously might have been mapped to a menu item or something else in your application, will now open the Help menu and if the Help menu is already open it will close it.

So that's a new hot key that's been defined by the operating system. You can change the keystrokes that are associated with it in the keyboard preferences page. You can disable it if you want, if that... if you disable it then the keystrokes are entirely ignored by the OS and they just go right back to your application. And if you really need to, you can intercept those keystrokes yourself by installing one of the standard Carbon event handlers or text input such as K event text input unit code for key event.

So if you do particularly need to use the keystrokes that are being mapped to the help hot key for your own purposes, you can install that Carbon event handler anywhere on the standard user focus chain. On a view, on a window, or the application target and you'll get those keystrokes and you can do whatever you want with them. But we really recommend that you don't do that, we recommend that you just let the standard behavior be allowed for the application.

The second tip here is how...regarding how you create your Help menu. Applications usually have one or two ways of creating their Help menu. They can just create a menu from scratch, and give it the title help and stick in the menu bar. Or they can use the HM get Help menu API.

And Spotlight for menus will work in either case. If you create your Help menu from scratch, we try to seek it out basically by looking for a menu in the menu bar that has the title help and we try to avoid interfering with your use of the menu as much as possible. But that's another case where if your seeing compatibility problems, file those bugs so we can look at what's going on.

But we also recommend use the HM get Help menu API which is part of the help manager in HIToolbox and Mac help dot h and if you use that API then we know exactly what you're doing and there's no confusion at all. We know that you're creating a Help menu and we can treat that appropriately.

Third tip here has to do with how you add content to your menus. It's pretty common that applications will want to dynamically populate the menu items in their menus. One example might be you could have a recent files menu that shows you all the recent files that a user has opened.

And you might not want to actually populate the contents of that menu until the user pulls it down because it might be a little slow to go out and grab that list of files and stick it into the menu. So we've have since 10.1 the K Event Menu Populate Carbon event. Which is sent to your event handlers right before the menu is opened to let you dynamically add the menu content.

And it's especially useful to use this Carbon event today in Leopard, because this Carbon event is also sent by Spotlight for menus before it opens the Help menu. The Spotlight system needs to index all the menu item content of all of your menus so it can quickly search through it when the user types in a search string.

And in order to index an up to date version of the menu item content, it sends K event menu populate before it does the indexing process. So definitely use this Carbon event if your dynamic menu item population and that will make sure that whatever you're dynamically adding to the menu will be properly indexed and searchable by the user.

And finally, this has to do again with how you populate menu content. Let's go back to that recent files menu again. Maybe the items in your recent files menu not only have text giving the names of the files, but they also have the icons of the files. Getting those icons might get a little slow especially if the file's located on a file server across an Airport network, and if you go across the network and pool the icon back and all that.

And if Spotlight for menus is the reason why you're adding the content to the menu, Spotlight doesn't care about the icons. It only searches text. So there's really no reason to add the icon or to pay the performance penalty of going and fetching it, if the only reason that you're populating the menu is to allow Spotlight to search it.

So to that end, we've added a few new bit masks which are part of the menu context parameter it's a Carbon event parameter in K event menu populate and other Carbon events. And you can see some of them here, K menu context don't update text, don't update key, don't update icon and don't update enabled.

And those simply indicate what parts of the menu item state you do not need to update at this time. So if Spotlight is sending out this event, it's going to set the don't update icon flag for example. And that tells you I can save some time here, I don't need to go fetch the icons and stick them into the menu. All I need is the text, and also the text will be faster to update than the icon.

That's it for the Spotlight for menus section. We're going to talk about a few text drawing enhancements next in HIToolbox for Leopard. And the first one is CF Attributed String. Now we've had for a long time the ability to draw CF strings using the toolbox, using the text drawing the keens and the Appearance Manager would be draw theme text box and the HI theme draw text box.

In Leopard, HIThemeDrawTextBox also supports drawing a CF attributed string. You may not be familiar with a CF attributed string as a new type that was added in Tiger. It's like a string which you can add attribute to it and those attributes can be things like font or font size or color. So that lets you draw a string that has multiple different fonts in it or maybe varies in size or color in other ways.

That's one one of the ways that we're trying to avoid some of the deprecated QuickDraw facility in previously versions of the OS because previously in order to customize the appearance of a font or of a text string you'd have to set the port font for the current QuickDraw port and then use K theme current port font when you are calling into the Appearance Manager. Since that's all deprecated at this point, using CS attributed strings you don't even have to do anything with QuickDraw there.

The other way in which we're avoiding the old QuickDraw path is explicit for explicit support for the Core Text font identifiers. And Core Text is another new technology in Leopard that's kind of the lowest level text drawing system, it's now used by both HI theme draw text box and a considerable part of the Cocoa text system.

And it has a data type called CT font ref which identifies a font and various of its attributes. And you can now pass in the CT font ref to HI theme draw text box or to the text measuring routines by setting the K the theme font to K theme specified font and setting the font field of the HI theme text info structure to your CT font ref and you also have to update the version field of the HI theme text info to the value one instead of zero to indicate that your now using the font field.

Finally HI theme get UI font type is a new API if you are using both Appearance Manager theme fonts like K theme system font for example, but you also want to do... you also want to take advantage of the Core Text API and do some drawing just with Core Text and you want to be able to map between those two.

HI theme get UI font type takes an appearance manager font identifier and gives you back to correspondingCore Text font identifier so you can figure out what kind of font you going to be drawing with Core Text. And finally NS images. This is another case where we're attempting to use Cocoa facilities in your Carbon application. NS images is a pretty powerful class in AppKit that encapsulates multiple different resolutions of an image and lets you do various transformations on an image.

So we have some ways for you to do that more easily inside your Carbon application now. HIView draw NS image is a lot like HIView draw CG image. You just pass it in NS image and a CG context usually you'd use this inside your K event draw handler. And it takes care of orientating the context properly in drawing the image into the context.

You can also associate an NS image directly with any of the standard views that take image content so HI image view for example or a bevel button or a push button or quite a few others I think. You can now pass in an HIView content info structure when you're setting image content for those views that contains an NS image. And the view will take care of calling HIView draw NS image for you, do everything automatically.

So this is kind of the path that we're advocating that you take if you have your own image content in your application and you want to move towards a more resolution independent user interface. You can create NS images that contain multi multiple representations at different resolutions of your same image content and the proper one will be drawn according to the current scaling factor of the user interface.

So that's about it for today. Some of the overview of what we're talking about today. You can start to adopt the Leopard user interface changes; it's quite easy and in most cases automatic if you're using the standard controls the standard windows. But if it's not completely automatic for your application and there are a few simple changes you can make to adopt that, but in general the direction that we're strongly advising that you go.

You know we've been saying this last year as well and we're certainly it this year is to look towards Cocoa as the future. Burtron (assumed spelling) told us all on Monday Carbon is not going to be significantly enhanced in the future it's effectively moving to a deprecated state at this point.

And Apple's energies, all it's API are being developed and looking towards Cocoa. And so that's definitely the direction that you should be looking as well. For some more info we have Deric Horn down here who'll be coming up in a moment. He is the application frameworks evangelist for both Carbon and Cocoa and the web site has some sample code and other documentation. And just after the session as soon as we get out of here we'll all be heading to the labs downstairs for the HIToolbox lab. So if you miss us now, you can bring your questions there and my voice will get even worse.