add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / form / Label.js

/**\r
 * Produces a standalone `<label />` element which can be inserted into a form and be associated with a field\r
 * in that form using the {@link #forId} property.\r
 * \r
 * **NOTE:** in most cases it will be more appropriate to use the {@link Ext.form.Labelable#fieldLabel fieldLabel}\r
 * and associated config properties ({@link Ext.form.Labelable#labelAlign}, {@link Ext.form.Labelable#labelWidth},\r
 * etc.) in field components themselves, as that allows labels to be uniformly sized throughout the form.\r
 * Ext.form.Label should only be used when your layout can not be achieved with the standard\r
 * {@link Ext.form.Labelable field layout}.\r
 * \r
 * You will likely be associating the label with a field component that extends {@link Ext.form.field.Base}, so\r
 * you should make sure the {@link #forId} is set to the same value as the {@link Ext.form.field.Base#inputId inputId}\r
 * of that field.\r
 * \r
 * The label's text can be set using either the {@link #text} or {@link #html} configuration properties; the\r
 * difference between the two is that the former will automatically escape HTML characters when rendering, while\r
 * the latter will not.\r
 *\r
 * # Example\r
 * \r
 * This example creates a Label after its associated Text field, an arrangement that cannot currently\r
 * be achieved using the standard Field layout's labelAlign.\r
 * \r
 *     @example\r
 *     Ext.create('Ext.form.Panel', {\r
 *         title: 'Field with Label',\r
 *         width: 400,\r
 *         bodyPadding: 10,\r
 *         renderTo: Ext.getBody(),\r
 *         layout: {\r
 *             type: 'hbox',\r
 *             align: 'middle'\r
 *         },\r
 *         items: [{\r
 *             xtype: 'textfield',\r
 *             hideLabel: true,\r
 *             flex: 1\r
 *         }, {\r
 *             xtype: 'label',\r
 *             forId: 'myFieldId',\r
 *             text: 'My Awesome Field',\r
 *             margin: '0 0 0 10'\r
 *         }]\r
 *     });\r
 */\r
Ext.define('Ext.form.Label', {\r
    extend:'Ext.Component',\r
    alias: 'widget.label',\r
    requires: ['Ext.util.Format'],\r
\r
    autoEl: 'label',\r
\r
    /**\r
     * @cfg {String} [text='']\r
     * The plain text to display within the label. If you need to include HTML\r
     * tags within the label's innerHTML, use the {@link #html} config instead.\r
     */\r
    /**\r
     * @cfg {String} forId\r
     * The id of the input element to which this label will be bound via the standard HTML 'for'\r
     * attribute. If not specified, the attribute will not be added to the label. In most cases you will be\r
     * associating the label with a {@link Ext.form.field.Base} component, so you should make sure this matches\r
     * the {@link Ext.form.field.Base#inputId inputId} of that field.\r
     */\r
    /**\r
     * @cfg {String} [html='']\r
     * An HTML fragment that will be used as the label's innerHTML.\r
     * Note that if {@link #text} is specified it will take precedence and this value will be ignored.\r
     */\r
    \r
    maskOnDisable: false,\r
\r
    getElConfig: function(){\r
        var me = this;\r
\r
        me.html = me.text ? Ext.util.Format.htmlEncode(me.text) : (me.html || '');\r
        return Ext.apply(me.callParent(), {\r
            htmlFor: me.forId || ''\r
        });\r
    },\r
\r
    /**\r
     * Updates the label's innerHTML with the specified string.\r
     * @param {String} text The new label text\r
     * @param {Boolean} [encode=true] False to skip HTML-encoding the text when rendering it\r
     * to the label. This might be useful if you want to include tags in the label's innerHTML rather\r
     * than rendering them as string literals per the default logic.\r
     * @return {Ext.form.Label} this\r
     */\r
    setText : function(text, encode){\r
        var me = this;\r
        \r
        encode = encode !== false;\r
        if(encode) {\r
            me.text = text;\r
            delete me.html;\r
        } else {\r
            me.html = text;\r
            delete me.text;\r
        }\r
        \r
        if(me.rendered){\r
            me.el.dom.innerHTML = encode !== false ? Ext.util.Format.htmlEncode(text) : text;\r
            me.updateLayout();\r
        }\r
        return me;\r
    }\r
});\r
\r