Class CPPopUpButton

CPObject
    extended byCPResponder
        extended byCPView
            extended byCPControl
                extended byCPButton
                    extended byCPPopUpButton

@implementation CPPopUpButton : CPButton

A CPPopUpButton contains a pop-up menu of items that a user can select from.


Method Summary
-(id)initWithCoder:(CPCoder)aCoder
          Initializes the pop-up button with data from the specified coder.
-(id)initWithFrame:(CGRect)aFrame
          Initializes the receiver for usage with the specified bounding rectangle.
-(id)initWithFrame:(CGRect)aFrame pullsDown:(BOOL)shouldPullDown
          Initializes the pop-up button to the specified size.
-(void)addItemWithTitle:(CPString)aTitle
          Adds a new menu item with the specified title.
-(void)addItemsWithTitles:(CPArray)titles
          Adds multiple new menu items with the titles specified in the provided array.
-(void)encodeWithCoder:(CPCoder)aCoder
          Encodes the data of the pop-up button into a coder.
-(int)indexOfItem:(CPMenuItem)aMenuItem
          Returns the index of the specified item or CPNotFound if the item is not in the list.
-(int)indexOfItemWithRepresentedObject:(id)anObject
          Returns the index of the item with the specified represented object or CPNotFound if a match does not exist.
-(int)indexOfItemWithTag:(int)aTag
          Returns the index of the item with the specified tag or CPNotFound if the item is not in the list.
-(int)indexOfItemWithTarget:(id)aTarget action:(SEL)anAction
          Returns the index of the item with the specified target and action.
-(int)indexOfItemWithTitle:(CPString)aTitle
          Returns the index of the item with the specified title or CPNotFound.
-(int)indexOfSelectedItem
          Returns the index of the selected item.
-(void)insertItemWithTitle:(CPString)aTitle atIndex:(int)anIndex
          Inserts a new item with the specified title and index location.
-(CPArray)itemArray
          Returns an array of the items in the menu.
-(CPMenuItem)itemAtIndex:(unsigned)anIndex
          Returns the item at the specified index or nil if the item does not exist.
-(CPString)itemTitleAtIndex:(unsigned)anIndex
          Returns the title of the item at the specified index or nil if no item exists.
-(CPArray)itemTitles
          Returns an array of all the menu item titles.
-(CPMenuItem)itemWithTitle:(CPString)aTitle
          Returns the menu item with the specified title.
-(CPMenuItem)lastItem
          Returns the last menu item.
-(CPMenu)menu
          Returns the button's menu of items.
-(void)menuDidAddItem:(CPNotification)aNotification
          Called when the menu has a new item added to it.
-(void)menuDidChangeItem:(CPNotification)aNotification
          Called when a menu item has changed.
-(void)menuDidRemoveItem:(CPNotification)aNotification
          Called when an item was removed from the menu.
-(void)mouseDown:(CPEvent)anEvent
          Called when the user clicks on this button.
-(int)numberOfItems
          Returns a count of the number of items in the button's menu.
-(id)objectValue
          Returns the selected item's index.
-(CPRectEdge)preferredEdge
          Returns the button's edge where the pop-up menu will be displayed when there is not enough room to display directly above the button.
-(BOOL)pullsDown
          Returns YES if the button is a pull-down menu.
-(void)removeAllItems
          Removes all menu items from the pop-up button's menu.
-(void)removeItemAtIndex:(int)anIndex
          Removes the menu item at the specified index.
-(void)removeItemWithTitle:(CPString)aTitle
          Removes a menu item with the specified title from the button.
-(void)selectItem:(CPMenuItem)aMenuItem
          Selects the specified menu item.
-(void)selectItemAtIndex:(int)anIndex
          Selects the item at the specified index.
-(void)selectItemWithTag:(int)aTag
          Selects the menu item with the specified tag.
-(void)selectItemWithTitle:(CPString)aTitle
          Selects the item with the specified title.
-(CPMenuItem)selectedItem
          Returns the selected item or nil if no item is selected.
