TUIButton and TUIControl documentation.

lib/UIKit/TUIButton.h

@@ -21,47 +21,114 @@
 @class TUIImageView;
 
 typedef enum {
-	// Does not respond to .tintColor.
+	// Creates a completely unstyled custom button.
+	// Does not respond to the tintColor property.
 	TUIButtonTypeCustom,
 
+	// Creates a rounded rectangle tintable button that
+	// has a drop shadow and a light beveling effect.
+	// The tintFactor property is used to determine
+	// the gradient colors: tintFactor is subtracted
+	// from tintColor to get the gradient's starting
+	// color, and added to get the ending color.
 	TUIButtonTypeStandard,
+
+	// Creates a rounded rectangle tintable button
+	// that has a light emboss effect with a flat color.
 	TUIButtonTypeFlat,
+
+	// Creates a rounded pill shaped button that has
+	// a light border with a light gradient color.
 	TUIButtonTypeMinimal,
 
-	// Does not respond to .tintColor.
-	// Overrides .selectable property as YES.
+	// Creates a specialized inline button that cannot
+	// be styled, but can be used to inline text as
+	// selectable. Overrides selectable property as YES.
 	TUIButtonTypeInline,
 } TUIButtonType;
 
+// An instance of the TUIButton class implements a button on the screen.
+// A button intercepts touch events and sends an action message to a
+// target object when clicked. Methods for setting the target and action
+// are inherited from TUIControl. This class provides methods for setting
+// the title, image, and other appearance properties of a button. By using
+// these accessors, you can specify a different appearance for each state.
 @interface TUIButton : TUIControl
 
+// Indicates the current button type. See TUIButtonType for the possible values.
 @property (nonatomic, assign, readonly) TUIButtonType buttonType;
 
+// Use this property to resize and reposition the effective drawing
+// rectangle for the button content. The content comprises the button 
+// image and button title. The default is TUIEdgeInsetsZero.
 @property (nonatomic, assign) TUIEdgeInsets contentEdgeInsets;
+
+// Use this property to resize and reposition the effective drawing
+// rectangle for the button title. The default value is UIEdgeInsetsZero.
+// The insets you specify are applied to the title rectangle after
+// that rectangle has been sized to fit the button’s text. Thus,
+// positive inset values may actually clip the title text.
 @property (nonatomic, assign) TUIEdgeInsets titleEdgeInsets;
+
+// Use this property to resize and reposition the effective drawing
+// rectangle for the button image. The default value is UIEdgeInsetsZero.
 @property (nonatomic, assign) TUIEdgeInsets imageEdgeInsets;
 
+// If YES, the button is drawn lighter when the window is not key. The default value is YES.
 @property (nonatomic, assign) BOOL dimsInBackground;
+
+// If YES, the image is drawn lighter when the button is highlighted. The default value is YES.
 @property (nonatomic, assign) BOOL adjustsImageWhenHighlighted;
+
+// If YES, the image is drawn darker when the button is disabled. The default value is YES.
 @property (nonatomic, assign) BOOL adjustsImageWhenDisabled;
+
+// If YES, the shadow changes from engrave to emboss appearance when highlighted. The default value is NO.
 @property (nonatomic, assign) BOOL reversesTitleShadowWhenHighlighted;
+
+// If YES, the button can be triggered into a stable selected state and back. The default is NO.
 @property (nonatomic, assign, getter = isSelectable) BOOL selectable;
 
 @property (nonatomic, strong, readonly) TUILabel *titleLabel;
 @property (nonatomic, strong, readonly) TUIImageView *imageView;
 
-// Setting this overrides .selectable property as YES.
+// Allows a pop up menu to be displayed if the button is pressed.
+// Setting this overrides selectable property as YES.
 @property (nonatomic, strong) NSMenu *menu;
-@property (nonatomic, strong) NSSound *sound;
 
+// The button tint color and factor. Depending on the button type, these
+// values may be used to tint the button into a different color. The factor
+// is used to determine the gradient difference between the start and
+// the end color, positioning the tintColor in the center.
 @property (nonatomic, strong) NSColor *tintColor;
 @property (nonatomic, assign) CGFloat tintFactor;
 
+// This method is a convenience constructor for creating button objects
+// with specific configurations. It you subclass TUIButton, this method
+// does not return an instance of your subclass. If you want to create
+// an instance of a specific subclass, you must alloc/init the button
+// directly or override this class method to return your button's newly
+// initialized object. You must always call the superclass implementation
+// if you are not returning a new button object. When creating a button
+// the frame of the button is set to CGRectZero initially. Before adding
+// the button to your interface, you should update the frame.
 + (instancetype)buttonWithType:(TUIButtonType)buttonType;
 
+// The default implementation of this method returns the value in the bounds
+// parameter. This rectangle represents the area in which the button draws
+// its standard background content. Subclasses that provide custom background
+// adornments can override this method and return a modified bounds rectangle
+// to prevent the button from drawing over any custom content.
 - (CGRect)backgroundRectForBounds:(CGRect)bounds;
+
+// The content rectangle is the area needed to display the image and title
+// including any padding and adjustments for alignment and other settings.
 - (CGRect)contentRectForBounds:(CGRect)bounds;
