Confusion with popUpMenuPositioningItem:atLocation:inView:

Question

The documentation for this method says: "Pops up the menu at the specified location." but the pamameters seem to describe a different situations:

item
The menu item to be positioned at the specified location in the view.

location
The location in the view coordinate system to display the menu item.

view
The view to display the menu item over.

The parameters seem to imply that you will only be popping up a MenuItem. What does this method actually do?

Answer 1

I don't know how you get that it might just pop up a menu item — there isn't even such a thing as a pop-up menu item. Nowhere in the parameter descriptions does it say it won't show a pop-up menu. The parameter descriptions all mention the item because they all relate to its positioning. It works as documented.

Answer 2

For convenience, you can set the coordinates of a single menu item. Your menu will be positioned accordingly around that single menu item.

You'll notice that this is how NSPopUpButton behaves: the selected menu item is always positioned directly overtop the button.

If you don't want your menu to behave like that, just pass in your top-most menu item.

Answer 3

You're forgetting something: This is a message you send to the menu object.

In English, the message is:

“Hey menu! Pop up yourself, positioning this item at this location relative to this view.”

The parameters describe where the whole pop-up menu should appear, in terms of positioning a specific item from the menu at a specific location. The whole menu appears as the pop-up, not just the positioning item. Popping up only a single item would be quite useless.

One other thing: This convenient method was introduced in Snow Leopard, so if you're targeting Leopard or earlier, you can't depend on it. You'll have to use another solution, such as the NSPopUpButtonCell I suggested in an answer on one of your earlier questions.