Main Content

scroll

Scroll to location within component

collapse all in page

Syntax

scroll(container,vlocation)
scroll(container,hlocation)
scroll(container,hlocation,vlocation)
scroll(container,comp)
scroll(container,x,y)
scroll(container,coord)
scroll(txa,vlocation)
scroll(tr,vlocation)
scroll(tr,treenode)
scroll(lb,vlocation)
scroll(lb,item)
scroll(lb,itemdata)
scroll(tbl,vlocation)
scroll(tbl,hlocation)
scroll(tbl,tableTarget,tableIndex)

Description

Scrollable Container or Button Group

scroll(container,vlocation) scrolls a container or button group vertically. Specify vlocation as 'top' or 'bottom'. For more information on when scrolling is possible, see Conditions that Enable Scrolling.

scroll(container,hlocation) scrolls horizontally. Specify hlocation as 'left' or 'right'.

scroll(container,hlocation,vlocation) scrolls both vertically and horizontally to a corner. For example, scroll(container,'right','bottom') scrolls to the bottom-right corner of the component.

example

scroll(container,comp) scrolls to the specified component in the container.

example

scroll(container,x,y) scrolls to the specified (x, y) coordinates. The coordinates are measured in pixels from the bottom-left corner of the container or button group.

example

scroll(container,coord) specifies pixel coordinates as a two-element vector coord. For example, scroll(container,[100 150]) scrolls the container or button group to coordinates (100,150).

Text Area

scroll(txa,vlocation) scrolls a text area vertically. Specify vlocation as 'top' or 'bottom'.

example

Tree

scroll(tr,vlocation) scrolls a tree vertically. Specify vlocation as 'top' or 'bottom'.

scroll(tr,treenode) scrolls to the specified tree node.

example

List Box

scroll(lb,vlocation) scrolls a list box vertically. Specify vlocation as 'top' or 'bottom'.

scroll(lb,item) scrolls to the specified item of a list box.

example

scroll(lb,itemdata) scrolls to the item of a list box with the specified item data. If there are multiple items with the same item data, the function scrolls to the first one.

Table

scroll(tbl,vlocation) scrolls a table vertically. Specify vlocation as 'top' or 'bottom'.

scroll(tbl,hlocation) scrolls a table horizontally. Specify hlocation as 'left' or 'right'.

scroll(tbl,tableTarget,tableIndex) scrolls to the specified row, column, or cell of a table. For example, scroll(uit,'Row',10) scrolls to the tenth row of the table.

example

Examples

collapse all

Scroll to specified (x,y)-coordinates within a figure created using the uifigure function.

Create a figure, and set the Scrollable property to 'on'. Then add five child components. To ensure that the figure is scrollable, place the first component above the top edge of the figure. Then space the components far enough apart so that they cannot fit within the figure together.

% Create figure
fig = uifigure('Name','Customer','Scrollable','on');
fig.Position = [100 100 493 283];

% Title label
title = uilabel(fig,'Text','Customer Record');
title.FontSize = 18;
title.FontWeight = 'bold';
title.Position = [173 315 157 22];

% Name
name = uieditfield(fig,'text');
name.Position = [169 239 173 22];
namelabel = uilabel(fig,'Text','Name','HorizontalAlignment','right');
namelabel.Position = [116 239 38 22];

% Phone
phone = uieditfield(fig,'text');
phone.Position = [169 164 173 22];
phonelabel = uilabel(fig,'Text','Phone','HorizontalAlignment','right');
phonelabel.Position = [114 164 40 22];

% Balance
balance = uieditfield(fig,'numeric');
balance.Position = [169 89 173 22];
balancelabel = uilabel(fig,'Text','Balance','HorizontalAlignment','right');
balancelabel.Position = [105 89 49 22];

% Submit button
button = uibutton(fig,'push','Text','Submit');
button.Position = [169 14 173 22];

UI figure window with a form to fill out a customer record. The window is vertically scrollable.

By default, MATLAB® scrolls to the upper-left corner of the area that encloses the child components.

Scroll to location (1,1), which is the bottom of the figure.

scroll(fig,1,1)

UI figure window with a form to fill out a customer record. The window is scrolled to the bottom.

Bring child components of a scrollable grid layout into view by specifying pixel coordinates or a location name.

Create a 5-by-2 grid layout and set the Scrollable property of the grid to 'on'. Then add a label, a table, and a panel to the grid. Set the Scrollable property of the panel to 'off' and then add a chart to the panel.

