ScrollView Methods

This section describes the members used to manipulate the widget.

beginUpdate()

Prevents the component from refreshing until the endUpdate method is called.

The beginUpdate and endUpdate methods allow you to apply several modifications to the component. After the beginUpdate method is called, the component does not update the UI until the endUpdate method is called. The usage of these methods prevents excessive component updating when you are changing multiple component settings at once.

clientHeight()

Returns the height of the scrollable widget in pixels.

Return Value: Number
The value of the widget height in pixels.

clientWidth()

Returns the width of the scrollable widget in pixels.

Return Value: Number
The value of the widget width in pixels.

content()

An HTML element of the widget.

Return Value: jQuery
An element representing in widget.

defaultOptions(rule)

Specifies the device-dependent default configuration options for this component.

Parameters:
rule: Object
An object specifying default options for the component and the device for which the options must be applied.
Object structure:
device: Object|Array|function
An object representing device parameters, or an array of objects representing device parameters, or a function that provides information on the current device as an input parameter and returning a Boolean value.
options: Object
A configuration object with specified options.

The defaultOptions method is a static method supported by the widget class. The following code demonstrates how to specify default options for all buttons in the application executed on the iOS platform.

JavaScript
DevExpress.ui.dxButton.defaultOptions({ 
    device: { platform: "ios" },
    options: {
        text: "Click me"
    }
});

element()

Returns the root HTML element of the widget.

Return Value: jQuery
The root element of the widget.

endUpdate()

Enables the component to refresh after the beginUpdate method call.

The beginUpdate and endUpdate methods allow you to apply several modifications to the component. After the beginUpdate method is called, the component does not update the UI until the endUpdate method is called. The usage of these methods prevents excessive component updating when you change multiple component setting at once.

instance()

Returns an instance of this component class.

Return Value: Object
An instance of this component class

Use this method to access other methods of the component.

off(eventName)

Detaches all event handlers from the specified event.

Parameters:
eventName: String
The name of the event to unsubscribe from.
Return Value: Object
The object for which this method is called.

For details on using methods for handling events, refer to the Handle Events topic.

off(eventName, eventHandler)

Detaches a particular event handler from the specified event.

Parameters:
eventName: String
The name of the event to unsubscribe from.
eventHandler: function
The handler to be detached from the specified event.
Return Value: Object
The object for which this method is called.

For details on using methods for handling events, refer to the Handle Events topic.

on(eventName, eventHandler)

Subscribes to a specified event.

Parameters:
eventName: String
The name of the event to be subscribed.
eventHandler: function
An event handler for the specified event.
Return Value: Object
The object for which this method is called.

Use this method to subscribe to one of the events listed in the Events section.

For details on using methods for handling events, refer to the Handle Events topic.

on(events)

Subscribes to the specified events.

Parameters:
events: Object
An object of the following structure: { "eventName1": handler1, "eventName2": handler2, ...}
Return Value: Object
The object for which this method is called.

Use this method to subscribe to several events at one method call. Available events are listed in the Events section.

For details on using methods for handling events, refer to the Handle Events topic.

option()

Returns the configuration options of this component.

Return Value: Object
An object representing the configuration options of this component.

option(optionName)

Gets the value of the specified configuration option of this component.

Parameters:
optionName: String
The name of the option to get.
Return Value: any
The value of the specified option.

If you need to get the value of a configuration option field, specify the path to the required field.

option(optionName, optionValue)

Sets a value to the specified configuration option of this component.

Parameters:
optionName: String
The name of the required option.
optionValue: any
The value you wish to assign to the required option.

To set a value to the configuration option field, specify the path to the required field.

option(options)

Sets one or more options of this component.

Parameters:
options: Object
An object containing the required configuration options.

refresh()

Locks the widget until the release(preventScrollBottom) method is called and executes the function passed to the onPullDown option and the handler assigned to the pullDown event.

release(preventScrollBottom)

Notifies the scroll view that data loading is finished.