-(void)setBordered:(BOOL)shouldBeBordered
          Sets whether the button has a bezeled border.
-(void)setImage:(CPImage)anImage
          This method has no effect.
-(void)setMenu:(CPMenu)aMenu
          Sets the menu for the button.
-(void)setObjectValue:(id)aValue
          Sets the object for the selected item.
-(void)setPreferredEdge:(CPRectEdge)aRectEdge
          Sets the preffered edge of the button to display the pop-up when there is a limited amount of screen space.
-(void)setPullsDown:(BOOL)shouldPullDown
          Specifies whether the object is a pull-down or a pop-up menu.
-(void)setTitle:(CPString)aTitle
          Sets the pop-up button's title.
-(void)synchronizeTitleAndSelectedItem
          Makes sure the selected item and the item being displayed are one and the same.
-(CPString)titleOfSelectedItem
          Returns the title of the selected item or nil if no item is selected.

Methods inherited from class CPObject
initialize, alloc, class, instanceMethodForSelector, instancesRespondToSelector, isSubclassOfClass, load, new, setVersion, superclass, version, init, autorelease, awakeAfterUsingCoder, class, classForCoder, classForKeyedArchiver, className, copy, dealloc, description, doesNotRecognizeSelector, forwardInvocation, hash, isEqual, isKindOfClass, isMemberOfClass, isProxy, methodForSelector, methodSignatureForSelector, mutableCopy, performSelector, performSelector, performSelector, release, replacementObjectForArchiver, replacementObjectForCoder, replacementObjectForKeyedArchiver, respondsToSelector, retain, self, superclass

Methods inherited from class CPResponder
acceptsFirstResponder, becomeFirstResponder, deleteBackward, doCommandBySelector, insertLineBreak, insertText, interpretKeyEvents, keyDown, keyUp, menu, mouseDown, mouseDragged, mouseEntered, mouseExited, mouseMoved, mouseUp, nextResponder, noResponderFor, performKeyEquivalent, resignFirstResponder, scrollWheel, setMenu, setNextResponder, tryToPerform, undoManager

Methods inherited from class CPView
initWithFrame, acceptsFirstMouse, addSubview, addSubview, adjustScroll, alphaValue, autoresizesSubviews, autoresizingMask, autoscroll, backgroundColor, bounds, convertPoint, convertPoint, convertRect, convertRect, convertSize, convertSize, didAddSubview, display, displayIfNeeded, displayIfNeededInRect, displayRect, displayRectIgnoringOpacity, dragImage, dragView, drawRect, enclosingMenuItem, enclosingScrollView, enterFullScreenMode, exitFullScreenModeWithOptions, frame, hitTest, hitTests, isDescendantOf, isFlipped, isHidden, isHiddenOrHasHiddenAncestor, isInFullScreenMode, isOpaque, lockFocus, mouseDown, mouseDownCanMoveWindow, needsDisplay, postsBoundsChangedNotifications, postsFrameChangedNotifications, reflectScrolledClipView, registerForDraggedTypes, registeredDraggedTypes, removeFromSuperview, replaceSubview, resizeSubviewsWithOldSize, resizeWithOldSuperviewSize, scrollClipView, scrollPoint, scrollRectToVisible, scrollRect, setAlphaValue, setAutoresizesSubviews, setAutoresizingMask, setBackgroundColor, setBounds, setBoundsOrigin, setBoundsSize, setFrame, setFrameOrigin, setFrameSize, setHidden, setHitTests, setNeedsDisplay, setNeedsDisplayInRect, setPostsBoundsChangedNotifications, setPostsFrameChangedNotifications, subviews, superview, unlockFocus, unregisterDraggedTypes, viewDidMoveToSuperview, viewDidMoveToWindow, viewWillMoveToSuperview, viewWillMoveToWindow, visibleRect, willRemoveSubview, window

Methods inherited from class CPControl
initWithFrame, action, alignment, backgroundColorForName, floatValue, font, isEnabled, mouseUp, sendAction, setAction, setAlignment, setBackgroundColor, setBackgroundColorWithName, setBackgroundColor, setEnabled, setFloatValue, setFont, setTarget, setTextColor, setTextShadow, target, textColor, textShadow

