Class: SC.ButtonView


Extends SC.Control, SC.View.

Implements a push-button-style button. This class is used to implement both standard push buttons and tab-style controls. See also SC.CheckboxView and SC.RadioView which are implemented as field views, but can also be treated as buttons.

By default, a button uses the SC.Control mixin which will apply CSS classnames when the state of the button changes:

Defined in: button.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.View:
acceptsMultitouch, ariaHidden, attributeBindings, autoMixins, backgroundColor, childViewLayout, childViewLayoutOptions, childViews, childViewsNeedLayout, classNameBindings, concatenatedProperties, createdByParent, designMode, enabledState, firstKeyView, hasLayout, hasTouch, hasVisibility, isBuildingIn, isBuildingOut, isChildViewLayoutLive, isEnabled, isFixedHeight, isFixedPosition, isFixedSize, isFixedWidth, isKeyResponder, isTextSelectable, isView, isVisible, lastKeyView, layerLocationNeedsUpdate, layerNeedsUpdate, layout, modeAdjust, nextKeyView, page, pane, parentView, previousKeyView, shouldInheritCursor, shouldInheritEnabled, tagName, toolTip, touchBoundary, transitionAdjust, transitionAdjustOptions, transitionHide, transitionHideOptions, transitionIn, transitionInOptions, transitionOut, transitionOutOptions, transitionShow, transitionShowOptions, useStaticLayout
Fields borrowed from SC.Responder:
hasFirstResponder, isFirstResponder, responderContext
Fields borrowed from SC.Object:
isDestroyed, isObject, nextProperty, object, property, toInvalidate
Fields borrowed from SC.Observable:
isObservable
Fields borrowed from SC.Control:
controlSize, errorLabel, fieldKey, fieldLabel, isActive, isControl, isSelected

Instance Methods

Field Detail

action String

The name of the method to call when the button is pressed.

This property is used in conjunction with the target property to execute a method when a regular button is pressed. If you do not set a target, then pressing the button will cause a search of the responder chain for a view that implements the action named. If you do set a target, then the button will only try to call the method on that target.

The action method of the target should implement the following signature:

action: function (sender) {
  // Return value is ignored by SC.ButtonView.
}

Therefore, if a target needs to know which button called its action, it should look to the sender argument. NOTE:* This property is not relevant when the button is used in toggle mode. Toggle mode only modifies the value of the button without triggering actions.

Default value:
null
See:
SC.ActionSupport
ariaRole String
The WAI-ARIA role of the button.
Default value:
'button'
autoResizePadding Number

The padding to add to the measured size of the text to arrive at the measured size for the view.

SC.ButtonView gets this from its render delegate, but if not supplied, defaults to 10.

Default value:
10
buttonBehavior String

The behavioral mode of this button.

Possible values are:

  • SC.PUSH_BEHAVIOR -- Pressing the button will trigger an action tied to the button. Does not change the value of the button.
  • SC.TOGGLE_BEHAVIOR -- Pressing the button will invert the current value of the button. If the button has a mixed value, it will be set to true.
  • SC.TOGGLE_ON_BEHAVIOR -- Pressing the button will set the current state to true no matter the previous value.
  • SC.TOGGLE_OFF_BEHAVIOR -- Pressing the button will set the current state to false no matter the previous value.
  • SC.HOLD_BEHAVIOR -- Pressing the button will cause the action to repeat at a regular interval specified by 'holdInterval'
Default value:
SC.PUSH_BEHAVIOR
classNames Array
Default value:
['sc-button-view']
See:
SC.View#classNames
SC.ButtonView.CLICK_AND_HOLD_DELAY Number

The delay after which "click" behavior should transition to "click and hold" behavior. This is used by subclasses such as PopupButtonView and SelectButtonView.

contentIconKey String

If you set this property, the icon will be updated automatically from the content using the key you specify.

Default value:
null
contentTitleKey String

If set, the title property will be updated automatically from the content using the key you specify.

Default value:
null
displayProperties Array

The following properties affect how SC.ButtonView is rendered, and will cause the view to be rerendered if they change.

Note: 'value', 'isDefault', 'isCancel' are also display properties, but are observed separately.

Default value:
['icon', 'displayTitle', 'displayToolTip', 'supportFocusRing', 'buttonBehavior']
escapeHTML Boolean

Whether the title and toolTip will be escaped to avoid HTML injection attacks or not.

You should only disable this option if you are sure you are displaying non-user generated text.