Parameters:
preventScrollBottom: Boolean
Indicates whether or not to prevent reachBottom action execution.
Return Value: jQuery.Promise
A Deferred jQuery object.

Use this method to hide the load indicator and release the scroll view after the pullDown or reachBottom events have been raised.

Show Example:
jQuery
<div id="scrollView" style="background-color:lightGray; color: black;" data-bind="dxScrollView: {
  onPullDown: pullDown,
  onReachBottom: reachBottom
}">
  <div id="textContainer"></div>
</div><br/>
nextParagraph = 0;
paragraphCount = 20;

//Loads new content to scrollView if reload is true. Otherwise adds 5 paragraphs to scroll view.
loadScrollViewData = function (reload) {
    if (reload) {
        nextParagraph = 0;
        $("#textContainer").empty();
        paragraphCount = 20;
    }
    $.ajax({
        type: "POST",
        url: "/LoremService.asmx/LoremIpsum",
        data: JSON.stringify({ count: paragraphCount }),
        contentType: "application/json; charset=utf-8",
        dataType: "json",
        success: function (data) {
            var targetParagraph = nextParagraph + 5 < paragraphCount ? nextParagraph + 5 : paragraphCount;
            while (nextParagraph < targetParagraph) {
                $("#textContainer").append("<p>" + data.d[nextParagraph] + "</p>");
                nextParagraph++;
            }
            $("#scrollView").dxScrollView("instance").release();
        }
    });
};

//pullDown action
pullDown = function () {
    loadScrollViewData(true);
};

//reachBottom action
reachBottom = function () {
    if (nextParagraph < paragraphCount)
        loadScrollViewData(false);
    else
        $("#scrollView").dxScrollView("instance").release();
};

loadScrollViewData(true);
body{
  text-align: center;
}
.button{
  margin:10px;
}
#scrollView{
  margin: 10px;
  height: 80%;
}

scrollBy(distance)

Scrolls the widget content by the specified number of pixels.

Parameters:
distance: Number
A distance to be scrolled in pixels.

Show Example:
jQuery
<div id="scrollView" data-bind="dxScrollView: {  }">
  <div id="textContainer"></div>
</div><br/>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label" data-bind="dxButton: { text: 'Scroll by', onClick: doScroll }"></div>
    <div class="dx-field-value" data-bind="dxNumberBox: { value: scrollDistance, min: -1000, max: 1000 }"></div>
  </div>
</div>

scrollDistance = ko.observable(200);

//Scrolls the widget content by the "scrollDistance" value
doScroll = function () {
    $("#scrollView").dxScrollView("instance").scrollBy(scrollDistance());
};

//Loads the scroll view content
$.ajax({
    type: "POST",
    url: "/LoremService.asmx/LoremIpsum",
    data: JSON.stringify({ count: Math.ceil(Math.random() * 30) }),
    contentType: "application/json; charset=utf-8",
    dataType: "json",
    success: function (data) {
        $.each(data.d, function (index, value) {
            $("#textContainer").append("<p>" + value + "</p>");
        });
    }
});
body{
  text-align: center;
}
#scrollView{
  margin: 10px;
  height: 60%;
}

scrollBy(distanceObject)

Scrolls widget content by the specified number of pixels in horizontal and vertical directions.

Parameters:
distanceObject: Object
An object specifying a distance to be scrolled in pixels.

The function's parameter should be an object in the following format - { left: value1, top: value2 } - where the left field is the distance to be scrolled in a horizontal direction and the top field is the distance to be scrolled in a vertical direction.

scrollHeight()

Returns the height of the scrollable content in pixels.

Return Value: Number
The value of the content height in pixels.

scrollLeft()

Returns the current scroll position against the leftmost position.

Return Value: Number
The requested scroll position.

scrollOffset()

Returns how far the scrollable content is scrolled from the top and from the left.

Return Value: Object
An object in the following format: { top: *scrollTop*, left: *scrollLeft* }, where *scrollTop* and *scrollLeft* are the left and top scroll offsets respectively.

scrollTo(targetLocation)

Scrolls widget content to the specified position.