fig = uifigure('Position',[782 497 435 311]);
g = uigridlayout(fig,'Scrollable','on');
g.RowHeight = {22,40,22,22,400};
g.ColumnWidth = {400,400};

lbl = uilabel(g,'Text','Tsunamis');
lbl.Layout.Row = 2;
lbl.Layout.Column = [1,2];
lbl.HorizontalAlignment = 'center';
lbl.FontSize = 28;

tsunamis = readtable('tsunamis.xlsx');
tsunamis.Cause = categorical(tsunamis.Cause);
t = uitable(g,'Data',tsunamis);
t.Layout.Row = [3,5];
t.Layout.Column = 2;

p = uipanel(g);
p.Scrollable = 'off';
p.Layout.Row = [3,5];
p.Layout.Column = 1;
gb = geobubble(p,tsunamis.Latitude,tsunamis.Longitude,...
    tsunamis.MaxHeight,tsunamis.Cause);

Scrollable UI figure window with the upper-left portion of the grid visible

Scroll to a location in the grid.

scroll(g,100,-30)

UI figure window scrolled 100 pixels to the right and 30 pixels down

Now use location names to scroll to the bottom-right corner of the grid.

scroll(g,'bottom','right')

UI figure window scrolled fully to the right and down, so that the lower-right portion of the grid is visible

Bring a component into view by specifying it as the scroll location.

Create a figure with two drop-down components, a list box, and a table. Position the components so that they cannot all be displayed within the figure at one time.

fig = uifigure;
fig.Scrollable = 'on';
fig.Position = [100 300 328 110];

dd1 = uidropdown(fig);
dd1.Position = [20 360 120 22];

dd2 = uidropdown(fig);
dd2.Position = [20 200 120 22];

lb = uilistbox(fig);
lb.Position = [230 300 120 80];

t = readtable('patients.xls');
uit = uitable(fig,'Data',t);
uit.Position = [375 100 300 300];

Scrollable UI figure window. The window is scrolled to the top left, and the drop-down and list box components are visible.

Scroll to the table.

scroll(fig,uit)

Scrollable UI figure window. The table component is visible.

Scroll to the bottom of a text area programmatically.

Create a text area. Specify a size and long text for it.

fig = uifigure;
txa = uitextarea(fig);
txa.Position = [100 100 80 80];
txa.Value = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor.";

Text area in a UI figure window. The text area is vertically scrollable.

Scroll to the bottom of the text area.

scroll(txa,"bottom")

Text area in a UI figure window. The text area is scrolled to the bottom.

Bring an item of a list box into view by specifying the item.

Create a list box containing a list of names with associated ItemsData.

fig = uifigure('Position',[680 678 300 200]);
list = uilistbox(fig, 'Position',[70 50, 150 78]);
list.Items = {'Diane Fitzsimmons', 'Naomi Becker', 'Nick Stewart',...
           'Alex Bradford', 'Caroline Eliot', 'Leslie Bond', ...
           'Aaron Silberlicht', 'Ramu Sadasiv', 'Joyce Wu',...
           'Ann Shanahan'};
list.ItemsData = [1 2 3 4 5 6 7 8 9 10];

List box in a UI figure window. The list box displays the first four names and is vertically scrollable.

Scroll to Caroline Eliot. 

scroll(list,'Caroline Eliot')

List box in a UI figure window. The list box is scrolled so that the name "Caroline Eliot" is displayed at the bottom of the visible items.

Select Caroline Eliot by setting the Value property to the corresponding element in the ItemsData property.

list.Value = 5;

List box in a UI figure window. The item "Caroline Eliot" is highlighted.

Bring a tree node into view by specifying the TreeNode object.

Create a tree containing four top-level nodes that each have child nodes.

fig = uifigure;
tree = uitree(fig,'Position',[20 20 175 100]);
    
% First level nodes
category1 = uitreenode(tree,'Text','Runners');
category2 = uitreenode(tree,'Text','Cyclists');
category3 = uitreenode(tree,'Text','Hikers');
category4 = uitreenode(tree,'Text','Swimmers');

% Second level nodes
r1 = uitreenode(category1,'Text','Joe');
r2 = uitreenode(category1,'Text','Linda');
c1 = uitreenode(category2,'Text','Rajeev');
h1 = uitreenode(category3,'Text','Jack');
s1 = uitreenode(category4,'Text','Logan');

