YouTip"`, `$.ui.progressbar({ value: 50 })` instantiates a progressbar widget instance on a new `
`.
* **document**: The `document` containing the widget element. Useful when interacting with widgets inside iframes.
* **element**: A jQuery object containing the element used to instantiate the widget. If you select multiple elements and call `.myWidget()`, a separate widget instance is created for each element. Therefore, this property always contains a single element.
* **namespace**: The location in the global jQuery object where the widget prototype is stored. For example, a `namespace` of `"ui"` means the widget prototype is stored in `$.ui`.
* **options**: An object containing the options currently in use by the widget. During instantiation, any options provided by the user are automatically merged with the defaults defined in `$.myNamespace.myWidget.prototype.options`. User-specified options override the defaults.
* **uuid**: A unique integer representing the widget identifier.
* **version**: A string version of the widget. For jQuery UI widgets, this property is set to the version of jQuery UI used by the widget. Plugin developers must set this property explicitly in their prototype.
* **widgetEventPrefix**: A prefix added to widget event names. For example, the `widgetEventPrefix` of the (#) is `"drag"`, so when a draggable is created, the event name is `"dragcreate"`. By default, the widget's `widgetEventPrefix` is its name. _Note: This property is deprecated and will be removed in a future version. Event names will be changed to widgetName:eventName (e.g., `"draggable:create"`)._
* **widgetFullName**: The full name of the widget, including the namespace. For `$.widget( "myNamespace.myWidget", {} )`, `widgetFullName` will be `"myNamespace-myWidget"`.
* **widgetName**: The name of the widget. For `$.widget( "myNamespace.myWidget", {} )`, `widgetName` will be `"myWidget"`.
* **window**: The `window` containing the widget element. Useful when interacting with widgets inside iframes.
**Description:** The base widget used by the Widget Factory.
### Quick Nav
| Options | Methods | Events |
| --- | --- | --- |
| (#) (#) (#) | (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) (#) | (#) |
| Option | Type | Description | Default |
| --- | --- | --- | --- |
| disabled | Boolean | If set to `true`, disables the widget. **Code Examples:** Initialize a widget with the `disabled` option specified: ```javascript $( ".selector" ).widget({ disabled: true }); ``` After initialization, get or set the `disabled` option: ```javascript // getter var disabled = $( ".selector" ).widget( "option", "disabled" ); // setter $( ".selector" ).widget( "option", "disabled", true ); ``` | false |
| hide | Boolean or Number or String or Object | Whether and how to animate hiding the element. **Multiple types supported:** * **Boolean**: When set to `false`, no animation is used and the element is hidden immediately. When set to `true`, the element fades out with the default duration and default easing. * **Number**: The element fades out with the specified duration and default easing. * **String**: The element is hidden using the specified effect. The value can be the name of a built-in jQuery animation method, such as `"slideUp"`, or the name of a (#), such as `"fold"`. In both cases, the effect uses the default duration and default easing. * **Object**: If the value is an object, the `effect`, `delay`, `duration`, and `easing` properties are provided. If the `effect` property contains the name of a jQuery method, that method is used; otherwise, it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you can include those settings in the object, and they will be passed to the effect. If `duration` or `easing` is omitted, the default value is used. If `effect` is omitted, `"fadeOut"` is used. If `delay` is omitted, no delay is used. **Code Examples:** Initialize a widget with the `hide` option specified: ```javascript $( ".selector" ).widget({ hide: { effect: "explode", duration: 1000 } }); ``` After initialization, get or set the `hide` option: ```javascript // getter var hide = $( ".selector" ).widget( "option", "hide" ); // setter $( ".selector" ).widget( "option", "hide", { effect: "explode", duration: 1000 } ); ``` | null |
| show | Boolean or Number or String or Object | Whether and how to animate showing the element. **Multiple types supported:** * **Boolean**: When set to `false`, no animation is used and the element is shown immediately. When set to `true`, the element fades in with the default duration and default easing. * **Number**: The element fades in with the specified duration and default easing. * **String**: The element is shown using the specified effect. The value can be the name of a built-in jQuery animation method, such as `"slideDown"`, or the name of a (#), such as `"fold"`. In both cases, the effect uses the default duration and default easing. * **Object**: If the value is an object, the `effect`, `delay`, `duration`, and `easing` properties are provided. If the `effect` property contains the name of a jQuery method, that method is used; otherwise, it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you can include those settings in the object, and they will be passed to the effect. If `duration` or `easing` is omitted, the default value is used. If `effect` is omitted, `"fadeIn"` is used. If `delay` is omitted, no delay is used. **Code Examples:** Initialize a widget with the `show` option specified: ```javascript $( ".selector" ).widget({ show: { effect: "blind", duration: 800 } }); ``` After initialization, get or set the `show` option: ```javascript // getter var show = $( ".selector" ).widget( "option", "show" ); // setter $( ".selector" ).widget( "option", "show", { effect: "blind", duration: 800 } ); ``` | null |
| Method | Returns | Description |
| --- | --- | --- |
| _create() | jQuery (plugin only) | The `_create()` method is the widget's constructor. It has no parameters, but `this.element` and `this.options` are already set. * This method does not accept any arguments. **Code Examples:** Set the background color of the widget element based on an option. ```javascript _create: function() { this.element.css( "background-color", this.options.color ); } ``` |
| _delay( fn [, delay ] ) | Number | Calls the provided function after a specified delay. Keeps the `this` context correct. Essentially `setTimeout()`. Use `clearTimeout()` to cancel the timeout ID. * **fn** Type: Function() or String Description: The function to call. Can also be the name of a method on the widget. * **delay** Type: Number Description: The number of milliseconds to wait before calling the function, defaults to `0`. **Code Examples:** Call the `_foo()` method on the widget after 100 milliseconds. ```javascript this._delay( this._foo, 100 ); ``` |
| _destroy() | jQuery (plugin only) | The public [`destroy()`](#) method clears all public data, events, etc. The `_destroy()` method is for customizing, specific widget cleanup. * This method does not accept any arguments. **Code Examples:** Remove a class from the widget element when the widget is destroyed. ```javascript _destroy: function() { this.element.removeClass( "my-widget" ); } ``` |
| _focusable( element ) | jQuery (plugin only) | Establishes `element` to apply the `ui-state-focus` class when focused. * **element** Type: jQuery Description: The element to apply focusable behavior to. **Code Examples:** Apply focusable styles to a set of elements inside the widget: ```javascript this._focusable( this.element.find( ".my-items" ) ); ``` |
| _getCreateEventData() | Object | All widgets trigger the [`create`](#) event. By default, no data is provided in the event, but this method returns an object that is passed as the data for the `create` event. * This method does not accept any arguments. **Code Examples:** Pass the widget's options to the `create` event handler as an argument. ```javascript _getCreateEventData: function() { return this.options; } ``` |
| _getCreateOptions() | Object | This method allows the widget to define a custom method for defining options during initialization. User-provided options will override the options returned by this method, which in turn override the default options. * This method does not accept any arguments. **Code Examples:** Make the widget element's `id` attribute available as an option. ```javascript _getCreateOptions: function() { return { id: this.element.attr( "id" ) }; } ``` |
| _hide( element, option [, callback ] ) | jQuery (plugin only) | Hides an element using built-in animation methods or a custom effect. For possible `option` values, see (#). * **element** Type: jQuery Description: The element to hide. * **option** Type: Object Description: Settings defining how to hide the element. * **callback** Type: Function() Description: The callback to invoke after the element is fully hidden. **Code Examples:** Pass the `hide` option for custom animation. ```javascript this._hide( this.element, this.options.hide, function() { // Remove the element from the DOM when it's fully hidden. $( this ).remove(); }); ``` |
| _hoverable( element ) | jQuery (plugin only) | Establishes `element` to apply the `ui-state-hover` class when hovered. Event handlers are automatically cleaned up on destroy. * **element** Type: jQuery Description: The element to apply hoverable behavior to. **Code Examples:** Apply hoverable styles to all `div`s inside the element when hovered. ```javascript this._hoverable( this.element.find( "div" ) ); ``` |
| _init() | jQuery (plugin only) | The concept of widget initialization is separate from creation. Any time the plugin is called without arguments or with only an options hash, the widget is initialized. This method is included when the widget is created. Note: Initialization only handles logic that should be executed when the widget is successfully called without arguments. * This method does not accept any arguments. **Code Examples:** Call the `open()` method if the `autoOpen` option is set. ```javascript _init: function() { if ( this.options.autoOpen ) { this.open(); } } ``` |
| _off( element, eventName ) | jQuery (plugin only) | Unbinds event handlers from the specified element. * **element** Type: jQuery Description: The element to unbind event handlers from. Unlike the `_on()` method, the element is required in the `_off()` method. * **eventName** Type: String Description: One or more space-separated event types. **Code Examples:** Unbind all click events from the widget's element. ```javascript this._off( this.element, "click" ); ``` |
| _on( [, element ], handlers ) | jQuery (plugin only) | Enables event delegation via a selector within the event name, e.g., `"click .foo"`. The `_on()` method provides several benefits over direct event binding: * Maintains the appropriate `this` context within the handler. * Automatically handles disabled widgets: If the widget is disabled or the event occurs on an element with the `ui-state-disabled` class, the event is ignored. * **suppressDisabledCheck** Type: Boolean Description: By default, when a widget is disabled, event handlers bound via `_on()` are not invoked. Set this to `true` to bypass this check. * **element** Type: jQuery Description: The element to bind the event handlers to. If not provided, defaults to `this.element`. * **handlers** Type: Object Description: A map of event names to handler functions. **Code Examples:** Bind a click handler to the widget's element. ```javascript this._on( this.element, { click: function( event ) { // Handle the click event. } }); ``` Bind a click handler to the document, bypassing the disabled check. ```javascript this._on( true, this.document, { click: function( event ) { // This handler will be invoked even if the widget is disabled. } }); ``` |
| _setOption( key, value ) | jQuery (plugin only) | Sets a single option value. This method is called by the public [`option()`](#) method and can be overridden by widgets to perform custom logic when an option changes. * **key** Type: String Description: The name of the option to set. * **value** Type: Object Description: The value to set for the option. **Code Examples:** Override `_setOption` to update the widget's appearance when the `color` option changes. ```javascript _setOption: function( key, value ) { this._super( key, value ); if ( key === "color" ) { this.element.css( "background-color", value ); } } ``` |
| _setOptions( options ) | jQuery (plugin only) | Sets multiple option values. This method is called by the public [`option()`](#) method and can be overridden by widgets to perform custom logic when options change. * **options** Type: Object Description: A map of option names to values to set. **Code Examples:** Override `_setOptions` to update the widget's appearance when any option changes. ```javascript _setOptions: function( options ) { this._super( options ); this.element.css( "background-color", this.options.color ); } ``` |
| _show( element, option [, callback ] ) | jQuery (plugin only) | Shows an element using built-in animation methods or a custom effect. For possible `option` values, see (#). * **element** Type: jQuery Description: The element to show. * **option** Type: Object Description: Settings defining how to show the element. * **callback** Type: Function() Description: The callback to invoke after the element is fully shown. **Code Examples:** Pass the `show` option for custom animation. ```javascript this._show( this.element, this.options.show, function() { // The element is now fully visible. }); ``` |
| _super( args ) | Object | Calls the method of the same name on the parent widget. This is used to call methods from the base widget that have been overridden. * **args** Type: Object Description: The arguments to pass to the parent method. **Code Examples:** Call the parent widget's `_create` method. ```javascript _create: function() { this._super(); // Additional initialization logic. } ``` |
| _superApply( args ) | Object | Calls the method of the same name on the parent widget, passing an array of arguments. This is used to call methods from the base widget that have been overridden, when the arguments are already in an array. * **args** Type: Array Description: An array of arguments to pass to the parent method. **Code Examples:** Call the parent widget's `_create` method with an array of arguments. ```javascript _create: function() { this._superApply( arguments ); // Additional initialization logic. } ``` |
| _trigger( type, event, data ) | Boolean | Triggers an event. This method is used internally by widgets to trigger events. * **type** Type: String Description: The type of event to trigger. * **event** Type: Event Description: The original event object, if any. * **data** Type: Object Description: Additional data to pass to the event handler. **Code Examples:** Trigger a custom `change` event. ```javascript this._trigger( "change", null, { value: this.options.value } ); ``` |
| destroy() | jQuery (plugin only) | Removes the widget functionality from the element, returning the element to its pre-init state. This method calls the widget's `_destroy()` method. * This method does not accept any arguments. **Code Examples:** Destroy the widget. ```javascript $( ".selector" ).widget( "destroy" ); ``` |
| disable() | jQuery (plugin only) | Disables the widget. * This method does not accept any arguments. **Code Examples:** Disable the widget. ```javascript $( ".selector" ).widget( "disable" ); ``` |
| enable() | jQuery (plugin only) | Enables the widget. * This method does not accept any arguments. **Code Examples:** Enable the widget. ```javascript $( ".selector" ).widget( "enable" ); ``` |
| option( optionName ) | Object | Gets the value currently associated with the specified `optionName`. * **optionName** Type: String Description: The name of the option to get. **Code Examples:** Get the current value of the `disabled` option. ```javascript var disabled = $( ".selector" ).widget( "option", "disabled" ); ``` |
| option() | Object | Gets an object containing key/value pairs representing the current options. * This method does not accept any arguments. **Code Examples:** Get all current options. ```javascript var options = $( ".selector" ).widget( "option" ); ``` |
| option( optionName, value ) | jQuery (plugin only) | Sets the value of the widget option associated with the specified `optionName`. * **optionName** Type: String Description: The name of the option to set. * **value** Type: Object Description: The value to set for the option. **Code Examples:** Set the `disabled` option to `true`. ```javascript $( ".selector" ).widget( "option", "disabled", true ); ``` |
| option( options ) | jQuery (plugin only) | Sets one or more options for the widget. * **options** Type: Object Description: A map of option names and values to set. **Code Examples:** Set multiple options at once. ```javascript $( ".selector" ).widget( "option", { disabled: true, color: "red" } ); ``` |
| widget() | jQuery (plugin only) | Returns a jQuery object containing the widget element. * This method does not accept any arguments. **Code Examples:** Get the widget element. ```javascript var widgetElement = $( ".selector" ).widget( "widget" ); ``` |
| Event | Type | Description |
| --- | --- | --- |
| create( event, ui ) | create | Triggered when the widget is created. * **event** Type: Event Description: The original event object. * **ui** Type: Object Description: An empty object. **Code Examples:** Bind to the `create` event. ```javascript $( ".selector" ).widget({ create: function( event, ui ) { // Handle the create event. } }); ``` Bind to the `create` event via event delegation. ```javascript $( ".selector" ).on( "widgetcreate", function( event, ui ) { // Handle the create event. }); ``` |