Parameters:
targetLocation: Number
A position to scroll to, in pixels.

Show Example:
jQuery
<div id="scrollView" data-bind="dxScrollView: {  }">
  <div id="textContainer"></div>
</div><br/>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label" data-bind="dxButton: { text: 'Scroll to', onClick: doScroll }"></div>
    <div class="dx-field-value" data-bind="dxNumberBox: { value: scrollPosition, min: 0, max: 5000 }"></div>
  </div>
</div>
scrollPosition = ko.observable(300);

//Scrolls the widget content to the "scrollPosition" position
doScroll = function () {
  $("#scrollView").dxScrollView("instance").scrollTo(scrollPosition());
};

//Loads the scroll view content
$.ajax({
    type: "POST",
    url: "/LoremService.asmx/LoremIpsum",
    data: JSON.stringify({ count: Math.ceil(Math.random() * 30) }),
    contentType: "application/json; charset=utf-8",
    dataType: "json",
    success: function (data) {
        $.each(data.d, function (index, value) {
            $("#textContainer").append("<p>" + value + "</p>");
        });
    }
});
body{
  text-align: center;
}
#scrollView{
  margin: 10px;
  height: 60%;
}

scrollTo(targetLocationObject)

Scrolls widget content to a specified position.

Parameters:
targetLocation: Object
An object specifying the target location after scrolling in pixels.

The function's parameter should be an object in the following format: { left: value1, top: value2 }, where the left field is the target location in a horizontal direction, and the top field is the target location in a vertical direction.

scrollToElement(targetLocation)

Scrolls widget content to the specified element.

Parameters:
element: DOM Node|jQuery
A DOM Node or jQuery object the widget should scroll to.

scrollTop()

Returns the current scroll position against the topmost position.

Return Value: Number
The requested scroll position.

scrollWidth()

Returns the width of the scrollable content in pixels.

Return Value: Number
The value of the content width in pixels.

update()

Updates the dimensions of the scrollable contents.

Use this method to fit the widget contents to the widget size after it (size) has been changed.

This function returns a resolved promise of the jQuery Deferred object when the update is complete.

Show Example:
AngularJS
Knockout
jQuery
<div ng-controller="demoController" style="height:100%;">
    <div class="button" dx-button="{ text: 'Resize scroll view', onClick: resizeScrollView }"></div>
    <div dx-check-box="{
        text: 'Update scroll view on resize',
        bindingOptions: {
            value: 'updateScrollView'
        }
    }"></div>
    <div id="myScrollView" dx-scroll-view="{}">
        <div id="textContainer"></div>
    </div>
</div>
//Loads scroll view content
$.ajax({
    type: "POST",
    url: "/LoremService.asmx/LoremIpsum",
    data: JSON.stringify({ count: 4 }),
    contentType: "application/json; charset=utf-8",
    dataType: "json",
    success: function (data) {
        $.each(data.d, function (index, value) {
            $("#textContainer").append("<p>" + value + "</p>");
        });
        $("#textContainer").append("<div id='end'>");
        scrollToEnd();
    }
});
var scrollViewHeight = 30;
//Scrolls widget content to the bottom
var scrollToEnd = function () {
    $("#myScrollView").dxScrollView("instance").scrollToElement($("#end"));
    $("#myScrollView").dxScrollView("instance").update(true);
};
var myApp = angular.module('myApp', ['dx']);
myApp.controller("demoController", function ($scope) {
    $scope.updateScrollView = false;
    $scope.resizeScrollView = function () {
        if (scrollViewHeight >= 70) {
            scrollViewHeight = 30;
            setTimeout(scrollToEnd, 500);
        }
        else
            scrollViewHeight += 10;
        $("#myScrollView").css({ height: scrollViewHeight + '%' });
        if ($scope.updateScrollView)
            $("#myScrollView").dxScrollView("instance").update(true);
    };
});
angular.element(document).ready(function () {
    angular.bootstrap(document, ['myApp']);
});
setTimeout(scrollToEnd, 500);
p{
    padding: 5px 10px;
    margin: 0;
}
.dx-button{
    margin: 10px;
}
.dx-checkbox{
    margin:10px;
}
#myScrollView{
    margin: 10px;
    height: 30%;
    background-color:lightGray;
    color: black;
}
<div data-bind="dxButton: { text: 'Resize scroll view', onClick: resizeScrollView }"></div>
<div data-bind="dxCheckBox: { text: 'Update scroll view on resize', value: updateScrollView }"></div>
<div id="myScrollView" style="" data-bind="dxScrollView: {}">
    <div id="textContainer"></div>
