Individual Widgets

This article describes the specifics of working with widgets unrelated to any category.

See Also

dxButton

The dxButton widget is a button, which executes a specified action when clicked.

View Demo

The action executed by a click should be passed to the onClick option.

JavaScript
var buttonOptions = {
    onClick: function() {
        alert("The button is clicked");
    }
}

The widget can display a text and an icon on the button. The text is specified using the text option. You can specify the button icon using either the icon option or iconSrc option.

You can pass the name of an existing icon from the built-in icon library or a custom icon name to the icon option.

JavaScript
var buttonOptions = {
    text: 'Click me',
    icon: 'home'
}

The iconSrc option specifies the URL pointing to the image to be displayed on the button.

JavaScript
var buttonOptions = {
    text: 'Click me',
    iconSrc: '/images/icons/buttonIcon.png'
}

In addition, you can specify the type of the displayed button using the type option, which accepts any of the following values: 'normal', 'default', 'back', 'danger', 'success'.

JavaScript
var buttonOptions = {
    text: 'Return',
    type: 'back'
}

If the button is focused, an end-user can use the Enter or Space key to perform a click.

dxLoadIndicator

The dxLoadIndicator widget is a UI element displayed when the loading process is being executed.

View Demo

You can control widget visibility using the visible option.

Get the widget instance and call the option(optionName, optionValue) method to update the visible option value.

JavaScript
var showLoadIndicator = function(){
    var loadIndicator = $("#loadIndicatorContainer").dxLoadIndicator("instance");
    loadIndicator.option("visible", true);
}
var hideLoadIndicator = function(){
    var loadIndicator = $("#loadIndicatorContainer").dxLoadIndicator("instance");
    loadIndicator.option("visible", false);
}

In MVVM Approach, provide two-way binding between the visible option and the corresponding variable.

Angular Approach
JavaScript
function Controller($scope) {
    $scope.visible = false;
    $scope.showLoadIndicator = function() {
        $scope.visible = true;
    };
    $scope.hideLoadIndicator = function() {
        $scope.visible = false;
    }
}
HTML
<div ng-controller="Controller">
    <div dx-load-indicator="{ bindingOptions: { 'visible': 'indicatorVisible' } }"></div>
</div>
Knockout Approach
JavaScript
var viewModel = {
    indicatorVisible: ko.observable(false);
    showLoadIndicator: function(){
        this.indicatorVisible(true);
    },
    hideLoadIndicator: function(){
        this.indicatorVisible(false);
    }
}
ko.applyBindings(viewModel);
HTML
<div data-bind="dxLoadIndicator: { visible: indicatorVisible }"></div>

You can use a custom image as an indicator instead of the standard indicator icons. Assign the image path to the indicatorSrc option to specify the indicator image.

JavaScript
var loadIndicatorOptions = {
    indicatorSrc: '/Content/Images/loadindicator-demo.gif'
}

dxMap

The dxMap widget displays a map at the specified location using a specified zoom level. It can also display markers and routes. Refer to the dxMap widget guide for more information.

View Demo

dxScrollView

The dxScrollView widget is a wrapper for scrollable content. Scrollable content is placed inside the dxScrollView container.

View Demo

End-user Gestures

The widget supports the "Pull Down to Refresh" gesture. Assign the required function to the onPullDown option to perform a custom action after the widget is scrolled to the top and pulled down. When the function is called, the widget gets into the "refreshing" state. You should call the release() method at the end of the action to release the widget. You can access the widget instance using the component property of the action parameter object.

JavaScript
var scrollViewOptions = {
    onPullDown: pulledDown
}
var pulledDown = function(actionOptions){
    alert("The widget is pulled down.");
    actionOptions.component.refresh();
}

You can also specify the text displayed when the widget is about to be pulled down and when it is pulled down using the pullingDownText and pulledDownText options respectively. The refreshingText option specifies the text displayed while the widget is being refreshed.

JavaScript
var scrollViewOptions = {
    onPullDown: pulledDown,
    pullingDownText: 'Pull down to refresh',
    pulledDownText: 'Release to refresh',
    refreshingText: 'Refreshing...'
}

If an end-user scrolls the widget to the bottom, the widget executes the function passed to the onReachBottom option and displays the text assigned to the reachBottomText option.

JavaScript
var reachedBottom = function(){
    alert("The widget is scrolled to the bottom.");
    actionOptions.component.refresh();
}
var scrollViewOptions = {
    onReachBottom: reachedBottom,
    reachBottomText: 'Loading...'
}

You can also pass a function to the onScroll option to process each scroll gesture.

JavaScript
var scrolled = function(){
    alert("The widget is scrolled.");
}
var scrollViewOptions = {
    onScroll: scrolled
}

Scrolling Options

By default, the widget can be scrolled only vertically. Use the direction option to enable scrolling in vertical, horizontal or in both directions. The showScrollBar option specifies whether the scrollbars are visible or not.

JavaScript
var scrollViewOptions = {
    direction: 'both'
}

Programmatic Scrolling

The dxScrollView widget includes multiple methods used to scroll the widget to the required position. Refer to the widget API reference for the information on these methods.

JavaScript
var scrollToTargetPosition(target){
    var scrollView = $("#scrollViewContainer").dxScrollView("instance");
    scrollView.scrollTo(target);
}

Keyboard Support

An end-user can use the following keys to interact with the widget.

  • Up/down arrow
    Scrolls content up/down.

  • Page up/down
    Scrolls content up/down by a page.

  • Home/End
    Scrolls content to the top/bottom.