Methods inherited from class CPButton
initWithFrame, allowsMixedState, alternateImage, bezelStyle, controlSize, highlight, image, imagePosition, imageScaling, isBordered, mouseDown, mouseDragged, mouseUp, setAlignment, setAllowsMixedState, setAlternateImage, setBezelStyle, setBordered, setButtonType, setControlSize, setFont, setFrameSize, setImage, setImagePosition, setImageScaling, setNextState, setState, setTag, setTextColor, setTitle, sizeToFit, state, tag, tile, title, viewDidMoveToWindow


Method Detail

initWithCoder

-(id)initWithCoder:(CPCoder)aCoder
Initializes the pop-up button with data from the specified coder.
Parameters:
aCoder - the coder from which to read the data
Returns:
the initialized pop-up button

initWithFrame

-(id)initWithFrame:(CGRect)aFrame
Initializes the receiver for usage with the specified bounding rectangle
Parameters:
aFrame
Returns:
the initialized view

initWithFrame

-(id)initWithFrame:(CGRect)aFrame pullsDown:(BOOL)shouldPullDown
Initializes the pop-up button to the specified size.
Parameters:
aFrame - the size for the button
shouldPullDown - YES makes this a pull-down menu, NO makes it a pop-up menu.
Returns:
the initialized pop-up button

addItemWithTitle

-(void)addItemWithTitle:(CPString)aTitle
Adds a new menu item with the specified title.
Parameters:
aTitle

addItemsWithTitles

-(void)addItemsWithTitles:(CPArray)titles
Adds multiple new menu items with the titles specified in the provided array.
Parameters:
titles - an arry of names for the new items

encodeWithCoder

-(void)encodeWithCoder:(CPCoder)aCoder
Encodes the data of the pop-up button into a coder
Parameters:
aCoder - the coder to which the data will be written

indexOfItem

-(int)indexOfItem:(CPMenuItem)aMenuItem
Returns the index of the specified item or CPNotFound if the item is not in the list.
Parameters:
aMenuItem - the item to obtain the index for

indexOfItemWithRepresentedObject

-(int)indexOfItemWithRepresentedObject:(id)anObject
Returns the index of the item with the specified represented object or CPNotFound if a match does not exist.
Parameters:
anObject - the item's represented object

indexOfItemWithTag

-(int)indexOfItemWithTag:(int)aTag
Returns the index of the item with the specified tag or CPNotFound if the item is not in the list.
Parameters:
aTag - the item's tag

indexOfItemWithTarget

-(int)indexOfItemWithTarget:(id)aTarget action:(SEL)anAction
Returns the index of the item with the specified target and action. Returns CPNotFound if the no such item is in the list.
Parameters:
aTarget - the item's target
anAction - the item's action

indexOfItemWithTitle

-(int)indexOfItemWithTitle:(CPString)aTitle
Returns the index of the item with the specified title or CPNotFound.
Parameters:
aTitle - the item's titel

indexOfSelectedItem

-(int)indexOfSelectedItem
Returns the index of the selected item. If no item is selected, it returns CPNotFound.

insertItemWithTitle

-(void)insertItemWithTitle:(CPString)aTitle atIndex:(int)anIndex
Inserts a new item with the specified title and index location.
Parameters:
aTitle - the new itme's title
anIndex - the item's index in the menu

itemArray

-(CPArray)itemArray
Returns an array of the items in the menu

itemAtIndex

-(CPMenuItem)itemAtIndex:(unsigned)anIndex
Returns the item at the specified index or nil if the item does not exist.
Parameters:
anIndex - the index of the item to obtain

itemTitleAtIndex

-(CPString)itemTitleAtIndex:(unsigned)anIndex
Returns the title of the item at the specified index or nil if no item exists.
Parameters:
anIndex - the index of the item

itemTitles

-(CPArray)itemTitles
Returns an array of all the menu item titles.

itemWithTitle

