/** * @class Ext.Widget * @extend Ext.Evented * @xtype widget * @alternateClassName Ext.Gadget * @mixins Ext.mixin.Inheritable * @mixins Ext.mixin.Bindable * @mixins Ext.mixin.ComponentDelegation * @mixins Ext.mixin.Pluggable * @mixins Ext.mixin.Keyboard * @mixins Ext.mixin.Factoryable * @mixins Ext.mixin.Focusable * @mixins Ext.mixin.Accessible * * Ext.Widget is a light-weight Component that consists of nothing more than a template * Element that can be cloned to quickly and efficiently replicate many instances. * Ext.Widget is typically not instantiated directly, because the default template is * just a single element with no listeners. Instead Ext.Widget should be extended to * create Widgets that have a useful markup structure and event listeners. * * For example: * * Ext.define('MyWidget', { * extend: 'Ext.Widget', * * // The element template passed to Ext.Element.create() * element: { * reference: 'element', * listeners: { * click: 'onClick' * }, * children: [{ * reference: 'innerElement', * listeners: { * click: 'onInnerClick' * } * }] * }, * * constructor: function(config) { * // It is important to remember to call the Widget superclass constructor * // when overriding the constructor in a derived class. This ensures that * // the element is initialized from the template, and that initConfig() is * // is called. * this.callParent([config]); * * // After calling the superclass constructor, the Element is available and * // can safely be manipulated. Reference Elements are instances of * // Ext.Element, and are cached on each Widget instance by reference name. * Ext.getBody().appendChild(this.element); * }, * * onClick: function() { * // listeners use this Widget instance as their scope * console.log('element clicked', this); * }, * * onInnerClick: function() { * // access the innerElement reference by name * console.log('inner element clicked', this.innerElement); * } * }); * * @since 5.0.0 */ /** * @cfg {String/String[]} [cls=null] * The CSS class to add to this widget's element, in * addition to the {@link #baseCls}. In many cases, this property will be specified * by the derived widget class. See {@link #userCls} for adding additional CSS * classes to widget instances (such as items in a {@link Ext.Container}). * @accessor */ /** * @cfg {Boolean/Number} [alwaysOnTop=false] * A flag indicating that this component should be above its floated siblings. * * This may be a positive number to prioritize the ordering of multiple visible always on top components. * * This may be set to a *negative* number to prioritize a component to the *bottom* of the z-index stack. * * @since 6.2.0 * @accessor */ /** * @cfg {String/Ext.util.Region/Ext.dom.Element} [constrainAlign] * A specification of the constraint to apply when {@link #showBy} or {@link #alignTo} * is called to align a {@link #floated} or positioned component. * * Defaults to the parent container for *positioned* components (components * which have their {@link #cfg!top}, {@link #cfg!right}, {@link #cfg!bottom} or {@link #cfg!left} set * to move them out of their container's layout flow). * * Defaults to the viewport for {@link #floated} components. * * May be a {@link Ext.ComponentQuery ComponentQuery} selector to find an ancestor * component to constrain within. * * May be `false` to specify that constraining is not applied. * * You may also specify an element, or a {@link Ext.util.Region Region} * @accessor */ /** * @cfg {Number/String/Object} flex * The flex of this item *if* this item item is inside a {@link Ext.layout.HBox} or {@link Ext.layout.VBox} * layout. * * You can also update the flex of a component dynamically using the {@link Ext.layout.FlexBox#setItemFlex} * method. * * When supplied as a string or number this option supports the same syntax * as CSS [flex](https://developer.mozilla.org/en-US/docs/Web/CSS/flex). * For example: * * flex: '1 2 auto' * * sets `flex-grow` property to `0`, `flex-shrink` to `2` and `flex-basis` to * `'auto'`. * * The default `flex-shrink` value for box layout items is set to `0` in the * stylesheet, which is different from the browser's default `flex-shrink` value * of `1`. This accommodates the majority use case for applications since where * non-flexed components are typically not expected to shrink smaller than their * default size. * * For convenience when only a single number is supplied it is used as the value * for both `flex-grow` and `flex-shrink`, for example `flex: 3` is the same as * `flex: '3 3'` * * An object form is also accepted: * * flex: { * grow: 1, * shrink: 2, * basis: 'auto' * } * * When the object form is supplied `shrink` always defaults to `0` regardless * of the value of `grow`. * * Although `'auto'` is the default value for flex-basis, flex-basis defaults to 0% * when flex is supplied as a single numeric or string value (e.g. `flex: 1`). If * this behavior is not desired either explicitly set flex-basis to `'auto'` or use * the object form to set only grow and/or shrink: * * flex: { * grow: 2 * } * * @evented * @accessor */ /** * @cfg {'clip'/'display'/'offsets'/'opacity'/'visibility'} [hideMode='display'] * A String which specifies how this component's DOM element will be hidden. The * accepted values are any of these: * * - `'clip'` : Hide using {@link Ext.dom.Element#CLIP clip}. * - `'display'` : Hide using {@link Ext.dom.Element#DISPLAY display}. * - `'offsets'` : Hide using positioning {@link Ext.dom.Element#OFFSETS offsets}. * - `'opacity'` : Hide using {@link Ext.dom.Element#OPACITY opacity}. * - `'visibility'` : Hide using {@link Ext.dom.Element#VISIBILITY visibility}. * * Hiding using ``display`` results in having no dimensions as well as resetting * scroll positions to 0. * * The other modes overcome this but may have different trade-offs in certain * circumstances. * * @since 6.5.0 * @accessor */ /** * @cfg {Boolean} [toFrontOnShow=true] * True to automatically call {@link #toFront} when a {@link #cfg-floated} Component is shown. * @accessor */ /** * @cfg {String} [selfAlign] * Specifies the self alignment of this widget in a box layout * @accessor */ /** * @cfg {Boolean} [shadow] * Configure as `true` for the component to have a drop shadow. 'false' will suppress any default shadow. * By default the theme will determine the presence of a shadow. * * @since 6.2.0 * @accessor */ /** * @cfg {Number} [x=0] * *Only valid when a component is `{@link #cfg-floated}`* * * The x position at which to position this component. This is usually viewport-relative. But if there is a * `{@link #relative}: true` ancestor, it will be relative to that. * @accessor */ /** * @cfg {Number} [y=0] * *Only valid when a component is `{@link #cfg-floated}`* * * The x position at which to position this component. This is usually viewport-relative. But if there is a * `{@link #relative}: true` ancestor, it will be relative to that. * @accessor */ /** * @cfg {Boolean/Object/String} ripple * Set to truthy, Color or Object value for the ripple. * @cfg {String} ripple.color The background color of the ripple. * @cfg {Array} ripple.position Position for the ripple to start at [x,y]. * Determines if a Ripple effect should happen whenever this element is pressed. * * For example: * { * ripple: true * } * * Or: * * { * ripple: { * color: 'red' * } * } * * For complex components, individual elements can suppress ripples by adding the * `x-no-ripple` class to disable rippling for a tree of elements. * * @since 6.5.0 * @accessor */ /** * @cfg {Boolean} [relative=false] * *Only valid when a component is `{@link #cfg-floated}`* * * Configure this as `true` if you require descendant floated components to be positioned relative to this * component's coordinate space, not the viewport's coordinate space. * * *Note:* The coordinate space is this Component's encapsulating element's area. Not that of the inner * element in which static child items are rendered by the layout. * * @since 6.2.0 * @accessor */ /** * @cfg {Boolean} [shim=false] * *Only valid when a component is `{@link #cfg-floated}`* * * Configure as `true` for the component to use an `<iframe>` as an underlay to ensure certain non-standard * browser plugins are occluded by this component. * * @since 6.2.0 * @accessor */ /** * @cfg {Boolean} [floated=false] * A Component may be floated above all other components in the application. This means that the component is absolutely * positioned, and will move to the front and occlude other sibling floated component if clicked. * * A Floated component may have floated descendants. It will bring these decendants to the front with it when brought * to the front of its sibling floated components. * * By default, descendant floated components are all positioned using the viewport coordinate system. To make a floating * component a positioning parent for descendants, and have the ancestors positioned relatively, configure the parent * floated component with `{@link #cfg-relative}: true`. * * @since 6.2.0 * @accessor */ /** * @cfg {String/Object} [style=null] * Additional CSS styles that will be rendered into an inline style attribute when * the widget is rendered. * * You can pass either a string syntax: * * style: 'background:red' * * Or by using an object: * * style: { * background: 'red' * } * * When using the object syntax, you can define CSS Properties by using a string: * * style: { * 'border-left': '1px solid red' * } * * Although the object syntax is much easier to read, we suggest you to use the * string syntax for better performance. * @accessor set */ /** * @cfg {Boolean} [border=null] * * Enables or disables bordering on this component. * The following values are accepted: * * - `null` or `true (default): Do nothing and allow the border to be specified by the theme. * - `false`: suppress the default border provided by the theme. * * Please note that enabling bordering via this config will not add a `border-color` * or `border-style` CSS property to the component; you provide the `border-color` * and `border-style` via CSS rule or {@link #style} configuration * (if not already provide by the theme). * * @accessor */ /** * @cfg {Object} [touchAction=true] * * Emulates the behavior of the CSS [touch-action](https://www.w3.org/TR/pointerevents/#the-touch-action-css-property) * property in a cross-browser compatible manner. * * Keys in this object are touch action names, and values are `false` to disable * a touch action or `true` to enable it. Accepted keys are: * * - `panX` * - `panY` * - `pinchZoom` * - `doubleTapZoom` * * All touch actions are enabled (`true`) by default, so it is usually only necessary * to specify which touch actions to disable. For example, the following disables * only horizontal scrolling and pinch-to-zoom on the component's main element: * * touchAction: { * panX: false, * pinchZoom: false * } * * Touch actions can be specified on reference elements using the reference element * name, for example: * * // disables horizontal scrolling on the main element, and double-tap-zoom * // on the child element named "body" * touchAction: { * panY: false * body: { * doubleTapZoom: false * } * } * * The primary motivation for setting the touch-action of an element is to prevent * the browser's default handling of a gesture such as pinch-to-zoom, or * drag-to-scroll, so that the application can implement its own handling of that * gesture on the element. Suppose, for example, a component has a custom drag * handler on its element and wishes to prevent horizontal scrolling of its container * while it is being dragged: * * Ext.create('Ext.Widget', { * touchAction: { * panX: false * }, * listeners: { * drag: function(e) { * // implement drag logic * } * } * }); */ /** * @cfg {String} [name=null] * Name for the widget to be used with {@link Ext.Container#lookupName} et al. */ /** * @cfg {String} id * The **unique id of this component instance.** * * It should not be necessary to use this configuration except for singleton objects in your application. Components * created with an id may be accessed globally using {@link Ext#getCmp Ext.getCmp}. * * Instead of using assigned ids, use the {@link #itemId} config, and {@link Ext.ComponentQuery ComponentQuery} * which provides selector-based searching for Sencha Components analogous to DOM querying. The * {@link Ext.Container} class contains {@link Ext.Container#down shortcut methods} to query * its descendant Components by selector. * * Note that this id will also be used as the element id for the containing HTML element that is rendered to the * page for this component. This allows you to write id-based CSS rules to style the specific instance of this * component uniquely, and also to select sub-elements using this component's id as the parent. * * **Note**: to avoid complications imposed by a unique id also see `{@link #itemId}`. * * Defaults to an auto-assigned id. */ /** * @cfg {String} itemId * An itemId can be used as an alternative way to get a reference to a component when no object reference is * available. Instead of using an `{@link #id}` with {@link Ext#getCmp}, use `itemId` with * {@link Ext.Container#getComponent} which will retrieve `itemId`'s or {@link #id}'s. Since `itemId`'s are an * index to the container's internal MixedCollection, the `itemId` is scoped locally to the container - avoiding * potential conflicts with {@link Ext.ComponentManager} which requires a **unique** `{@link #id}`. * * Also see {@link #id}, {@link Ext.Container#query}, {@link Ext.Container#down} and {@link Ext.Container#child}. * * @accessor */ /** * @cfg {Ext.Element} [renderTo=true] * Optional element to render this Component to. * Not required if this component is an {@link Ext.Container#items item} of a Container of a Container. */ /** * @cfg {String/String[]} [ui=true] * The ui or uis to be used on this Component * * When a ui is configured, CSS class names are added to the {@link #element}, created * by appending the ui name(s) to each {@link #classCls} and/or {@link #baseCls}. */ /** * @cfg {String/String[]} [userCls=true] * One or more CSS classes to add to the component's primary element. This config * is intended solely for use by the component instantiator (the "user"), not by * derived classes. * * For example: * * items: [{ * xtype: 'button', * userCls: 'my-button' * ... * }] */ /** * @cfg {Number/String} [width=null] * The width of this Component; must be a valid CSS length value, e.g: `300`, `100px`, `30%`, etc. * By default, if this is not explicitly set, this Component's element will simply have its own natural size. * If set to `auto`, it will set the width to `null` meaning it will have its own natural size. * @accessor * @evented */ /** * @cfg {Number/String} [height=null] * The height of this Component; must be a valid CSS length value, e.g: `300`, `100px`, `30%`, etc. * By default, if this is not explicitly set, this Component's element will simply have its own natural size. * If set to `auto`, it will set the width to `null` meaning it will have its own natural size. * @accessor * @evented */ /** * @cfg {Boolean} [hidden=null] * Whether or not this Component is hidden (its CSS `display` property is set to `none`). * * Defaults to `true` for {@link #floated} Components. * @accessor * @evented */ /** * @cfg {Boolean} [disabled=null] * Whether or not this component is disabled * @accessor * @evented */ /** * @method up * Walks up the ownership hierarchy looking for an ancestor Component which matches * the passed simple selector. * * Example: * * var owningTabPanel = grid.up('tabpanel'); * * @param {String} selector (optional) The simple selector to test. * @param {String/Number/Ext.Component} [limit] This may be a selector upon which to stop the upward scan, or a limit of the number of steps, or Component reference to stop on. * @return {Ext.Container} The matching ancestor Container (or `undefined` if no match was found). */