Tree component in a UI figure window. All top-level nodes are collapsed and visible.

Expand the nodes, so that Swimmers scrolls out of view.

expand(tree)

Tree component in a UI figure window. All nodes are expanded, and the Swimmers node is not visible. The tree is vertically scrollable.

Scroll to the Swimmers node.

scroll(tree,category4)

Tree component in a UI figure window. The Swimmers node is visible.

Select the Swimmers node by setting the SelectedNodes property of the Tree object.

tree.SelectedNodes = category4;

Tree component in a UI figure window. The Swimmers node is highlighted.

Read sample patient data into the workspace as a table array. Then, create a table UI component to display the data.

tdata = readtable("patients.xls");
vars = ["Age","Systolic","Diastolic","Smoker"];
tdata = tdata(1:40,vars);

fig = uifigure;
uit = uitable(fig,"Data",tdata);
uit.RowName = "numbered";

Table with patient data in a UI figure window. The table rows are numbered, and the table is scrolled to the top.

Scroll to the 25th row of the table. 

scroll(uit,"row",25)

Table with patient data in a UI figure window. The table is scrolled so that row 25 is at the top of the visible data.

Input Arguments

collapse all

Scrollable container or button group, specified as a figure created with the uifigure function, or any of the following components within that figure: grid layout, panel, button group, or tab.

Vertical scroll location, specified as 'top' or 'bottom'.

Horizontal scroll location, specified as 'left' or 'right'.

UI component to scroll to. The container scrolls to bring the component into view.

x-coordinate, specified as a non-negative integer in pixels from the left edge of the container. The container scrolls to display the specified x-coordinate at the left of the visible container area. If the specified value exceeds the scrollable area of the container, the container scrolls as far as it can in the specified direction.

y-coordinate, specified as an integer in pixels from the bottom edge of the container. The container scrolls to display the specified y-coordinate at the bottom of the visible container area. If the specified value exceeds the scrollable area of the container, the container scrolls as far as it can in the specified direction.

If a grid layout is taller than its parent container, you can use negative y-coordinates to scroll to components within the grid that lie below the bottom edge of the parent container.

Pixel coordinates, specified as a two-element row vector of integers.

Example: [100 150] specifies pixel coordinates (100,150).

Text area, specified as a component created with the uitextarea function.

Scrolling within a text area is supported starting in R2020b.

Tree, specified as a component created with the uitree function. This component can be either a tree with the default style or a check box tree created with uitree('checkbox').

Tree node, specified as a component created with the uitreenode function. Use this argument to specify which tree node to scroll to.

List box, specified as a component created with the uilistbox function.

List box item, specified as an element of the Items property of lb. The function scrolls to the specified item within the list box.

List box item data, specified as an element of the list box ItemsData property of lb. The function scrolls to the item in the list box with the associated item data. If there is more than one such item, the function scrolls to the first.

Table, specified as a component created with the uitable function.

Scrolling within a table is supported starting in R2021a, and is supported only when the table UI component is in a figure created with the uifigure function.

Table scroll target, specified as 'row', 'column', or 'cell'.

Table scroll target index, specified as one of the values listed in the table. The type of value you can specify depends on the value of tableTarget.

tableTargetSupported ValueExampleResult
'row'Positive integer4Scroll vertically to bring the row with the corresponding row index into view.
'column'Positive integer3Scroll horizontally to bring the column with the corresponding column index into view.
'cell'Two-element row vector of positive integers[5 9]Scroll to the cell with the corresponding row and column indices into view.

Specify the scroll target index in relation to the table data in the display. For example, if the table is sorted, specifying a row index scrolls to the row in the sorted table, not in the original table data. You can query the table data as it appears in the current display by using the DisplayData table property.

More About

collapse all

Conditions that Enable Scrolling

To allow scrolling within a container, the Scrollable property of the container must be set to 'on'. In addition, these container-specific conditions must also be true:

Grid layouts

  • The sum of the values specified for the RowHeight property of the grid must be larger than the height of the parent container.

  • The sum of the values specified for the ColumnWidth property of the grid must be larger than the width of the parent container.

  • At least one row or column of the grid must be set to a fixed pixel height or width.

  • The grid must contain components.

Containers other than grid layout

  • The child components in the container must occupy a larger area than the container can display at one time.

  • Components that do not fit in the container must be above or to the right of the container.

Version History

Introduced in R2016a

expand all

See Also

Functions

Properties

Topics