Re: HIObject Delegate

On May 22, 2008, at 10:37 PM, Eric Schlegel wrote:

On May 21, 2008, at 1:35 AM, Jack Small wrote:

I found this example code online: <http://developer.apple.com/samplecode/HIToolboxSOU-Delegates/listing1.html>

This was sample code from our HIToolbox State of the Union talk at WWDC a year or two ago (SOU == State Of the Union).

Oh I've been trying to block that out. My notes from that session aren't very nice. I have the word “Union” in big, big, big quotes. They just say HIObjectDelegate == Magic. I guess I was a bit distracted. I finally had time to get to it this week.

I'm wondering what exactly HIObject delegates are and how they should be used?

An HIObject delegate is an HIObject itself that can be attached to another HIObject. The API is declared in HIObject.h. The idea is to allow you to add easily behavior to an existing HIObject: when you add a delegate to an existing HIObject, any Carbon events sent to the existing HIObject are also sent to the delegate, if the delegate has Carbon event handlers for them installed on itself. You can do this already by installing Carbon event handlers on an existing HIObject, but delegates have a few advantages:

- you can install a delegate so that it's called _after_ all other handlers on the object. You can't do that with InstallEventHandler.
- you can install a delegate so that it's called before all other handlers on the object. This is the behavior of InstallEventHandler as well, but if someone else installs a handler after yours, then yours is no longer first in line. If you install a delegate in front of other handlers, it remains in front even if other handlers are installed on the object.
- a delegate incorporates both code (the event handlers installed on the delegate) and data (the instance data of the HIObject)

Data too! That's really cool. Since these APIs made the 64-bit cut it is definitely interesting territory to explore.

What is the 'com.apple.appobjects.HINumericTextFilter' HIObject, how does it work exactly?

It's an HIObject that uses the public kEventTextShouldChangeInRange Carbon event to run text input to an edit field through a Cocoa NSFormatter to determine if the text has a valid numeric format. If not, the input text is rejected. This particular delegate wasn't actually publicized for Leopard.

#define kHINumericTextFilterClassID CFSTR("com.apple.appobjects.HINumericTextFilter")

There we go. It was in the SOU after all.

Can I set a range or a format somehow?

No, it doesn't support those capabilities. I didn't have time to do everything I wanted to do with that delegate, which is why it's not public.

Understood. Even just a number filter is a huge and cool thing, though, for us simple Carbon folk.

And perhaps more important, are there any more like it?

There are other experimental delegate objects implemented in the Leopard HIToolbox, but the only one that's public and supported is the HITextLengthFilter delegate, which is documented in HITextLengthFilter.h.

D'oh! I guess I asked for it.

HITextLengthFilter doesn't seem to be 32-bit only. Ironic, really. Also handy.

I don't suppose there's a "type-select" delegate? Like the old old TypeSelect stuff? Oh just dreaming I'm sure.

Is there any way to get a list of all the HIObjects defined in a process?

No, I don't think we have a way to do that. (I assume you mean HIObject classes, not HIObjects themselves, since the latter would include every menu, every window, every HIView, etc.)

Yes just the names would do. Although, given a specific name, a list of all the instances might be very useful metadata, even if it is expensive.

You would know better than anyone, is generating the list of names easy enough to justify a new API? Just a little one? It would certainly be helpful, if only for debugging purposes. How many feature request reports would it take? :)

Also, while I'm at it, the MenuItemViews source mentions the 'ctit' initialization event parameter sets a controls title. This is very handy, and there are other control fields that would be nice to set during initialization via event parameters. Was this or any others ever actually documented with official symbol names?

Unfortunately they were not, and probably won't be at this point. However, if you are interested in specific event parameters I think we could describe them on this list; they're not likely to change at this point.

Yes I am interested. I'm sure you're all very busy getting ready and I couldn't do anything with them right now, but I can think of a few specific control parameters that would be useful to prefabricate in an EventRef. Visible, enabled, bounds, superview, min, max, value, resize, attributes, ideal size, HICommand, id, event handlers, etc. All I really need to know right now is if constructing the basics of controls this way will work, it would be nice option to have. I'll get back to you when I need to know the specifics!

Again, thank you for this clarification, it really does help. Maybe I'll add a little magic myself.

More later,

Jack

References:
	>HIObject Delegate (From: Jack Small <email@hidden>)
	>Re: HIObject Delegate (From: Eric Schlegel <email@hidden>)