</div>
//Loads scroll view content
$.ajax({
    type: "POST",
    url: "/LoremService.asmx/LoremIpsum",
    data: JSON.stringify({ count: 4 }),
    contentType: "application/json; charset=utf-8",
    dataType: "json",
    success: function (data) {
        $.each(data.d, function (index, value) {
            $("#textContainer").append("<p>" + value + "</p>");
        });
        $("#textContainer").append("<div id='end'>");
        scrollToEnd();
    }
});
var scrollViewHeight = 30;
//Scrolls widget content to the bottom
var scrollToEnd = function () {
    $("#myScrollView").dxScrollView("instance").scrollToElement($("#end"));
    $("#myScrollView").dxScrollView("instance").update(true);
};
var myViewModel = {
    updateScrollView: ko.observable(false),
    resizeScrollView: function () {
        if (scrollViewHeight >= 70) {
            scrollViewHeight = 30;
            setTimeout(scrollToEnd, 500);
        }
        else
            scrollViewHeight += 10;
        $("#myScrollView").css({ height: scrollViewHeight + '%' });
        if (this.updateScrollView())
            $("#myScrollView").dxScrollView("instance").update(true);
    }
}
ko.applyBindings(myViewModel);
setTimeout(scrollToEnd, 500);
p{
    padding: 5px 10px;
    margin: 0;
}
.dx-button{
    margin: 10px;
}
.dx-checkbox{
    margin:10px;
}
#myScrollView{
    margin: 10px;
    height: 30%;
    background-color:lightGray;
    color: black;
}
<div id="resizeButton"></div>
<div id="updateSelector"></div>
<div id="myScrollView">
    <div id="textContainer"></div>
</div>
//Loads scroll view content
$.ajax({
    type: "POST",
    url: "/LoremService.asmx/LoremIpsum",
    data: JSON.stringify({ count: 4 }),
    contentType: "application/json; charset=utf-8",
    dataType: "json",
    success: function (data) {
        $.each(data.d, function (index, value) {
            $("#textContainer").append("<p>" + value + "</p>");
        });
        $("#textContainer").append("<div id='end'>");
        scrollToEnd();
    }
});
var scrollViewHeight = 30;
//Scrolls widget content to the bottom
var scrollToEnd = function () {
    $("#myScrollView").dxScrollView("instance").scrollToElement($("#end"));
    $("#myScrollView").dxScrollView("instance").update(true);
};
var updateScrollView = false;
$("#myScrollView").dxScrollView();
$("#resizeButton").dxButton({
    text: "Resize scroll view",
    onClick: function () {
        if (scrollViewHeight >= 70) {
            scrollViewHeight = 30;
            setTimeout(scrollToEnd, 500);
        }
        else
            scrollViewHeight += 10;
        $("#myScrollView").css({ height: scrollViewHeight + '%' });
        if (updateScrollView)
            $("#myScrollView").dxScrollView("instance").update(true);
    }
});
$("#updateSelector").dxCheckBox({
    text: "Update scroll view on resize",
    onValueChanged: function (e) {
        updateScrollView = e.value;
    }
});
setTimeout(scrollToEnd, 500);
p{
    padding: 5px 10px;
    margin: 0;
}
.dx-button{
    margin: 10px;
}
.dx-checkbox{
    margin:10px;
}
#myScrollView{
    margin: 10px;
    height: 30%;
    background-color:lightGray;
    color: black;
}