Transcript
>> Peter Ammon: Welcome to Key
Equivalent Handling in Cocoa Applications.
My name is Peter Ammon.
I'm an engineer in the Cocoa Frameworks team.
Before we begin, I must confess that the
title of the session is a little incomplete.
The first half will indeed be about key equivalents
in Cocoa applications, but in the second half we will bring
out my colleague Raleigh who will show
you how to create custom views and menus.
For example, the finder label view or also entirely
simulated menus like the suggestions popup in Safari.
So you don't want to miss that.
So, we're going to cover the basics of key equivalent
handling, what are key equivalents, how do you set one.
We'll go over the keyboard event flow.
So, when the user actually types the
key event, what methods get invoked
and how can your application involve itself with that.
We'll talk about handling key equivalents
from other applications so you can respond
to events when you aren't even the front most app.
We'll go over to conflict handling.
What happens when two menu items
claim the same key equivalent?
Which one wins?
We'll go over how to debug these conflicts
when they occur and then I'll bring up Raleigh
for the custom menu items and simulated menus.
So, key equivalent basics.
Well, key equivalents are there to accelerate access to
commonly used menu items and buttons via the keyboard.
So here we see the Save button which has a key
equivalent of return which is why it's showing blue
and we have the New menu item which has
a key equivalent of command-N of course.
And it's the same API on NSButton and NSMenuItem
but most key equivalents are on menu items.
Now, programmatically, we refer to the N
that you see there as the key equivalent
and you can set that with the setKeyEquivalent method.
Now, notice that the N we pass is lower case even
though it draws as uppercase in the menu item.
This is important.
It will draw uppercase even though
you pass a lowercase string.
If you pass an uppercase string
it would in fact interpret it
as if you were requesting shift
that's part of the modifier mask.
So you want to stick to lowercase
characters unless you want the Shift key.
Now the command key you see next
to it is part of the modifier mask.
Of course, there are four different
modifier flags that are available.
There is command, option, control and shift.
You can also pass nothing at all.
It's perfectly valid to have the key
equivalent with no modifier mask.
You may be wondering about the Function key.
A lot of keyboards have that but
in fact that is not supported.
The reason for that is that not all keyboards have that.
So those key equivalents will be unavailable to those users.
And again, to set the key equivalent modifier mask,
of course you call setKeyEquivalentModifierMask
and you pass a bitmask of the modifier
flags that you would also get from NSEvent
and this is the same on NSButton as it is on menu item.
Now, you can set this programmatically but most of
the time of course you set them in Interface Builder.
Here the new menu item is selected and down
at the lower left you can see the portion
of the inspector where you can set the key equivalent.
So which item should get key equivalents?
Well, you want to assign them to frequently use command
and in fact the HIG lists a lot of key equivalents
that have standard established meanings and I mean a lot.
There's a lot there.
It's very comprehensive.
You want to try to avoid repurposing the standard or
reserved key equivalents because users expect them
to behave consistently across applications.
Now, a very powerful technique for enabling
power users is to use an alternate menu item.
This is for example Close All.
The Close All appears when you press the
Option key, that's why it's called alternate
and this doesn't clutter up the user interface.
But because these items aren't very
discoverable you have to know what to press.
You always want to provide another
way to accomplish the task.
For the example of Close All, you can of
course just close each window individually.
Now, it's worth noting that the key equivalent
you set may not be the one that appears.
The one reason for that is what's
called the user key equivalents.
These are things that user can
set in the system preferences.
So here the user setting command-Option-C, I'm
sorry command-Shift-C as close for the text data.
It's called the user key equivalent and you can access
it with the user key equivalent method on the menu item.
So we actually expose when these occurs and you can
get what the currently selected user key equivalent is.
So those are just the basics.
What happens when the user actually types an event?
Well, event handling always starts
in NSApplication sendEvent.
That is the earliest point at which you can catch
an event and it's worth nothing in this diagram
that I'll show you every orange box represents
a point in which your application can override.
It's an override point that you can
involve yourself in event handling.
And the first thing sendEvent will do is
invoke what are called local event monitors.
So here's an event and local event monitors,
they can just pass the event on through.
They can handle it or they can return
in an entirely different event.
So in this case the event goes in and it comes out and
you can see it's totally different, different color.
So let's say that the local event
monitor does not ignore the event.
It returns it so it can continue being processed.
Now, the next step whether the event contains command or
control is an important fact in how the event is dispatched.
If it contains command or control, it's going
to treat it like a key equivalent first.
So it's going to call performKeyEquivalent on the keyWindow.
So before it even reaches the main
menu, it will start on the keyWindow.
And the default behavior performKeyEquivalent is to call
performKeyEquivalent on all the views and this is recursive.
So if you wanted to do a custom key equivalent on
a view you could override performKeyEquivalent.
Now assuming none of the key-- the event
is not handled by performKeyEquivalent.
It will also try other active windows.
What do I mean by an active window?
I mean a window such as a drawer attached to
the keyWindow, or a sheet, or the main window.
It's different than the keyWindow.
But in this case, it only sends-- calls
performKeyEquivalent on views that manage menus.
That's specifically our popup buttons
and segmented controls that have menus.
So for example, a popup button in the main window can handle
key equivalents and this is recursive in the same way.
Now, performKeyEquivalent returns YES, that's a way
of indicating that the view handled the key equivalent
and if it returns NO, it indicates it
doesn't and the recursion should continue.
So let's say that keyWindow didn't handle the key
event and neither did any other active windows.
Finally, we reach the main menu performKeyEquivalent
is called and normally through dynamic key equivalents
in the main menu, you want to implement delegate methods.
A very tempting looking delegate method is menu
has key equivalent for event target action.
This allows you to return to YES that does have a key
equivalent and NO that doesn't and this looks tempting
but in fact this is a problematic
method for a couple of reasons.
One of them is that if you just dynamically
say YES, it had it or NO, it didn't have it.
We don't know what to draw in the menu item
and it doesn't get called if the menu was open.
So if the user opens the menu and then types a
key equivalent, this method will not get called.
And lastly, it doesn't work by
default with user key equivalent.
You have to go to heroics to make user key
equivalents work with this type of delegate method.
But it has one good use and that's just to press
expensive population for menus without key equivalents.
So for example, the open reasons menu
has a heap of disk to be populated.
You don't want to do that every time the user presses
a key so you might implement this delegate method
to just return NO which is a way of
saying don't even bother populating me
for key equivalent searching because
I promise I don't have any.
Now, a better method to implement is menu needs update.
This is called not just for key equivalent handling
but also when the menu is opened when it searched
for accessibility, when it searched spotlight for help.
So it's called in a number of places and your delegate
method should populate the menu with the menu items that--
and their key equivalents and then the frameworks
will actually take responsibility for determining
which items match the key equivalent if any.
So the owners lift it off your application
for determining which key equivalents match.
So, so far we've been assuming the event had
command or control in this modifier mask.
What if it didn't have those?
Or what if performKeyEquivalent returned NO?
So it not recognizes a key equivalent.
So we're going to take off the command key.
Well this is where-- the next step is
that app command hot keys are handled.
So these are keys like command-tilde
for windows cycling or there are keys
for moving a focus in the menu bar or for the toolbar.
Now, other hot keys that you might register for with
register hot key don't actually get invoked via this path.
In that case the event is never ever
sent to the front most application.
It's sent only to the app that registered the hot key.
But for this sort of app command hot keys,
these do get sent to the app at this point.
And finally, we reach sendEvent on the keyWindow.
And the keyWindow is going to call keyDown on
the first responder, for example a text view.
And the default behavior is to call
keyDown up that responder chain
until we reach the window itself NSWindow keyDown.
And at this point the default behavior
is to call performKeyEquivalent.
Now, if this is an event without command or control this
is the first time performKeyEquivalent has been called.
If it did have command or control,
this is in fact the second time.
But most of the time it wouldn't get that far.
And if the performKeyEquivalent on
the keyWindow did not return NO,
then it will call performKeyEquivalent on the main menu.
So again, this might be the first or second time that
performKeyEquivalent is called depending on the event.
And the very last thing it does is it
will beep and then the event is destroyed.
So this is the very fallback behavior.
So, that's a lot to take in I know but
these are the things to keep in mind.
Windows get first crack a key
equivalent before the main menu.
Now if the event has command or control
it's treated like a key equivalent first,
performKeyEquivalent is called before sendEvent.
Other events performKeyEquivalent is called after sendEvent.
So, the best practices to do dynamic key equivalent.
If you want to apply them to a menu
you would implement menu needs update
to just install the menu items with the key equivalents.
If it's on view you would override performKeyEquivalent.
Now, if you want to do your special work
before normal key equivalent handling,
you can override NSApplication sendEvent, NSWindow
sendEvent and NSWindow performKeyEquivalent
or you can call and install a local event monitor.
If you want to do your special processing after all
the other work is done, you can override keyDown
on NSWindow and you call through the super.
So that's how you handle key event
within your own application.
How do you handle them from other applications?
Well, a very powerful and polite
way to do this is to use a service.
We see here's a bit of the services
declaration from Stickies.
Notice that Declare is a key equivalent of Y and because
it's uppercase it will actually be command-Shift-Y.
This is very powerful because your
app doesn't even have to be running.
The frameworks will launch your application for you
and users can customize this in System Preferences.
It's polite because if the front most application also uses
the key equivalent that you want, the application will win.
So you won't interfere with the front most app.
And you can also interact with the text selection.
Stickies will create a new sticky
with whatever text is selected.
And to do this of course you specify the NSKeyEquivalent
key in the service declaration like we see here
and I recommend seeing my talk from last
year about services for more information.
Now, another very powerful approach is the use
of hot key and your application has be running
to use a hot key and hot key always take precedence.
So it's very possible to register for a hot key
for the letter N and then anytime the user types N
in any application that will get sent to your app instead of
the front most app because that will be a rude thing to do.
This requires a virtual key code so you can't just pass
the string and you have to pass a virtual key code.
You can find many of these in the Events.h header
in HIToolbox framework or another technique is
to actually ask the user type the key event you want to be
the hot key and then you can pull out the virtual key code
from the NSEvent with the key code method.
Now, to install a hot key you use
the RegisterEventHotKey function.
This is a carbon function but unlike many carbon
function this one is available in 64-bit which is nice.
The third option is to use a global event monitor.
This is sort of the analog to local event monitors.
They asynchronously respond to
event and they don't block events.
So a hot key will actually swallow the event whereas the
global event monitors will just allow you to observe them.
To do this you use addGlobalMonitorForEventsMatchingMask
at handler and handler is a block that you pass
when you want your-- to be invoked
when the right event is dispatched.
So on to conflict handling.
Most key equivalents are always visible, right.
Close just shows command-W all the time and some of them can
be revealed such as Close All when you press the option key.
And some of them are just sort of power user secrets like
you can hit Escape to close the dialog with a Cancel button.
Now, when the key equivalents are visible, it's
really important that what you see is what you get.
What do I mean?
Well, imagine an app location like this with
delete and duplicate both showing command-D,
user types command-D hoping to
duplicate instead it deleted something.
That's bad.
This might seem like a very contrive example but
if the menu items are in very different menus,
maybe ones that are popup, who knows, it could be confusing.
So when two menu items claim the same key equivalent
NSMenu will actually mediate between them to determine
which one wins and the other menu item
will not show that key equivalent.
And you may think, you know, I designed my app.
I pick all the key equivalents.
I know there are no conflicts but as we've seen,
key equivalents can come from other places.
They can come from the service.
They can come from something the user
requested as a user key equivalent.
Your application has plug-ins.
They can come from there.
Input managers and any future menu items
added by added by AppKit such as Close All.
Now, the first come first serve meaning the first menu item
that requests the key equivalent will get it
except that user key equivalent always win.
We respect the users' wishes and services
always lose because it's very polite.
And a surprising fact is that the key equivalent method
actually returns to currently applicable key equivalent.
So if I call a setKeyEquivalent when I pass N
and then I call key equivalent to get it back
and I get back the empty string that's a good hint that
some other menu item has claimed that key equivalent.
Now the NI pass isn't lost.
It just sort of dormant in the menu item and when the winner
goes out of the menu or it changes its key equivalent,
my item will, its N will become prominent and then
it will return it from the key equivalent method.
So I'll give you a demo of the conflict handling.
So here I have a simple application which shows some files.
I can get info on a particular file and I can edit it.
You'll notice that get info contains
command-I as the key equivalent.
Now, command I is also used for italics, right?
So in the Font menu you can see that Bold and Underline
have their normal key equivalent but italic does not.
This is because the get info item got to it first.
Now if I open this file, you'll notice
that get info loses its key equivalent.
Where did it go?
Well, if you remember that keyWindow get
to try key equivalents before the main menu
and in fact this keyWindow has a popup button
which has key equivalents in it and you can
that italics goes to that-- is in that popup button.
If I hit command-I, in fact, it
does do italic instead of get info.
And you also notice that the italics menu item also
has command-I which should be surprising because I said
that key equivalents can't be shared
so we'll talk about how that works.
And if I go back and make this the keyWindow, get info
recovers those key equivalents and italic loses it.
So the winner can be determined very dynamically.
So as we saw with italic, sometimes it's OK
if two menu items share a key equivalent.
It's OK when they sort of do the same thing.
In that case there's no confusion if they both show it.
To indicate to AppKit that it's okay if these
two menu items have the same key equivalent,
you can give them the same action.
They don't need the same target.
They just need the same action and that's true as
we saw even if one is in a popup and the other is
in the main menu, they can be widely separated.
So debugging.
Often as I said you'll set a key
equivalent and then it doesn't show up.
You know, where did it go?
Well, another menu item has it but where?
How do you find out?
Well, this is an important enough question
that will share a bit of NSMenus internals.
Here it is.
You can actually access the uniqueing properties, the main
menu uniquer and print out its content to figure out, OK,
which menu items have which key equivalents registered?
This is of course for debugging only because, you
know, absolutely this is going to change in the future.
Hopefully, it will become easier.
But for now this is a powerful way to solve this problem.
I'll give you a demo of that.
So I've launched this application in GDB over here.
I'm going to pause it and I'll call what I said
NSMenuKUniquer MinMenuUniquer print contents
and it outputs a lot of information and we're
looking for italics so let's search for italic.
There it is and you can see that italic is registered for
command-I but so is get info and get info is ahead of it
which shows you that get info is the winner and that's
why get info has the keyEquivalent and italics does not.
That's a powerful way to debug conflicts.
So that is the end of the key equivalent
portion of this session.
I'm going to hand the podium over to my coworker Raleigh
who will talk about how to create custom menu items
like finders label view and how to simulate
menus when you need the ultimate and flexibility.
[ Applause ]
>> Raleigh Ledet: Thank you Peter.
My name is Raleigh Ledet.
I'm a coworker with Peter on the Coca Frameworks.
So custom menus and simulating menus,
we're kind of switching gears here.
So let me give you a couple of examples of the
things that we do in OS X today and I'm going
to show you how to implement those things yourself.
This is the menu from the finder.
Hopefully, you're familiar with it.
In this particular portion is you could set
the label color that you want for your files.
This isn't just a text.
This isn't just some text in the menu.
You can actually select little code boxes and they've
done this by putting in a custom view inside the menu
and we'll go ahead and show you how to do that yourself.
Sometimes though menus aren't quite what
you need and so for our example here
when you start typing a location it
puts up a custom list of suggestions.
The problem with having this in a menu is that focus is
actually still on the text field and the menu wants to focus
for itself and so that won't work
and you can't put up a menu.
So you actually have to simulate a menu.
So I'm going to show you how to do that as well.
So we have some sample code.
Hopefully, you've already downloaded it.
If not, you can find it there and we'll give
you a quick tour of what the sample code does.
So right over here we have a custom menu items and you see
it has a normal regular menu item here and we can track
around and these are just pulling images from the
desktop images and we can also search for them here.
Just type L and we see a list of suggestions and we can
choose a suggestion or we can change that and here's all
of the L items and maybe we want the ladybug instead.
So this is the sample code and will
show you how to do both of those items.
So first let's talk about custom menu items.
Whenever you can it's preferable that you actually
create a custom view and put that in a menu
when what you really want is true menu behavior.
This is the most appropriate way to do it and
the most future proof way of accomplishing that.
And so this is our analog to what
we've been doing in the finder.
It's the exact same thing.
We've got a custom view with 4 images.
And so the first thing you need to do is you
need to create your custom view and set it
as the view that the menu item should use.
So Interface Builder then I went ahead in and
I created a custom view with four image wells.
I also put in four progress indicators so the
progress indicator will spin while we're waiting
for the thumbnails to be generated.
And then the other thing that you need to do which is really
important, you actually need to go in Interface Builder
and then Properties and set your class for your view
to some custom subclass that you're going to write.
You need to write a custom subclass that you can
handle the mouse events and the keyboard events.
Now that you have a custom view, how do you put
that custom view in to the actual menu item?
It's actually fairly easy in Interface Builder.
You can jot down your menu, pull off its properties
and then connect the view outlet right to the view.
Now when you run your application instead of item
two it will put your custom menu item in there.
You have custom view.
That's not what I actually went in the sample code
because I actually look at that source folder.
You said it was one menu item where you could
select the folder to be a source of images
and there are four images per menu item
so I dynamically add menu items as needed.
And so since I do this dynamically in code,
there's an API call on NSMenuItem called setView.
All you have to do is call menuItem
setView and you add your view
and now when the menu is displayed
your view will be shown there.
So now we got our view inside of menuItem.
It's coming up correctly.
Let's talk about mouse navigation.
Hopefully, you hear for the previous talk
that Troy gave and he talked some great--
some interesting hints about mouse navigation
and a lot of people go into tracking loop
so you override mouseDown, mouse drag, and mouseUp.
We don't want to do that in this case for this application.
Particularly, we don't want to do a tracking loop because
the user can track from your menu item to other menu items
and for that matter, the user might press the mouse button
down and keep it held down while we pop up the menu,
drag to the menu item they want to select and then let go.
So you might not ever get a mouseDown anyway.
Instead, we're going to go ahead
and use updateTrackingAreas.
We're going to create tracking areas
to do our mouse tracking and you do
that by overriding updateTrackingAreas in you custom view.
In this case we just loop through each one of our
image views and we're going to call an internal method
that we'll get to in a little bit called
trackingAreaForIndex and the key important thing
in the slide here is what you call self addTrackingArea.
So addTrackignArea is an API on NSView and that's how
you add your tracking areas once you've created them.
Here is the internal method inside discussed in subclass
called trackingAreaForIndex and we have to do a number
of things before we actually allocate our tracking
area and the first is that I create a dictionary
to hold the index that this tracking area is for.
In this index I've just used so I can correlate which
is the imageView that this index is associate with,
what's the spinner that this index is associated with,
and more importantly what's the URL that's associated
with this index which is actually what other
parts of the application are looking for.
So then we go ahead and we grab our view that's
associated with that index and we convert its bounds
to the coordinate system of our custom subview and then
we have to figure out what our tracking area options are.
As I mentioned earlier, the user can drag
through your menu item to other menu items.
So you want to get your entered and exited tracking
area events for both mouse moves and mouse drags.
So we add the NSTrackingEnabledDuringMouseDrag
to our options.
That way we'll get them in both cases.
We want both the mouseEntered and the mouseExited.
We want to see whenever you come over one of the image views
and whenever you leave it so we
update our selection properly.
And then the last option is NSTrackingActiveInActiveApp.
When the menu is up your app is active.
That works great and anything happens
that's going to require your apps
to lose activation, the menu is going to go away anyway.
So that's a nice little option to add on there as well.
Now that we have all of that figured out we can go
ahead and call NSTrackingArea alloc initWithRect,
the trackingRect that we in our local
coordinate system that we determined earlier.
The options that we figured up above, real important.
Make the owner sell so that your custom view
receives the mouseEntered and mouseExited events.
And then that dictionary that we created at the beginning as
the user info and this will allow us to associate the view,
the spinner and the URL that's all
associated with this tracking area.
So now we have our tracking areas
implemented and they're in place
and they automatically get updated whenever
the system thinks that they need to be updated.
We can go ahead and implement our mouseEntered responder
method and so you could just call a user data right off
of event and this will be that user info
dictionary that we added to the tracking area,
grab our index value out of there and just
set our property selected index to that index.
I'm not going to show you the code for it
but in the implementation I've actually created a custom
set selected index set of method for this property.
And in that set of method I make sure that whenever
the index changes that I call self set needs display.
In that way, at any time for whatever
means that the index changes,
we know that we need to redraw with the proper selection.
Then we implement the mouseExited responder method.
We don't need to look at the user dictionary
in this case because the user is gone
out of our tracking area so at
this point we have kNoSelection.
We'll receive a mouseEntered if the user moves with the
curser into another image view inside this menu item.
So we can rely on that and just return those
selections here, set our selected index to kNoSelection.
Now we're not implementing mouseDown and mouseDrag
but it is important that we implement mouseUp.
When you get a mouseUp event in your custom view,
you'll only get that when the user has
actually released the mouseOver your menu item,
your custom view for the menu item.
If it's any other menu item you won't get the mouseUp.
So now that a mouseUp has occurred in your
menu item, we obviously want to go ahead
and send the action that's associated with that
and here's what we're doing, we send the action.
There is a method on NSView called enclosing menu item.
If you're associated with the menu
item and of course in this case we are,
it will return to you the menu
item that you're associated with.
And in this case I would call NSApp sendAction and actually
get the action and the target that's already associated
with the menu item that was wired up in Interface
Builder so I didn't have to do any additional work here.
I could just wire it up in Interface Builder.
Now, that we've actually sent the action we need to go ahead
and cancelTracking for the menu so that the menu dismisses.
And for menu item we can ask for its
parent menu, the menu it's associated with
and then just call cancelTracking on that menu.
That's all you really need to do for mouse navigation.
Very pretty, it's very simple but now we also need to handle
keyboard navigation because of course the user can navigate
with the keyboard as well and I'll
give you a quick demo of that.
So here we have the custom menu application so I'm going
to like move the mouse way over here so not using it.
Everything is going to be keyboard driven now.
OK. [Whispering] There we go.
Mouse is out the way and so of course I can
navigate with the keyboard, move around,
I can jump to the beginning and to the end.
You hit the Space for return and the item is selected and
of course you can just hit Escape and dismiss the menu.
There we go.
So let's see how we handle that in code.
So if you're here for the last talk, then you already
know that you're not going to receive any keyboard events
until you override acceptsFirstResponder return YES.
By default NSView returns NO.
So, we need to become first responder.
Once you've informed Cocoa that you
do in fact acceptsFirstResponder,
you will at some point be asked to become first responder.
There are 2 cases that you might become first responder.
The users are navigated into the view of
the keyboard or perhaps the user clicked
onto your custom view inside the menu item.
If it's a user click, then we've already set
the selection based on the tracking areas.
So if there is a selection, we don't want to overwrite that.
But if the user arrowed in to the menu item view of
the keyboard then we don't currently have a selection
but we want to set the selection
to something so that the user sees
that that is the item that they're
manipulating at the moment.
So, in this case, we just our selected index to 0.
If you want to get really fancy, you might remember the last
selection that was there on the menu item so when they move
to it, you move to the last remembered one.
Since you've become the first responder,
at some point you're going to be asked
to resign first responder generally moving off with
the keyboard or perhaps the menu is getting dismissed.
If the menu is getting dismissed and your
item was the one that was activated, we've--
at this point we have already set the action so setting
the selected index to kNoSelection doesn't do anything.
But if you-- if we're resigning first responder
because of keyboard movement then it's important
that we set our selected index to kNoSelection
so that the user doesn't get two highlighted
items inside the menu and get confused.
Finally, we can get a keyDown message and we're going to
do the typical Cocoa thing of just call interpretKeyEvents.
This will key bindings to kick in and look at the key
event and figure out what is the user's intention.
And what's really important in this example which is
kind of unique is that after we call interpretKeyEvents,
we still need to call super keyDown so that
eventually it will go up the responder chain
and then this menu can handle the
key events that we don't handle.
So, keyDown is just going to look at the event
and if it's the right arrow or the left arrow,
it's going to call moveRight, moveLeft in our view.
This is great so now you don't have to forget
what the key code is or the appropriate character
for the right arrow key and the left arrow key.
It's taken care of for you.
So, here we just move our selection right or left and
likewise, the user might do command-right or command-left
and that will be interpreted as move to beginning
of line so you can move your selection to the end
of the beginning in the sample code's case.
Then of course if the user hits the Return key or the
Enter key, we'll want to go ahead and send the action
if they've committed it so we can do send action and
we've already taken a look at that implementation.
But we also want to activate our menu whenever the user hits
the space bar and traditionally, key binding just thinks
of space as being part of texts
usually associated with the text field.
So, there's no user action associated with space.
So, when key binding doesn't find some action
associated with that, it will call insertText so,
we overwrite insertText and we look for the space string
that has to be inserted and if that's the case, again,
we want to go ahead and send the action
and commit that item and dismiss the menu.
The way key bindings actually works when you
call interpretKeyEvents is that once it figures
out what the command is, that it wasn't send for an action,
it calls doCommandBySelector on your view and by default,
this will find out-- the default implementation
will determine if your view responds to selector.
If it doesn't, we'll call that.
If not, it will route up the responder chain appropriately.
And if it goes all the way to the end of the responder chain
and nobody has responded to it, he will get the system B
and menus, whenever there's some invalid
keyboard movement, they don't beat.
So, we want to go ahead and just check for
the selectors that we've implemented above.
If it's one of those selectors, we'll go ahead and just
call up the super which will call back the correct method
but if it's not one of those methods,
we specifically don't want to call super
so that we eat the action right
here and we don't have a system B.
Now, you might be wondering well,
if we don't allow this to call
up the super then how can you navigate
up or down off of your menu item.
Or remember previously, when we implemented keyDown after
calling interpretKeyEvents, we called up the super keyDown
and that's why we're-- it's perfectly fine
to eat this here and not worry about it.
Now, we got menu navigation via the
keyboard and we can navigate via mouse.
You might want to throw some animations
in your custom menu item.
Now, you don't want your animations just
running wild while the menu isn't even showing.
That's a waste of resources but you
can override viewDidMoveToWindow.
The way this works is whenever we show a menu, we create
a new window and we add all the menu items in there.
If you have a custom view as your menu
item, that gets added to the window
and you'll-- we'll get a viewDidMoveToWindow call.
You could check your window property from self.window.
If you have a valid value, you can start your animations.
When the menu is dismissed, we deallocate the
window after we pulled out all of the menu items
and including removing your view from the window.
Your view is not going to be deallocated or released because
it's actually still being held onto by the menu item.
However, you'll get a viewDidMoveToWindow
and window will now be nil so you know
that you can stop any of your animations.
So that was creating custom menu items.
Real easy to do.
It's a recommended approach but
sometimes that's not quite good enough.
As our example here with our custom suggestions
example, we need something that acts a lot like a menu,
looks like a menu, but is not in full control
because we want the text to still be type--
go into the text field as the user types.
So, the first thing we need to do when we create-- when
we're going to create our suggestion in windows is we need
to create a borderless window, fairly easy to do.
In this case, we have a custom subclass of NSWindow
called suggestions window in the sample code
and we've created a subclass for two reasons.
First off because Interface Builder,
there's no checkbox or a series
of checkboxes you can click to get a borderless window.
If you have a subclass, you can set the
class in Interface Builder to your subclass
which will force a borderless window property.
But the main reason we did it in this sample code was
that we're doing a unique situation here that we need
to inform accessibility about and having a custom subclass
of NSWindow provides the appropriate places to hook
into that and we'll cover a little bit of that later.
In NSWindow, the designated initializer is
initWithContentRect styleMask backing defer.
So we're going to overwrite the designated initializer.
When we call up the super, we're always going to
send the NSBorderlessWindowMask as the styleMask.
So, regardless of what set in Interface Builder when this
gets called, we're going to create a borderless window
or if you call it programatically,
you'll get a borderless window.
That's great, we get this which isn't quite what we
want so we will add some depth by saying setHasShadow.
That's great but we want the nice kind of rounded corners
like a menu has and we do that with a custom view that's set
up as the content view for drawing so we just need to
tell the window that it has a clear background color.
But then we get these black tips.
We're getting our rounded drawing but
we're going to have these black tips.
And that's because the window server doesn't realize
that this window has some transparency in it.
It still thinks it's completely opaque.
So, we tell the window setOpaque:NO and at this point,
the window server does an appropriate compositing now
and we have a nice rounded cornered
window that looks a lot like a menu.
We're ready to add content.
The next thing we need to do now
that we have our window is we need
to make our suggestion window a
child window of the parent window.
This is really important.
Why it's important is best shown when things go wrong.
So, this is not actually in the sample code but
I've modified it to do some things wrong here.
So, here we have the suggestion window is up
and if I go ahead and do expose nice and slowly,
we see that our suggestion window kind of
disappeared and that's not what we want.
And I was playing around with the window level there.
Maybe we would change the window level to
something else and we get this one we expose.
Well, now this is definitely not what we want.
What is the user really going to be
clicking on here, we don't want it.
We definitely don't want that.
So, we'll go ahead and make it a child
window and we'll make it a child window.
You'll see that a suggestion window
in expose will stay with our window
and it plays nicely and scales with the expose scaling.
And if you would have tried this with the suggestions list
up in Safari, this is the exact same behavior that occurs.
So, that's the best we have.
And now, what happened there?
This is what happens if you aren't careful on how you
deconstruct your child window whenever you go to dismiss it.
I'll show you that again.
Now a child window and it's doing
the right thing, great, but if--
when I click anywhere, this is going to dismiss
this menu, the whole window went away and if we look
at the real example that you have in the code,
as you've seen earlier, and this window is up.
I can click here and it dismisses properly.
So, I'll show you how to avoid that mistake as well.
So as I've said you need to add at your suggestion
window the child window of the parent window.
parentWindow addChildWindow:suggestionWindow
ordered:NSWindowAbove.
This will bring the child window above
your parent window and be displayed.
Put in the appropriate place.
So, now you don't need to call order front on the window
and we obviously don't want to make it key so we don't want
to call it a front made key because the key
focus needs to remain in the text field.
And whenever the suggestion window is dismissed
and we do that in our cancelSuggestions method inside
SuggestionsWindowController.m in the sample code.
The trick is to remove your child window from
the parent before ordering out the child window,
and our child window here is our suggestions window.
If you order out a child window, it will
automatically order out its parent window
and that's what was going wrong in the demo.
So make sure you remove your parent-child
relationship then order out your child window.
When do we want to activate our suggestions window?
And how do we get that to work?
So, in Interface Builder, I went ahead and wired up the
text field to the CustomMenusApplication delegate class
and I set it as the delegate of the text field.
Then I went ahead and implemented
the NSTextFieldDelegate methods.
In this case, controlTextDidBeginEditing.
The user started typing something.
This seems like a wonderful place to go ahead
and start putting up a list of suggestions.
controlTextDidChange, we probably need to modify our
suggestions or maybe we no longer have suggestions.
We need to dismiss our suggestions window.
Or maybe for some reason it was dismissed and now we
do have suggestions so we need to make it reappear.
controlTextDidEndEditing, we'll implement
that one and dismiss our suggestions window
because the user's either committed whatever they had typed
or some other means canceled that
or perhaps key focus changed.
So, we'll need to go ahead and
dismiss our suggestions window.
And then last but not the least,
control:textView:doCommandBySelector.
If you remember earlier in our custom menu section of
the talk, interpretKeyEvents calls doCommandBySelector
and this is what's actually going on in the text field.
In the text field then, we'll go ahead and forward that on
to its delegate via this
control:textView:doCommandBySelector.
And the main reason we want to implement
this is to search for the complete action.
AppKit has an autocompletion mechanism built in
whenever you're typing and we need to suppress
that 'cause we don't want the autocompletion popping up
on top of our suggestions, our custom suggestions window.
And it's also great place if we can catch this,
suppress the autocompletion from AppKit but use this
to toggle the behavior that the user would expect.
So, when the users hit escape to do autocompletion
we can go ahead and jot down our list of suggestions
and when the users hit escape and our list of suggestions
is already up, we can go ahead and dismiss that.
Now, since we're simulating a menu, there are times
when we need to go ahead and watch for the mouse
and various other actions that go through the system
and automatically dismiss our suggestions window.
So, let's take a look at some of those cases.
So, here we have a suggestions window up and perhaps
the user clicks into the desktop or another application.
Obviously, we want our suggestions window to go away.
You've already seen how the user can click
in the parent window and it goes away.
Here's an interesting trick.
If I would have clicked on the menu here, the menu
doesn't pop up because we don't want the menu to pop up.
If I click again, the menu is going to go ahead and display.
Or perhaps the user wasn't mousing at all and
they did command-tab and switch that way of--
so, there we want our suggestions
window to go away there as well.
They hit did command-tilde to switch menus--
to switch windows inside your application.
So, we need to go ahead and catch all those cases
but there's one other interesting little case
which is perhaps the user clicks in this text field.
We still want that to work because we want to
allow the user to be able to modify their selection
so they can then go ahead and perhaps type
an A instead and see the ladybug in lavender.
Just go ahead and select the Menu button.
Peter has already talked earlier in the talk about
localEventMonitors and when they are processed
and this is a great place for us to use it.
It's a new-- event monitors are new in Snow Leopard.
So, whenever we go to the show our suggestions window,
we'll go ahead and add a localEventMonitor and this is great
because now we don't have to subclass
NSApplication or NSWindow.
So, we'll addLocalEventMonitorForEventsMatchingMask
and we're interested in any of the mouseDowns
with just the right mouse button, the primary
mouse button or the any other mouse button.
And riding along we can go ahead and add our
code to how to respond to that type of situation.
First thing we're going to do for our mousedown event is
we're going to find out what window did this event occur in.
Did it occur in our suggestions window?
When it occurred in the suggestion window, we
want to go ahead and allow the click to process
through and allow that to act as an action.
So, we don't want to do anything.
If it's not the suggestion window
then perhaps it's our parent window.
Well, if it's not our parent window,
this is a LocalEventMonitor so it has
to be some click that's associated with our application.
If it's not our parent window, it must be
some other window inside of our application.
So, we'll go ahead and cancel our suggestions window.
If it is in the parent window, then
we have a little bit more work to do.
You got a whole bunch of code here and the whole point of
this code is basically to find out did the user click here.
The user clicked in the text field, we want to go ahead and
allow that click to go through and be processed normally
so that user can move the selection, change
the selection or just move the carat.
All of this work is just basically doing normal hit testing
but the real key here is that whenever the user is typing
in the text field, we actually place the field editor
there and so hit testing will actually hit test
to the field editor and not the text field.
So, we need to check the hit tested view here if it's
the text field or if it's the field editor associated
with that text field that we want to
let the event process do normally.
If it's anywhere else in our parent window,
we'll go ahead and make event equal nil.
This is the event that was passed
into us in the beginning of our block.
We're going to return to that in
a moment and you'll see that.
And this will effectively eat the event.
So, Cocoa will no longer run this event because we
can modify the event here and the event is eaten
but we'll go ahead and cancel our suggestions
window which will dismiss the window
and this is how we accomplish the user clicking
on the popup button dismissing the suggestions
but not having the popup button pop up.
At the end of a block here for
completeness, you can see how we return event.
And in this case, we will either always return the event,
the mouseDown event as it was passed to us or we're going
to return nil and effectively eat the event.
So, we set up our localEventMonitor
whenever we showed our suggestions window.
Likewise, we need to remove our event monitor
whenever we dismiss our suggestions window.
So, event monitors are automatically retained and the
memory management is automatically already done for you.
So, when we add our localEventMonitor, we didn't need to
call retain on it but we did need to hang on to the observer
so that we can call NSEvent removeMonitor
and we could pass in that observer.
Since we didn't retain it, we don't need to release
it but we're going to go ahead and make sure
that we set our local number variable to nil because
we don't want to hold on to an invalid object.
So, that handles a lot of the mouse cases but the user
can navigate with the keyboard or perhaps something else
like an alert pops up and we want to handle that case.
And that can all be done by listening for the
NSWindowDidResignKeyNotification on the parent window.
So, this will handle all the other cases
that we need to worry about and you'll see
that I'm using here the new the 10.6
notification method addObserverForName.
That way, this allows me to put right in line
the behavior that I want associated with that
which is simply to dismiss our suggestions window.
So, we go ahead and we install the notification
for NSWindowDidResignKeyNotification
whenever we show our suggestions window,
and likewise whenever we dismiss our suggestions window,
we need to go ahead and remove that observer as well
and just like the localEventMonitors, you don't-- the
observer that's returned to, you don't need to retain it.
The memory is handled for you but you do need to go ahead
and remove the observer or else it's hanging around forever.
And likewise, once you've removed the
observer, we need to set our local ivar to nil.
Otherwise, we're hanging on to a potentially invalid object.
So, that's great.
So, we got our suggestions window showing up.
It's playing around nicely with the
keyboard and the mouse and autocancelling.
But how do we get to play nicely with the
keyboard and the mouse as far as tracking goes.
This turns out that it's very similar to what
we're doing in our custom menu item view case so,
I'm not going to go over that code here
because it's practically the same thing.
Please look at the sample code
for some of the monitor changes.
But I do want to touch a little bit on accessibility.
We're doing something a little bit unique here.
So, we have to inform accessibility of that.
Cocoa does a lot of things for us but what this
looks like to the user is that there's a list
of suggestions associated with the text field.
In reality, we have a child window
that's associated with the parent window.
And we need to inform accessibility of the
logical relationship that we have here.
Namely, that we have a list of suggestions
that of the child of some text field.
So in this suggestions window class in the sample
code, in the suggestion with text field cell
in the suggestions controller, whenever we show the
suggestions window we go ahead and build this relationship
and whenever we dismiss the suggestions window, we go ahead
and tear down this logical relationship for accessibility.
I'm not going to go over the code but real
quick in Interface Builder for that text field,
I went down and I gave it a custom cell class
which is the suggestible text field cell,
and this cell knows that it can potentially
have a child window associated with it
and that's how we handle this relationship.
And we have a whole bunch of items on here.
We need to report accessibility that this is an AX list
and we actually handle this in the rounded corners view
and set NSView subclass that draws the nice rounded
corners in our content for our suggestions window
but it will also report for us that we have--
that it contains a list of items to accessibility.
There's not a lot of code there.
It's in the sample code.
And then we need to report that the image, the main
label and the blue label are all part of the same group.
And we go ahead and we do that
in the highlight view subclass.
It's already had it there to handle the
highlighting that you see at the top
of the window as the selection is changed.
So, it's a great place to go ahead and report
accessibility that it contains a group that all
of its item should be considered part of a group.
From there, the label views will report the
appropriate things to accessibility and that's great.
But we still need to deal with this image.
For an accessibility user, this image is just an
opaque field unless we do a little bit of work.
And in 10.6 we added an API that
go ahead and allow you to do that.
You can call setAccessibilityDescription.
You can go ahead and put in a localized description there.
In this case, we'll go ahead and put the file
name since that's all that we know about it.
If it's images in your application,
call in setAccessibilityDescription,
we'll add a wealth of information for controls
and displaying the intent to your users.
That's real easy to do.
Particularly since we've also added that you can-- if
you're using named image whenever you create your images,
you can actually just create an accessibility image
descriptions that strings file and localizes file
and the accessibility description will be
localized from this file and just add it
to the image automatically and
then report it to accessibility.
There was a good talk about this in the Cocoa Tips
and Tricks so I recommend you check out that session.
So, we go ahead and look at our key equivalents.
They allow user to accelerate their use of your application.
So, we've looked at how they flow through the system.
We've looked at how the appropriate places for you
to implement overrides our implement delegate methods
to dynamically modify your key equivalents.
We've looked at how key equivalents in their conflicts
are mediated by NSMenu and how you can even debug that.
And then the last two items here, we've
looked at how to create a custom view
and put it in the menu, it's really simple to do.
It's fairly easy.
This is the recommended approach as we change
things in the operating system for the menu,
you'll get the new look and behavior appropriately.
But when that absolutely won't do and you have to
do it yourself, you can look at the sample code
to see how we go ahead and we simulate the menu
where appropriate and do all the appropriate things
in the autocancellation and attaching to the child
window and working correctly with the system.
For more information, you can see
our-- the frameworks evangelist
and there are a couple of links to our documentation.
Now forums are always a great place to get
some more information and ask questions.
The Cocoa Tips and Tricks session I referenced earlier.
There's a lot of great information there and went
to a little bit more detail on some of the topics
and the Crafting Custom Cocoa Views which
was the session right before this one.
Hopefully, you've seen that one and if you're watching
this on the video, you can go back and check that one out.
There's some good information there as
well that's related and a little bit more
in depth in some areas that we've covered here.