// ========================================================================== // Project: SproutCore
- JavaScript Application Framework // Copyright: ©2006-2011 Strobe Inc. and contributors. // Portions ©2008-2011 Apple Inc. All rights reserved. // License: Licensed under MIT license (see license.js) // ==========================================================================
sc_require('mixins/content_value_support'); sc_require('system/string');
/**
Option for controls to automatically calculate their size (should be default on controls that use renderers). @type String @constant
*/ SC
.AUTO_CONTROL_SIZE = '__AUTO__';
/**
Option for HUGE control size. @type String @constant
*/ SC
.JUMBO_CONTROL_SIZE = 'sc-jumbo-size';
/**
Option for HUGE control size. @type String @constant
*/ SC
.HUGE_CONTROL_SIZE = 'sc-huge-size';
/**
Option for large control size. @type String @constant
*/ SC
.LARGE_CONTROL_SIZE = 'sc-large-size';
/**
Option for standard control size. @type String @constant
*/ SC
.REGULAR_CONTROL_SIZE = 'sc-regular-size';
/**
Option for small control size. @type String @constant
*/ SC
.SMALL_CONTROL_SIZE = 'sc-small-size';
/**
Option for tiny control size @type String @constant
*/ SC
.TINY_CONTROL_SIZE = 'sc-tiny-size';
/**
@namespace A Control is a view that also implements some basic state functionality. Apply this mixin to any view that you want to have standard control functionality including showing a selected state, enabled state, focus state, etc. ## About Values and Content Controls typically are used to represent a single value, such as a number, boolean or string. The value a control is managing is typically stored in a "value" property. You will typically use the value property when working with controls such as buttons and text fields in a form. An alternative way of working with a control is to use it to manage some specific aspect of a content object. For example, you might use a label view control to display the "name" property of a Contact record. This approach is often necessary when using the control as part of a collection view. You can use the content-approach to work with a control by setting the "content" and "contentValueKey" properties of the control. The "content" property is the content object you want to manage, while the "contentValueKey" is the name of the property on the content object you want the control to display. The default implementation of the Control mixin will essentially map the contentValueKey of a content object to the value property of the control. Thus if you are writing a custom control yourself, you can simply work with the value property and the content object support will come for free. Just write an observer for the value property and update your view accordingly. If you are working with a control that needs to display multiple aspects of a single content object (for example showing an icon and label), then you can override the contentValueDidChange() method instead of observing the value property. This method will be called anytime _any_ property on the content object changes. You should use this method to check the properties you care about on the content object and update your view if anything you care about has changed. ## Delegate Support Controls can optionally get the contentDisplayProperty from a displayDelegate, if it is set. The displayDelegate is often used to delegate common display-related configurations such as which content value to show. Anytime your control is shown as part of a collection view, the collection view will be automatically set as its displayDelegate. @since SproutCore 1.0 @extends SC.ContentValueSupport
*/ SC
.Control = SC.mixin(SC.clone(SC.ContentValueSupport), /** @scope SC
.Control.prototype */{
/** Walk like a duck @type Boolean @default YES @readOnly */ isControl: YES, /** The selected state of this control. Possible values: - `YES` - `NO` - SC.MIXED_STATE. @type Boolean @default NO */ isSelected: NO, /** @private */ isSelectedBindingDefault: SC.Binding.oneWay().bool(), /** Set to YES when the item is currently active. Usually this means the mouse is current pressed and hovering over the control, however the specific implementation my vary depending on the control. Changing this property value by default will cause the Control mixin to add/remove an 'active' class name to the root element. @type Boolean @default NO */ isActive: NO, /** @private */ isActiveBindingDefault: SC.Binding.oneWay().bool(), /** The name of the property this control should display if it is part of an SC.FormView. If you add a control as part of an SC.FormView, then the form view will automatically bind the value to the property key you name here on the content object. @type String @default null */ fieldKey: null, /** The human readable label you want shown for errors. May be a loc string. If your field fails validation, then this is the name that will be shown in the error explanation. If you do not set this property, then the fieldKey or the class name will be used to generate a human readable name. @type String @default null */ fieldLabel: null, /** The human readable label for this control for use in error strings. This property is computed dynamically using the following rules: If the fieldLabel is defined, that property is localized and returned. Otherwise, if the keyField is defined, try to localize using the string "ErrorLabel.{fieldKeyName}". If a localized name cannot be found, use a humanized form of the fieldKey. Try to localize using the string "ErrorLabel.{ClassName}". Return a humanized form of the class name. @field @type String @observes 'fieldLabel' @observes 'fieldKey' */ errorLabel: function () { var ret = this.get('fieldLabel'), fk, def, locFK; // Fast path! if (ret) return ret; // if field label is not provided, compute something... fk = this.get('fieldKey') || this.constructor.toString(); def = fk ? SC.String.capitalize(SC.String.humanize(fk)) : ''; locFK = SC.String.locWithDefault("FieldKey." + fk, def); return SC.String.locWithDefault("ErrorLabel." + fk, locFK); }.property('fieldLabel', 'fieldKey').cacheable(), /** The control size. This will set a CSS style on the element that can be used by the current theme to vary the appearance of the control. Some controls will default to SC.AUTO_CONTROL_SIZE, which will allow you to simply size the control, and the most appropriate control size will automatically be picked; be warned, though, that if you don't specify a height, performance will be impacted as it must be calculated; if you do this, a warning will be issued. If you don't care, use SC.CALCULATED_CONTROL_SIZE. @type String @default SC.REGULAR_CONTROL_SIZE */ controlSize: SC.REGULAR_CONTROL_SIZE, /** @private */ displayProperties: ['isSelected', 'isActive', 'controlSize'], /** @private */ _CONTROL_TMP_CLASSNAMES: {}, /** @private Invoke this method in your updateDisplay() method to update any basic control CSS classes. */ renderMixin: function (context, firstTime) { var sel = this.get('isSelected'), disabled = !this.get('isEnabledInPane'), // update the CSS classes for the control. note we reuse the same hash // to avoid consuming more memory names = this._CONTROL_TMP_CLASSNAMES; // temporary object names.mixed = sel === SC.MIXED_STATE; names.sel = sel && (sel !== SC.MIXED_STATE); names.active = this.get('isActive'); var controlSize = this.get("controlSize"); if (!controlSize) { controlSize = SC.REGULAR_CONTROL_SIZE; } if (firstTime) { context.setClass(names); // delegates handle adding 'controlSize' on their own. We only support it // here for backwards-compatibility. if (!this.get('renderDelegate')) { context.addClass(controlSize); } } else { context.$().setClass(names); if (!this.get('renderDelegate')) { context.$().addClass(controlSize); } } // if the control implements the $input() helper, then fixup the input // tags if (!firstTime && this.$input) { var inps = this.$input(); if (inps.attr('type') !== "radio") { this.$input().attr('disabled', disabled); } } }
});