Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / CheckItem.html
index 7cdb390..7615e87 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.menu.CheckItem"></div>/**
- * @class Ext.menu.CheckItem
- * @extends Ext.menu.Item
- * Adds a menu item that contains a checkbox by default, but can also be part of a radio group.
- * @constructor
- * Creates a new CheckItem
- * @param {Object} config Configuration options
- * @xtype menucheckitem
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-menu-CheckItem'>/**
+</span> * A menu item that contains a togglable checkbox by default, but that can also be a part of a radio group.
+ *
+ *     @example
+ *     Ext.create('Ext.menu.Menu', {
+ *         width: 100,
+ *         height: 110,
+ *         floating: false,  // usually you want this set to True (default)
+ *         renderTo: Ext.getBody(),  // usually rendered by it's containing component
+ *         items: [{
+ *             xtype: 'menucheckitem',
+ *             text: 'select all'
+ *         },{
+ *             xtype: 'menucheckitem',
+ *             text: 'select specific',
+ *         },{
+ *             iconCls: 'add16',
+ *             text: 'icon item'
+ *         },{
+ *             text: 'regular item'
+ *         }]
+ *     });
  */
-Ext.menu.CheckItem = Ext.extend(Ext.menu.Item, {
-    <div id="cfg-Ext.menu.CheckItem-group"></div>/**
-     * @cfg {String} group
-     * All check items with the same group name will automatically be grouped into a single-select
-     * radio button group (defaults to '')
+Ext.define('Ext.menu.CheckItem', {
+    extend: 'Ext.menu.Item',
+    alias: 'widget.menucheckitem',
+
+<span id='Ext-menu-CheckItem-cfg-checkedCls'>    /**
+</span>     * @cfg {String} checkedCls
+     * The CSS class used by {@link #cls} to show the checked state.
+     * Defaults to `Ext.baseCSSPrefix + 'menu-item-checked'`.
      */
-    <div id="cfg-Ext.menu.CheckItem-itemCls"></div>/**
-     * @cfg {String} itemCls The default CSS class to use for check items (defaults to "x-menu-item x-menu-check-item")
+    checkedCls: Ext.baseCSSPrefix + 'menu-item-checked',
+<span id='Ext-menu-CheckItem-cfg-uncheckedCls'>    /**
+</span>     * @cfg {String} uncheckedCls
+     * The CSS class used by {@link #cls} to show the unchecked state.
+     * Defaults to `Ext.baseCSSPrefix + 'menu-item-unchecked'`.
      */
-    itemCls : "x-menu-item x-menu-check-item",
-    <div id="cfg-Ext.menu.CheckItem-groupClass"></div>/**
-     * @cfg {String} groupClass The default CSS class to use for radio group check items (defaults to "x-menu-group-item")
+    uncheckedCls: Ext.baseCSSPrefix + 'menu-item-unchecked',
+<span id='Ext-menu-CheckItem-cfg-groupCls'>    /**
+</span>     * @cfg {String} groupCls
+     * The CSS class applied to this item's icon image to denote being a part of a radio group.
+     * Defaults to `Ext.baseCSSClass + 'menu-group-icon'`.
+     * Any specified {@link #iconCls} overrides this.
      */
-    groupClass : "x-menu-group-item",
+    groupCls: Ext.baseCSSPrefix + 'menu-group-icon',
 
-    <div id="cfg-Ext.menu.CheckItem-checked"></div>/**
-     * @cfg {Boolean} checked True to initialize this checkbox as checked (defaults to false).  Note that
-     * if this checkbox is part of a radio group (group = true) only the last item in the group that is
-     * initialized with checked = true will be rendered as checked.
+<span id='Ext-menu-CheckItem-cfg-hideOnClick'>    /**
+</span>     * @cfg {Boolean} hideOnClick
+     * Whether to not to hide the owning menu when this item is clicked.
+     * Defaults to `false` for checkbox items, and to `true` for radio group items.
      */
-    checked: false,
+    hideOnClick: false,
 
-    // private
-    ctype: "Ext.menu.CheckItem",
-    
-    initComponent : function(){
-        Ext.menu.CheckItem.superclass.initComponent.call(this);
-           this.addEvents(
-               <div id="event-Ext.menu.CheckItem-beforecheckchange"></div>/**
-                * @event beforecheckchange
-                * Fires before the checked value is set, providing an opportunity to cancel if needed
-                * @param {Ext.menu.CheckItem} this
-                * @param {Boolean} checked The new checked value that will be set
-                */
-               "beforecheckchange" ,
-               <div id="event-Ext.menu.CheckItem-checkchange"></div>/**
-                * @event checkchange
-                * Fires after the checked value has been set
-                * @param {Ext.menu.CheckItem} this
-                * @param {Boolean} checked The checked value that was set
-                */
-               "checkchange"
-           );
-           <div id="method-Ext.menu.CheckItem-checkHandler"></div>/**
-            * A function that handles the checkchange event.  The function is undefined by default, but if an implementation
-            * is provided, it will be called automatically when the checkchange event fires.
-            * @param {Ext.menu.CheckItem} this
-            * @param {Boolean} checked The checked value that was set
-            * @method checkHandler
-            */
-           if(this.checkHandler){
-               this.on('checkchange', this.checkHandler, this.scope);
-           }
-           Ext.menu.MenuMgr.registerCheckable(this);
+    afterRender: function() {
+        var me = this;
+        this.callParent();
+        me.checked = !me.checked;
+        me.setChecked(!me.checked, true);
     },
 
-    // private
-    onRender : function(c){
-        Ext.menu.CheckItem.superclass.onRender.apply(this, arguments);
-        if(this.group){
-            this.el.addClass(this.groupClass);
+    initComponent: function() {
+        var me = this;
+        me.addEvents(
+<span id='Ext-menu-CheckItem-event-beforecheckchange'>            /**
+</span>             * @event beforecheckchange
+             * Fires before a change event. Return false to cancel.
+             * @param {Ext.menu.CheckItem} this
+             * @param {Boolean} checked
+             */
+            'beforecheckchange',
+
+<span id='Ext-menu-CheckItem-event-checkchange'>            /**
+</span>             * @event checkchange
+             * Fires after a change event.
+             * @param {Ext.menu.CheckItem} this
+             * @param {Boolean} checked
+             */
+            'checkchange'
+        );
+
+        me.callParent(arguments);
+
+        Ext.menu.Manager.registerCheckable(me);
+
+        if (me.group) {
+            if (!me.iconCls) {
+                me.iconCls = me.groupCls;
+            }
+            if (me.initialConfig.hideOnClick !== false) {
+                me.hideOnClick = true;
+            }
         }
-        if(this.checked){
-            this.checked = false;
-            this.setChecked(true, true);
+    },
+
+<span id='Ext-menu-CheckItem-method-disableCheckChange'>    /**
+</span>     * Disables just the checkbox functionality of this menu Item. If this menu item has a submenu, that submenu
+     * will still be accessible
+     */
+    disableCheckChange: function() {
+        var me = this;
+
+        if (me.iconEl) {
+            me.iconEl.addCls(me.disabledCls);
+        }
+        me.checkChangeDisabled = true;
+    },
+
+<span id='Ext-menu-CheckItem-method-enableCheckChange'>    /**
+</span>     * Reenables the checkbox functionality of this menu item after having been disabled by {@link #disableCheckChange}
+     */
+    enableCheckChange: function() {
+        var me = this;
+
+        me.iconEl.removeCls(me.disabledCls);
+        me.checkChangeDisabled = false;
+    },
+
+    onClick: function(e) {
+        var me = this;
+        if(!me.disabled &amp;&amp; !me.checkChangeDisabled &amp;&amp; !(me.checked &amp;&amp; me.group)) {
+            me.setChecked(!me.checked);
         }
+        this.callParent([e]);
     },
 
-    // private
-    destroy : function(){
-        Ext.menu.MenuMgr.unregisterCheckable(this);
-        Ext.menu.CheckItem.superclass.destroy.apply(this, arguments);
+    onDestroy: function() {
+        Ext.menu.Manager.unregisterCheckable(this);
+        this.callParent(arguments);
     },
 
-    <div id="method-Ext.menu.CheckItem-setChecked"></div>/**
-     * Set the checked state of this item
-     * @param {Boolean} checked The new checked value
-     * @param {Boolean} suppressEvent (optional) True to prevent the checkchange event from firing (defaults to false)
+<span id='Ext-menu-CheckItem-method-setChecked'>    /**
+</span>     * Sets the checked state of the item
+     * @param {Boolean} checked True to check, false to uncheck
+     * @param {Boolean} suppressEvents (optional) True to prevent firing the checkchange events. Defaults to `false`.
      */
-    setChecked : function(state, suppressEvent){
-        var suppress = suppressEvent === true;
-        if(this.checked != state && (suppress || this.fireEvent("beforecheckchange", this, state) !== false)){
-            if(this.container){
-                this.container[state ? "addClass" : "removeClass"]("x-menu-item-checked");
+    setChecked: function(checked, suppressEvents) {
+        var me = this;
+        if (me.checked !== checked &amp;&amp; (suppressEvents || me.fireEvent('beforecheckchange', me, checked) !== false)) {
+            if (me.el) {
+                me.el[checked  ? 'addCls' : 'removeCls'](me.checkedCls)[!checked ? 'addCls' : 'removeCls'](me.uncheckedCls);
             }
-            this.checked = state;
-            if(!suppress){
-                this.fireEvent("checkchange", this, state);
+            me.checked = checked;
+            Ext.menu.Manager.onCheckChange(me, checked);
+            if (!suppressEvents) {
+                Ext.callback(me.checkHandler, me.scope, [me, checked]);
+                me.fireEvent('checkchange', me, checked);
             }
         }
-    },
-
-    // private
-    handleClick : function(e){
-       if(!this.disabled && !(this.checked && this.group)){// disable unselect on radio item
-           this.setChecked(!this.checked);
-       }
-       Ext.menu.CheckItem.superclass.handleClick.apply(this, arguments);
     }
 });
-Ext.reg('menucheckitem', Ext.menu.CheckItem);</pre>    \r
-</body>\r
-</html>
\ No newline at end of file
+</pre>
+</body>
+</html>