-(CPMenuItem)itemWithTitle:(CPString)aTitle
Returns the menu item with the specified title.
Parameters:
aTitle - the title of the desired menu item

lastItem

-(CPMenuItem)lastItem
Returns the last menu item

menu

-(CPMenu)menu
Returns the button's menu of items.

menuDidAddItem

-(void)menuDidAddItem:(CPNotification)aNotification
Called when the menu has a new item added to it.
Parameters:
aNotification - information about the event

menuDidChangeItem

-(void)menuDidChangeItem:(CPNotification)aNotification
Called when a menu item has changed.
Parameters:
aNotification - information about the event

menuDidRemoveItem

-(void)menuDidRemoveItem:(CPNotification)aNotification
Called when an item was removed from the menu.
Parameters:
aNotification - information about the event

mouseDown

-(void)mouseDown:(CPEvent)anEvent
Called when the user clicks on this button.
Parameters:
anEvent - the event with information about the click

numberOfItems

-(int)numberOfItems
Returns a count of the number of items in the button's menu.

objectValue

-(id)objectValue
Returns the selected item's index. If no item is selected, it returns CPNotFound.

preferredEdge

-(CPRectEdge)preferredEdge
Returns the button's edge where the pop-up menu will be displayed when there is not enough room to display directly above the button.

pullsDown

-(BOOL)pullsDown
Returns YES if the button is a pull-down menu. NO if the button is a pop-up menu.

removeAllItems

-(void)removeAllItems
Removes all menu items from the pop-up button's menu

removeItemAtIndex

-(void)removeItemAtIndex:(int)anIndex
Removes the menu item at the specified index
Parameters:
anIndex - the index of the item to remove

removeItemWithTitle

-(void)removeItemWithTitle:(CPString)aTitle
Removes a menu item with the specified title from the button.
Parameters:
aTitle - the title of the item to remove

selectItem

-(void)selectItem:(CPMenuItem)aMenuItem
Selects the specified menu item.
Parameters:
aMenuItem - the item to select

selectItemAtIndex

-(void)selectItemAtIndex:(int)anIndex
Selects the item at the specified index
Parameters:
anIndex - the index of the item to select

selectItemWithTag

-(void)selectItemWithTag:(int)aTag
Selects the menu item with the specified tag
Parameters:
aTag

selectItemWithTitle

-(void)selectItemWithTitle:(CPString)aTitle
Selects the item with the specified title
Parameters:
aTitle

selectedItem

-(CPMenuItem)selectedItem
Returns the selected item or nil if no item is selected.

setBordered

-(void)setBordered:(BOOL)shouldBeBordered
Sets whether the button has a bezeled border.
Parameters:
shouldBeBordered

setImage

-(void)setImage:(CPImage)anImage
This method has no effect. Because the image is taken from the currently selected item, this method serves no purpose.
Parameters:
anImage

setMenu

-(void)setMenu:(CPMenu)aMenu
Sets the menu for the button
Parameters:
aMenu

setObjectValue

-(void)setObjectValue:(id)aValue
Sets the object for the selected item. If no item is selected, then this method has no effect.
Parameters:
aValue

setPreferredEdge

-(void)setPreferredEdge:(CPRectEdge)aRectEdge
Sets the preffered edge of the button to display the pop-up when there is a limited amount of screen space. By default, the pop-up should draw on top of the button.
Parameters:
aRectEdge

setPullsDown

-(void)setPullsDown:(BOOL)shouldPullDown
Specifies whether the object is a pull-down or a pop-up menu.
Parameters:
shouldPullDown - YES makes the pop-up button a pull-down menu. NO makes it a pop-up menu.

setTitle

-(void)setTitle:(CPString)aTitle
Sets the pop-up button's title.
Parameters:
aTitle - the new title

synchronizeTitleAndSelectedItem

-(void)synchronizeTitleAndSelectedItem
Makes sure the selected item and the item being displayed are one and the same.

titleOfSelectedItem

-(CPString)titleOfSelectedItem
Returns the title of the selected item or nil if no item is selected.

Created on Sat Sep 13 14:15:43 PDT 2008