scroll

Scroll to location within component

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.

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

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.

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'.

Tree

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

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

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.

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.

Examples

Scroll Within a Figure

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];

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)

Scroll to Location in Grid

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);

Scroll to a location in the grid.

scroll(g,100,-30)

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

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

Scroll to Component

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];

Scroll to the table.

scroll(fig,uit)

Scroll to Bottom of Text Area

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.";

Scroll to the bottom of the text area.

scroll(txa,"bottom")

Scroll to List Box Item

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];

Scroll to Caroline Eliot.

scroll(list,'Caroline Eliot')

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

list.Value = 5;

Scroll to Tree Node

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');

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

expand(tree)

Scroll to the Swimmers node.

scroll(tree,category4)

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

tree.SelectedNodes = category4;

Scroll to Table Row

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";

Scroll to the 25th row of the table.

scroll(uit,"row",25)

Input Arguments

container — Scrollable container or button group

Figure object | GridLayout object | Panel object | ButtonGroup object | Tab object

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.

vlocation — Vertical scroll location

'top' | 'bottom'

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

hlocation — Horizontal scroll location

'left' | 'right'

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

comp — UI component to scroll to

UI component

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

x — x-coordinate

non-negative integer

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 — y-coordinate

integer

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.

coord — Pixel coordinates

row vector of integers

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

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

txa — Text area

TextArea object

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

Scrolling within a text area is supported starting in R2020b.

tr — Tree

Tree object | CheckBoxTree object

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').

treenode — Tree node

TreeNode object

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

lb — List box

ListBox object

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

item — List box item

element of list box Items property

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

itemdata — List box item data

element of list box ItemsData property

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.

tbl — Table

Table object

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.

tableTarget — Table scroll target

'row' | 'column' | 'cell'

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

tableIndex — Table scroll target index

positive integer | row vector of positive integers

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.

tableTarget	Supported Value	Example	Result
'row'	Positive integer	4	Scroll vertically to bring the row with the corresponding row index into view.
'column'	Positive integer	3	Scroll 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

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

R2022b: Scroll to a specified component in a container or button group

To scroll to a component in a container or button group, use the syntax scroll(container,component).

R2021a: Scroll in a table UI component

Specify the table scroll location as the top, bottom, left, or right side of the table, or as a specific row, column, or table cell.

R2020b: Scroll in a text area

Specify the scroll location as the top or bottom of the text area.