From 23c33aed955914dd6141842d282c4240872e6622 Mon Sep 17 00:00:00 2001 From: Aditya Nrusimha Date: Sat, 17 Nov 2012 00:11:50 -0800 Subject: [PATCH] TUIButton and TUIControl documentation. --- lib/UIKit/TUIButton.h | 106 ++++++++++++++++++++++++++++++++++++----- lib/UIKit/TUIButton.m | 3 +- lib/UIKit/TUIControl.h | 105 ++++++++++++++++++++++++++++++++++++---- 3 files changed, 191 insertions(+), 23 deletions(-) diff --git a/lib/UIKit/TUIButton.h b/lib/UIKit/TUIButton.h index a8438190..9e5f4dc8 100644 --- a/lib/UIKit/TUIButton.h +++ b/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 diff --git a/lib/UIKit/TUIButton.m b/lib/UIKit/TUIButton.m index 9e95fc6d..9b423997 100644 --- a/lib/UIKit/TUIButton.m +++ b/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; diff --git a/lib/UIKit/TUIControl.h b/lib/UIKit/TUIControl.h index 388b0125..0f83abeb 100644 --- a/lib/UIKit/TUIControl.h +++ b/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;