Note: this is not an observed display property. If you change it after rendering, you should call displayDidChange on the view to update the layer.

Default value:
true
icon String

The button icon. Set this to either a URL or a CSS class name (for spriting). Note that if you pass a URL, it must contain at least one slash to be detected as such.

Default value:
null
isCancel Boolean

If YES, then this button will be triggered when you hit escape. This is the same as setting the keyEquivalent to 'escape'.

Default value:
NO
isDefault Boolean

If YES, then this button will be triggered when you hit return.

This is the same as setting the keyEquivalent to 'return'. This will also apply the "def" classname to the button.

Default value:
NO
keyEquivalent String
The key equivalent that should trigger this button on the page.
Default value:
null
localize Boolean
If YES, then the title will be localized.
Default value:
NO
needsEllipsis Boolean

If YES, button will attempt to display an ellipsis if the title cannot fit inside of the visible area. This feature is not available on all browsers.

Note: this is not an observed display property. If you change it after rendering, you should call displayDidChange on the view to update the layer.

Default value:
YES
renderDelegateName String

The name of the render delegate in the theme that should be used to render the button.

In this case, the 'button' property will be retrieved from the theme and set to the render delegate of this view.

Default value:
'buttonRenderDelegate'
supportFocusRing Boolean
If YES, use a focus ring.
Default value:
NO
target Object

The target to invoke the action on when the button is pressed.

If you set this target, the action will be called on the target object directly when the button is clicked. If you leave this property set to null, then the responder chain will be searched for a view that implements the action when the button is pressed.

The action method of the target should implement the following signature:

action: function (sender) {
  // Return value is ignored by SC.ButtonView.
}

Therefore, if a target needs to know which button called its action, it should look to the sender argument. NOTE:* This property is not relevant when the button is used in toggle mode. Toggle mode only modifies the value of the button without triggering actions.

Default value:
null
See:
SC.ActionSupport
themeName String

The theme to apply to the button. By default, a subtheme with the name of 'square' is created for backwards-compatibility.

Default value:
'square'
title String

The button title. If localize is YES, then this should be the localization key to display. Otherwise, this will be the actual string displayed in the title. This property is observable and bindable.

Default value:
""
toggleOffValue Boolean|Object

Value of an unselected toggle button.

For a toggle button, set this to any object value you want. When the user toggle's the button off, the value of the button will be set to this value.

Default value:
NO
toggleOnValue Boolean|Object

Value of a selected toggle button.

For a toggle button, set this to any object value you want. The button will be selected if the value property equals the targetValue. If the value is an array of multiple items that contains the targetValue, then the button will be set to a mixed state.

default is YES

Default value:
YES
SC.ButtonView.TRIGGER_DELAY
How long to wait before triggering the action.
value Object

Used to automatically update the state of the button view for toggle style buttons.

For toggle style buttons, you can set the value and it will be used to update the isSelected state of the button view. The value will also change as the user selects or deselects. You can control which values the button will treat as isSelected by setting the toggleOnValue and toggleOffValue. Alternatively, if you leave these properties set to YES or NO, the button will do its best to convert a value to an appropriate state:

  • null, false, 0 -- isSelected = false
  • any other single value -- isSelected = true
  • array -- if all values are the same state, that state; otherwise MIXED.
Default value:
null

Instance Method Detail

acceptsFirstResponder()
Tied to the isEnabledInPane state
computeIsSelectedForValue(value)

This is the standard logic to compute a proposed isSelected state for a new value. This takes into account the toggleOnValue/toggleOffValue properties, among other things. It may return YES, NO, or SC.MIXED_STATE.

Parameters:
value Object
Returns:
Boolean
return state
didTriggerAction()

Callback called anytime the button's action is triggered. You can implement this method in your own subclass to perform any cleanup needed after an action is performed.

displayTitle()
This is generated by localizing the title property if necessary.
performKeyEquivalent(keystring, evt)

Handle a key equivalent if set. Trigger the default action for the button. Depending on the implementation this may vary.

Parameters:
keystring String
evt SC.Event
Returns:
Boolean
YES if handled, NO otherwise
triggerActionAfterDelay(evt)

Called when the user presses a shortcut key, such as return or cancel, associated with this button.

Highlights the button to show that it is being triggered, then, after a delay, performs the button's action.

Does nothing if the button is disabled.

Parameters:
evt Event
Returns:
Boolean
YES if successful, NO otherwise
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)