uitable
Create table user interface component
Description
creates a table user interface
component in the current figure and returns the uit
= uitableTable
UI
component object. If there is no figure available, MATLAB® calls the figure
function to create
one.
specifies property values of the table UI component using one or more name-value
pair arguments.uit
= uitable(Name,Value
)
creates
the table in the specified parent container. The parent container can be a figure
created with either the uit
= uitable(parent
)figure
or uifigure
function, or a child
container such as a panel. Property values for uitable
vary
slightly depending on whether the app is created with the
figure
or uifigure
function. For more
information, see Name-Value Arguments.
specifies the parent container and one or more property values.uit
= uitable(parent
,Name,Value
)
Examples
Display Table Array Data
Starting in R2018a, you can display table
array data in a table UI
component. (This type of data is supported only when the table UI component is
in a figure created with the uifigure
function. App Designer
uses this type of figure for creating apps.)
Create table array t
by calling the
readtable
function to read data from a file. Select
four variables and 15 rows from t
.
t = readtable('patients.xls'); vars = {'Age','Systolic','Diastolic','Smoker'}; t = t(1:15,vars);
Create a table UI component, and specify t
as the
data.
fig = uifigure;
uit = uitable(fig,'Data',t);
Programmatically Update Table Data
Display and programmatically update table
array data in a table UI
component. (This type of data is supported only when the table UI component is
in a figure created with the uifigure
function. App Designer
uses this type of figure for creating apps.)
Create a table array by reading in tsunami data from a file, and display a subset of the data in a table UI component.
t = readtable('tsunamis.xlsx'); vars = {'Year','MaxHeight','Validity'}; t = t(1:20,vars); fig = uifigure; uit = uitable(fig,'Data',t);
Update the validity of the tsunami in the first row by editing the
Data
property of the UI table.
uit.Data.Validity(1) = {'definite tsunami'};
Convert the maximum height data from meters to feet by accessing and
modifying the data in the MaxHeight
column.
uit.Data.MaxHeight = uit.Data.MaxHeight*3.281;
Enable and Code Response to Interactive Data Editing
Create an app that allows users to sort and edit table data,
and that updates a data visualization when data is changed. (Interactive column
sorting is supported only when the table UI component is in a figure created
with the uifigure
function. App Designer
uses this type of figure for creating apps.)
First, create a program file called tsunamisData.m
.
Within the program file:
Create a
table
array by calling thereadtable
function.Create a UI figure.
Create a sortable and editable table UI component to display in the figure. Store the
table
array to the component'sData
property.Create a bubble chart to visualize the tsunami data, where the coordinates of a bubble represent the latitude and longitude of the tsunami and the size of the bubble represents the maximum height.
Specify a
DisplayDataChangedFcn
callback that uses theDisplayData
property to update the bubble chart when the app user sorts columns or edits cells in the table UI component.
function tsunamisData % Create table array t = readtable('tsunamis.xlsx'); vars = {'Latitude','Longitude','MaxHeight'}; t = t(1:20,vars); % Create UI figure fig = uifigure; fig.Position(3:4) = [722 360]; % Create table UI component uit = uitable(fig); uit.Data = t; uit.ColumnSortable = true; uit.ColumnEditable = [false false true]; uit.Position(3) = 290; uit.DisplayDataChangedFcn = @updatePlot; % Create bubble chart ax = uiaxes(fig); ax.Position(1) = 315; ax.XLabel.String = 'Longitude'; ax.YLabel.String = 'Latitude'; x = t.Longitude; y = t.Latitude; sz = t.MaxHeight; bubblechart(ax,x,y,sz) % Update the bubble chart when table data changes function updatePlot(src,event) t = uit.DisplayData; x = t.Longitude; y = t.Latitude; sz = t.MaxHeight; bubblechart(ax,x,y,sz) end end
A sortable column displays arrows in the header when you hover your mouse over it. Sort the table by the maximum height of the tsunami.
Edit the maximum height of the tsunami in the second row to be 30 meters by first double-clicking on the table cell, and then entering the new height. Notice how the bubble chart updates in response.
Change Color of Specific Cells Based on Data
Starting in R2019b, you can style rows, columns, or cells of
a table UI component using the uistyle
and addStyle
functions. (Styles are only supported when the table UI
component is in a figure created with the uifigure
function. App Designer uses this type of figure for creating apps.)
Style cells in a table UI component that contain missing values. In this
case, add a red background color style to cells that have
NaN
values.
Read tsunami sample data into the workspace as a table array. Then, create a table UI component to display the data.
tdata = readtable('tsunamis.xlsx'); vars = {'Year','Month','Day','Hour', ... 'MaxHeight','Cause','EarthquakeMagnitude'}; tdata = tdata(1:100,vars); fig = uifigure('Position',[500 500 760 360]); uit = uitable(fig); uit.Position = [20 20 720 320]; uit.Data = tdata; uit.RowName = 'numbered';
Use the ismissing
function to get a logical array of
the table elements that contain missing values. Find the row and column
subscripts for the elements that have NaN
values.
Finally, create a red background color style and add it to the cells with
NaN
values in the table UI component.
styleIndices = ismissing(tdata); [row,col] = find(styleIndices); s = uistyle('BackgroundColor',[1 0.6 0.6]); addStyle(uit,s,'cell',[row,col]);
Programmatically Access Table Selection
Starting in R2021b, you can programmatically set and query
which table elements are selected, and specify whether users can select cells,
rows, or columns. (Programmatic selection is only supported when the table UI
component is in a figure created with the uifigure
function. App Designer uses this type of figure for creating apps.)
Using this feature, create an app that automatically plots data on a map
when the user selects it in a table. First, create a program file called
selectTsunamis.m
. Within the program file:
Load the tsunami data by calling the
readtable
function.Create a UI figure with a table UI component and a geographic bubble chart in a panel.
Configure the table UI component. Store the tsunami data in the
Data
property, and let users select multiple rows by setting theSelectionType
andMultiSelect
properties.Specify a
SelectionChangedFcn
callback that updates the bubble chart when the app user changes the table selection. The function plots a bubble for each selected row, where the size of the bubble represents the maximum tsunami height.
function selectTsunamis % Load data T = readtable('tsunamis.xlsx'); vars = {'Latitude','Longitude','MaxHeight'}; T = T(1:20,vars); % Create UI components fig = uifigure('Position',[500 500 700 350]); tbl = uitable(fig,'Position',[20 20 250 300]); pnl = uipanel(fig,'Position',[285 20 400 300]); geobubble(pnl,[],[]); % Configure table tbl.Data = T; tbl.SelectionType = 'row'; tbl.Multiselect = 'on'; tbl.SelectionChangedFcn = @plotTsunami; % Plot tsunami data for each selected row function plotTsunami(src,event) rows = event.Selection; data = src.Data(rows,:); lat = data.Latitude; long = data.Longitude; ht = data.MaxHeight; geobubble(pnl,lat,long,ht); end end
Run the selectTsunamis
function, and select multiple
table rows by holding down Ctrl while clicking. The plot
updates with the tsunami data.
Programmatically Scroll to Table Row
Starting in R2021a, you can programmatically scroll to a row,
column, or cell of a table UI component using the scroll
function. (Programmatic
scrolling is only supported when the table UI component is in a figure created
with the uifigure
function. App Designer uses this type of
figure for creating apps.)
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)
Display Array of Numbers
Create a table UI component that displays a 10-by-3 array of random
integers. The Data
property specifies the values to
display, and the Position
property specifies the
location and size of the table within the figure.
f = figure; uit = uitable(f,'Data',randi(100,10,3),'Position',[20 20 262 204]);
Display Mixed Data Types
Table UI components can accommodate a mixture of different data types across the columns.
Create an empty Table
UI component.
f = figure; uit = uitable(f);
Set the Data
property to populate the data as a cell
array that contains a mixture of different types. Then set the
Position
property to adjust the location and size
of the table to fit the data.
d = {'Male',52,true;'Male',40,true;'Female',25,false}; uit.Data = d; uit.Position = [20 20 258 78];
Set the ColumnName
property to change the column
headings to descriptive names. Set the ColumnEditable
property to true
so that users can edit the data in the
UI. When a user changes a value in the UI, the Data
property updates to reflect that change.
uit.ColumnName = {'Gender','Age','Authorized'}; uit.ColumnEditable = true;
Input Arguments
parent
— Parent container
Figure
object (default) | Panel
object | Tab
object | ButtonGroup
object | GridLayout
object
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: uitable(fig,'Data',[1 2 3; 4 5 6])
Note
The properties listed here are a subset of the available properties. For the full list, see Table Properties.
Data
— Table data
table array | numeric array | logical array | cell array | string array | ...
Table data, specified as one of the following types of array:
Table array (
uifigure
-based apps only) — Displays any combination of data types thattable
arrays support, such asdatetime
,duration
, andcategorical
.Numeric array — Displays numeric values such as
double
orsingle
.Logical array — Displays check boxes.
true
values correspond to selected boxes, whereasfalse
values display cleared boxes.Cell array — Displays any combination of numeric, logical, or character array values.
String array — Displays characters and text.
Cell array of character vectors — Displays characters and text.
To prevent warnings or NaN
values that display when users enter invalid data into an editable cell, write a CellEditCallback
function to convert the data to the appropriate type. When a user edits a cell, the Data
property updates.
Specify a Table Array
In App Designer and apps created using the uifigure
function, you can specify the Data
property as a table array. Table arrays provide a convenient way to store tabular data as a MATLAB variable. The table
, readtable
, and array2table
functions create table arrays. By contrast, the uitable
function creates a Table
UI component (a user interface component for an app).
When you specify the Data
property of a Table
UI component as a table array, then MATLAB sets the format of the Table
UI component automatically based on the values in the table array:
By default, the column names displayed in the app match the
VariableNames
property of the table array. Changing theColumnName
property of theTable
UI component updates the UI, but it does not update the variable names in the table array.By default, the row names displayed in the app match the
RowName
property of the table array. Changing theRowName
property of theTable
UI component updates the UI, but it does not update the row names in the table array.The data type of each table array variable controls formatting for the corresponding column in the app. If you try to set the
ColumnFormat
property, MATLAB returns a warning.
For more information on displaying table array data, see Display Tabular Data in Apps.
Specify Numeric, Logical, Cell, String Array, or Cell Array of Character Vectors
Use the ColumnFormat
property to specify the format for data that is a numeric, logical, cell, or string array, or a cell array of character vectors. If data is edited and results in a mismatch between the data type of the data and the ColumnFormat
property, MATLAB converts the data or displays a warning. See Data Display of Editable Columns in the ColumnFormat
property description for more information.
ColumnWidth
— Width of table columns
'auto'
(default) | 'fit'
| '1x'
| 1-by-n
cell array
Width of table columns, specified as 'auto'
or as a 1
-by-n
cell array of character vectors, strings, and numeric values. In uifigure
-based apps, you can additionally specify the column width as '1x'
or 'fit'
.
Automatic widths — Specify
'auto'
to have MATLAB calculate the widths of the columns automatically using several factors, one of which is theColumnName
property value.Fit widths to content (
uifigure
-based apps only) — Specify a value of'fit'
to configure columns to strictly adjust widths to fit column names and data. This setting allows narrower columns than'auto'
does.Uniform widths (
uifigure
-based apps only) — Specify a value of'1x'
to make all columns the same width, dividing the available space equally.Fixed widths — Specify a cell array of numeric values that define the column widths in pixel units.
Combinations — You can combine fixed and variable column widths in a cell array. Each element in the cell array corresponds to a column in the table. If the cell array you specify has fewer values than the number of columns, then the columns with no specified value keep the default value of
'auto'
. If the array has more values than the number of columns, MATLAB ignores the extra values.Weighted variable widths (
uifigure
-based apps only) — Specify a cell array with character vectors or strings composed of a number concatenated with an'x'
(for example,'2x'
,'3x'
, etc.). The x-factor of each column sets that column width proportionally with respect to the others, with consideration for the remaining space in the UI table.
If a user interactively resizes a table column in a running app, the resized column
width persists even if you later update the ColumnWidth
property.
Example: uit = uitable(uifigure,'ColumnWidth','auto','Data',[1 2 3;4 5 6])
Example: uit = uitable(uifigure,'ColumnWidth','fit','Data',[1 2 3;4 5 6])
Example: uit = uitable(uifigure,'ColumnWidth',{64,60,40},'Data',[1 2 3;4 5 6])
Example: uit = uitable(uifigure,'ColumnWidth',{'2x','1x','1x'},'Data',[1 2 3;4 5 6])
Example: uit = uitable(uifigure,'ColumnWidth',{64,"auto",40},'Data',[1 2 3;4 5 6])
Example: uit = uitable(uifigure,'ColumnWidth',{'fit','1x','3x'},'Data',[1 2 3;4 5 6])
ColumnEditable
— Ability to edit column cells
[]
(default) | logical 1-by-n
array | logical scalar
Ability to edit column cells, specified as:
An empty logical array (
[]
) — No columns are editable.A logical 1-by-
n
array — This array specifies which columns are editable. The value ofn
is equal to the number of columns in the table. Each value in the array corresponds to a table column. A value oftrue
in the array makes the cells in that column editable. A value offalse
makes the cells in that column uneditable. If the array has more values than the number of columns, MATLAB ignores the excess values. If the array has fewer values than the number of columns, then the columns with no specified value are not editable.A logical scalar — The entire table is editable or uneditable.
When a user edits a cell, the Data
property updates.
Example: uit = uitable(uifigure,'Data',rand(10,3),'ColumnEditable',[false true true])
Example: uit = uitable(uifigure,'Data',rand(10,3),'ColumnEditable',false)
To enable users to interact with the controls in table columns that contain check boxes or pop-up menus, set the ColumnEditable
property to true
.
If the Data
property is a table array, then any variables that are multicolumn or contain non-editable data types, like duration
, are not editable in the running app even when the ColumnEditable
property is true
. Table array variables that contain mixed data types in a cell array are editable in the running app, as long as the data types are editable.
CellEditCallback
— Cell edit callback function
function handle | cell array | character vector
Cell edit callback function, specified as one of these values:
A function handle.
A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.
A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.
Use this callback function to perform calculations or validate input when the app user changes the contents of a table cell.
This callback function can access specific information about the user’s interaction with the cell (such as the cell indices). MATLAB passes this information in a CellEditData
object as the second argument to your callback function. In App Designer, the argument is called event
. You can query the object properties using dot notation. For example, event.Indices
returns the indices of the selected cell. The CellEditData
object is not available to callback functions specified as character vectors.
The following table describes properties of the CellEditData
object.
Property | Description |
---|---|
Indices | This is a 1-by-2 array containing the row and column indices of the cell the user edited in the running app. When a column is sorted, |
DisplayIndices | This is a 1-by-2 array containing the row and column indices corresponding to the location of the edited cell in the display of the sorted table. If a user does not sort columns, then |
PreviousData | This is the previous cell data. The default is an empty matrix, |
EditData | This is the user-entered value. |
NewData | This is the value that MATLAB wrote to the The |
Error | This is the error message returned if MATLAB detects an error in the user-entered data. The If the |
Source | Component executing the callback. |
EventName |
|
When the user edits a table cell, MATLAB performs these steps:
Tries to store the new value into the
Data
property of the tableCalls the
CellEditCallback
function (if it exists)
If the value results in an error and there is no CellEditCallback
function, then the cell data reverts to its previous value and no error displays.
For more information about writing callbacks, see Callbacks in App Designer.
Position
— Location and size of table
[left bottom width height]
Location and size of the table, specified as a four-element vector of
the form [left bottom width height]
. This table
describes each element in the vector.
Element | Description |
---|---|
left | Distance from the inner left edge of the parent container to the outer left edge of the table |
bottom | Distance from the inner bottom edge of the parent container to the outer bottom edge of the table |
width | Distance between the right and left outer edges of the table |
height | Distance between the top and bottom outer edges of the table |
All measurements are in units specified by the
Units
property.
The Position
values are relative to the
drawable area of the parent container. The drawable area is the area
inside the borders of the container and does not include the area occupied by decorations such
as a menu bar or title.
Units
— Units of measurement
'pixels'
(default) | 'normalized'
| 'inches'
| 'centimeters'
| 'points'
| 'characters'
Units of measurement, specified as one of the values in this table.
Units Value | Description |
---|---|
'pixels' (default) | Distances in pixels are independent of your system resolution on Windows® and Macintosh systems:
On Linux® systems, the size of a pixel is determined by your system resolution. |
'normalized' | These units are normalized with respect to
the parent container. The lower-left corner of the
container maps to |
'inches' | Inches. |
'centimeters' | Centimeters. |
'points' | Points. One point equals 1/72nd of an inch. |
'characters' | These units are based on the default uicontrol font of the graphics root object:
To access the default uicontrol
font, use
|
The recommended value is 'pixels'
, because most
MATLAB app building functionality measures distances in pixels.
You can create a table that rescales based on the size of the parent
container by parenting the table to a grid layout manager created using
the uigridlayout
function. For more information, see Lay Out Apps Programmatically.
Version History
Introduced in R2008aR2022b: Program a response to a user clicking or double-clicking the table
Use the ClickedFcn
and DoubleClickedFcn
callback properties to program a response to a user clicking and double-clicking the
table UI component.
For more information, see Table Properties.
R2022a: Rearrange columns interactively
Specify the ability to interactively rearrange table columns in an app by using
the ColumnRearrangeable
property. In a table UI component with
the ColumnRearrangeable
value set to 'on'
,
rearrange table columns in the app by clicking and dragging the column
header.
In App Designer and apps created using the uifigure
function,
you can program an app to respond when a user rearranges table columns by creating a
DisplayDataChangedFcn
callback function.
For more information, see Table Properties.
R2021b: Set, query, and configure options for table selection
Use properties to configure selection options for table UI components.
Set and query the table selection using the
Selection
property.Specify whether a user can select table cells, rows, or columns using the
SelectionType
property.Specify whether a user can select single or multiple table elements using the
Multiselect
property.Update your app whenever a user selects table data by specifying a
SelectionChangedFcn
callback.
Selection options in table UI components are supported only in App Designer apps
and in figures created with the uifigure
function.
For more information, see Table Properties.
R2020b: Configure column widths to use weighted variables or to automatically adjust to fit data
Configure the column widths of table UI components in App Designer and
uifigure
-based apps.
To specify a weighted variable width, set the
ColumnWidth
property to a number paired with an'x'
character (for example,'2x'
).To configure column widths to automatically adjust to column names and data, set the
ColumnWidth
property to'fit'
.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)