+
+// The rectangle in which the receiver draws its title.
 - (CGRect)titleRectForContentRect:(CGRect)contentRect;
+
+// The rectangle in which the receiver draws its image.
 - (CGRect)imageRectForContentRect:(CGRect)contentRect;
 
 @end
@@ -74,16 +141,33 @@ typedef enum {
 @property (nonatomic, strong, readonly) NSImage *currentImage;
 @property (nonatomic, strong, readonly) NSImage *currentBackgroundImage;
 
-- (void)setTitle:(NSString *)title forState:(TUIControlState)state;
-- (void)setTitleColor:(NSColor *)color forState:(TUIControlState)state;
-- (void)setTitleShadowColor:(NSColor *)color forState:(TUIControlState)state;
-- (void)setImage:(NSImage *)image forState:(TUIControlState)state;
-- (void)setBackgroundImage:(NSImage *)image forState:(TUIControlState)state;
-
 - (NSString *)titleForState:(TUIControlState)state;
 - (NSColor *)titleColorForState:(TUIControlState)state;
 - (NSColor *)titleShadowColorForState:(TUIControlState)state;
 - (NSImage *)imageForState:(TUIControlState)state;
 - (NSImage *)backgroundImageForState:(TUIControlState)state;
 
+// In general, if a property is not specified for a state, the default
+// is to use the TUIControlStateNormal value. If the TUIControlStateNormal
+// value is not set, then the property defaults to a system value.
+// Therefore, at a minimum, you should set the value for the normal state.
+
+// Set the title for the button. The title derives its formatting from
+// the button’s associated label.
+- (void)setTitle:(NSString *)title forState:(TUIControlState)state;
+
+// Set the title color for the button. The color derives its formatting
+// from the button’s associated label.
+- (void)setTitleColor:(NSColor *)color forState:(TUIControlState)state;
+
+// Set the shadow color for the button. The shadow color derives its
+// formatting from the button’s associated label.
+- (void)setTitleShadowColor:(NSColor *)color forState:(TUIControlState)state;
+
+// Set the image for the button.
+- (void)setImage:(NSImage *)image forState:(TUIControlState)state;
+
+// Set the background image for the button.
+- (void)setBackgroundImage:(NSImage *)image forState:(TUIControlState)state;
+
 @end

lib/UIKit/TUIButton.m

@@ -70,13 +70,12 @@ - (id)initWithFrame:(CGRect)frame {
 		self.contentLookup = [NSMutableDictionary dictionary];
 		_buttonFlags.buttonType = TUIButtonTypeStandard;
 
-		self.needsDisplayWhenWindowsKeyednessChanges = YES;
 		self.tintColor = [NSColor colorWithCalibratedWhite:0.95f alpha:1.0f];
 		self.backgroundColor = [NSColor clearColor];
 		self.tintFactor = 0.10f;
 		self.opaque = NO;
 
-		_buttonFlags.reversesTitleShadowWhenHighlighted = NO;
+		self.needsDisplayWhenWindowsKeyednessChanges = YES;
 		_buttonFlags.adjustsImageWhenDisabled = YES;
 		_buttonFlags.adjustsImageWhenHighlighted = YES;
 		_buttonFlags.dimsInBackground = YES;

lib/UIKit/TUIControl.h

@@ -17,60 +17,141 @@
 #import "TUIView.h"
 
 enum {
+
+	// A mouse down event in the control.
 	TUIControlEventMouseDown			= 1 <<  0,
+
+	// A mouse down multi-click event in the control.
+	// -[NSEvent clickCount] will return > 1.
 	TUIControlEventMouseDownRepeat		= 1 <<  1,
+
+	// A mouse drag within the bounds of the control.
 	TUIControlEventMouseDragInside		= 1 <<  2,
+
+	// A mouse drag that leaves the bounds of the control.
 	TUIControlEventMouseDragOutside		= 1 <<  3,
+
 	/*
-	 Needs:
+	 Does not support:
 	 TUIControlEventMouseDragEnter		= 1 <<  4,
 	 TUIControlEventMouseDragExit		= 1 <<  5,
 	 */
+
+	// A mouse up event inside the control.
 	TUIControlEventMouseUpInside		= 1 <<  6,
+
+	// A mouse up event outside the control.
 	TUIControlEventMouseUpOutside		= 1 <<  7,
+
+	// A canceled mouse up event, due to system reasons.
 	TUIControlEventMouseCancel			= 1 <<  8,
 
+	// A mouse hover begin event that a control is tracking.
 	TUIControlEventMouseHoverBegan		= 1 <<  9,
-	TUIControlEventMouseHoverEnded		= 1 <<  9,
+
+	// A mouse hover end event that a control stops tracking.
+	TUIControlEventMouseHoverEnded		= 1 <<  10,
+
+	// A manipulated control caused to emit a series of different values.
 	TUIControlEventValueChanged			= 1 << 12,
 
-	/*
-	 Needs:
+	// A TUITextField editing session was begun, changed, or ended.
 	TUIControlEventEditingDidBegin		= 1 << 16,
 	TUIControlEventEditingChanged		= 1 << 17,
 	TUIControlEventEditingDidEnd		= 1 << 18,
-	 */
 	TUIControlEventEditingDidEndOnExit	= 1 << 19,
 
+	// All mouse events.
 	TUIControlEventAllMouseEvents		= 0x00000FFF,
+
+	// All TUITextField editing session events.
 	TUIControlEventAllEditingEvents		= 0x000F0000,
+
+	// A range of control-event values available for application use.
 	TUIControlEventApplicationReserved	= 0x0F000000,
+
+	// A range of control-event values reserved for framework use.
 	TUIControlEventSystemReserved		= 0xF0000000,
+
+	// All events, including reserved system events.
 	TUIControlEventAllEvents			= 0xFFFFFFFF
 };
 typedef NSUInteger TUIControlEvents;
 
 enum {
-	TUIControlStateNormal			= 0,					   
+
+	// The normal, or default state of a control—that is,
+	// enabled but neither selected nor highlighted.
+	TUIControlStateNormal			= 0,
+
+	// The highlighted state of a control. A control enters this
+	// state when a mouse enters and exits during tracking and
+	// when there is a mouse up event. You can retrieve and set
+	// this value through the highlighted property.
 	TUIControlStateHighlighted		= 1 << 0,
+
+	// the disabled state of a control. This state indicates that
+	// the control is currently disabled. You can retrieve and
+	// set this value through the enabled property.
 	TUIControlStateDisabled			= 1 << 1,
+
+	// The selected state of a control. For many controls, this
+	// state has no effect on behavior or appearance. But other
+	// subclasses may have different appearance depending on
+	// their selected state. You can retrieve and set this value
+	// through the selected property.
 	TUIControlStateSelected			= 1 << 2,
+
+	// The state of a control when a mouse cursor is hovering upon
+	// it. This state can also be read through the tracking property.
 	TUIControlStateHover			= 1 << 3,
+
 	TUIControlStateNotKey			= 1 << 11,
+
+	// Additional control-state flags available for application use.
 	TUIControlStateApplication		= 0x00FF0000,
+
+	// Additional control-state flags reserved for framework use.
 	TUIControlStateReserved			= 0xFF000000
 };
 typedef NSUInteger TUIControlState;
 
+// TUIControl is the base class for control objects such as
+// buttons and sliders that convey user intent to the application.
+// You cannot use the TUIControl class directly to instantiate
+// controls. It instead defines the common interface and behavioral
+// structure for all its subclasses. The main role of UIControl is
+// to define an interface and base implementation for preparing
+// action messages and initially dispatching them to their targets
+// when certain events occur. The TUIControl class also includes
+// methods for getting and setting control state—for example,
+// for determining whether a control is enabled or highlighted—and
+// it defines methods for tracking touches within a control. These
+// tracking methods are overridden by TUIControl subclasses.
 @interface TUIControl : TUIView
 
+// One or more TUIControlState bit-mask constants that specify the
+// state of the TUIControl object. Note that the control can be in
+// more than one state, for example, both disabled and selected.
 @property (nonatomic, readonly) TUIControlState state;
 @property (nonatomic, assign) BOOL acceptsFirstMouse;
 @property (nonatomic, assign) BOOL animateStateChange;
 
+// The value is YES if the receiver is tracking mouse events; otherwise NO.
 @property (nonatomic, readonly, getter = isTracking) BOOL tracking;
+
+// If the control's enabled state is NO, the control ignores
+// events and subclasses may draw differently.
 @property (nonatomic, assign, getter = isEnabled) BOOL enabled;
+
+// For many controls, this state has no effect on behavior or
+// appearance. But other subclasses or the application object
+// might read or set this control state.
 @property (nonatomic, assign, getter = isSelected) BOOL selected;
+
+// By default, a control is not highlighted. TUIControl automatically
+// sets and clears this state automatically when a touch enters
+// and exits during tracking and when there is a mouse up.
 @property (nonatomic, assign, getter = isHighlighted) BOOL highlighted;
 @property (nonatomic, assign, getter = isContinuous) BOOL continuous;
 
@@ -131,10 +212,14 @@ typedef NSUInteger TUIControlState;
 - (NSArray *)actionsForTarget:(id)target forControlEvent:(TUIControlEvents)controlEvent;
 
 // As a TUIControl subclass, these methods enable you to dispatch
-// actions when an event occurs. The first -sendAction:to:forEvent:
-// method call is for the event and is a point at which you can
-// observe or override behavior. It is then called repeately after
-// the second call to this method.
+// actions when an event occurs.
+// The first -sendAction:to:forEvent: method call is for the event
+// and is a point at which you can observe or override behavior.
+// It is then called repeately after the second call to this method.
+// To observe or modify the dispatch of action messages to targets
+// for particular events, override sendAction:to:forEvent:, evaluate
+// the passed-in selector, target object, or TUIControlEvents bit
+// mask, and proceed as required.
 - (void)sendAction:(SEL)action to:(id)target forEvent:(NSEvent *)event;
 - (void)sendActionsForControlEvents:(TUIControlEvents)controlEvents;