Table
Table UI component
Description
Table UI components display rows and columns of data in an app. Use the
Table
object to modify the appearance and behavior of a table after you
create it.
Creation
Create a table in an app using the uitable
function.
Properties
Table
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 Format 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 the ColumnFormat
property
description for more information.
ColumnName
— Column names
'numbered'
| n
-by-1 cell array of character vectors | n
-by-1 string array | empty cell array ({}
) | ...
Column names, specified as one of these values:
'numbered'
— The column headings are sequential numbers that start at1
.Cell array of character vectors, string array, or categorical array — Each element of the array becomes the name of a column. If you specify a 1-by-
n
cell array, MATLAB stores and returns the value as ann
-by-1 cell array. If you specify anm
-by-n
array, MATLAB reshapes the array into a column vector. Specify a multiline column name by including a vertical slash (|
) in the column name. For example, the value'Telephone|Number'
produces a column heading with a newline character between the words “Telephone” and “Number”.Empty cell array (
{}
) — The table has no column headings.Empty matrix (
[]
) — The table has no column headings.
If the number of columns in the Data
property array does not
match the number of elements in the ColumnName
array, then the
number of columns in the resulting table is the larger of the two values.
If you specify the Data
property as a table array, then the
default column names match the VariableNames
property of the
table array. Changing the ColumnName
property of the
Table
UI component updates the UI, but it will not update the
variable names in the table array.
Example: uit =
uitable(uifigure,'ColumnName',{'Name';'Number'},'Data',{'Bob',5})
Example: uit =
uitable(uifigure,'ColumnName',{'Name';[]},'Data',{'Bob',5})
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.
ColumnRearrangeable
— Ability to rearrange table columns
'off'
(default) | on/off logical value
Ability to rearrange table columns, specified as 'on'
or
'off'
, or as numeric or logical 1
(true
) or 0
(false
). A
value of 'on'
is equivalent to true
, and
'off'
is equivalent to false
. Thus, you can
use the value of this property as a logical value. The value is stored as an on/off
logical value of type matlab.lang.OnOffSwitchState
.
When the value of ColumnRearrangeable
is
'on'
, app users can reorder the table columns by clicking and
dragging the column headers.
Rearranging table columns in the app does not affect the columns in the
Data
property array.
Example: Create Table with Rearrangeable Columns
Create a table with rearrangeable columns in a UI figure window. The table displays with a visual indicator in the column headers to show that the users can click and drag the columns.
fig = uifigure; uit = uitable(fig,"Data",magic(3),"ColumnRearrangeable",true);
To rearrange the first and second columns, click the drag indicator in the header of column 1 and drag the column to the right of column 2.
While the Data
property of the table UI component does not
change, the DisplayData
property is updated to store the data
in the order that it is displayed in the table view.
tbl.Data
ans = 8 1 6 3 5 7 4 9 2
tbl.DisplayData
ans = 1 8 6 5 3 7 9 4 2
ColumnFormat
— Cell display format
empty cell array ({}
) (default) | 1-by-n
cell array of character vectors
Cell display format, specified as an empty cell array or a
1-by-n
cell array of character vectors.
Do not set this property when the Data
property contains a
table
array. For more information, see Format Tabular Data in Apps.
This property sets the format for displaying numeric, logical, cell, or string
array, and cell array of character vectors data types. The elements of the cell array
correspond to columns in the Data
property array. If you do not
want to specify a display format for a particular column, specify
[]
for that column. If you do not specify a format for a column,
MATLAB determines the default display by the data type of the data in the
cell.
Elements of the cell array must be one of the values described in the table.
Cell Format Value | Description |
---|---|
'char' | Display left-justified values. If an element in the
To edit a cell, the user types text to replace the existing value. |
'logical' | Display a center-justified check box. Initially, a check box is
selected when the corresponding To edit a cell, the user selects or clears the check
box. Then, MATLAB sets the corresponding |
'numeric' | Display a right-justified value equivalent to the Command Window
display for numeric data. If an element in the To edit a cell, the user can enter any text. If a user enters text that represents a constant, such as
|
A 1-by-n cell array of character vectors, such as
{'one','two','three'} | Display a pop-up menu in an editable column. The value displays as
left-justified whether the To
edit a cell, the user selects an item from the pop-up menu, or enters text
to create a new item. MATLAB sets the corresponding |
A format name accepted by the | Display the |
Effect of Pop-Up Menu ColumnFormat and Various Data Types
If the ColumnFormat
value defines a pop-up menu, the
initial Data
value does not have to be one of the options in
that menu. The initial Data
value appears until the user makes
a different selection.
For instance, suppose the Data
property value for a given
column is 'Choose'
for all rows, and the
ColumnFormat
value specifies a pop-up menu with the choices
of 'group 1'
and 'group 2'
. When MATLAB creates the table, those table cells display
'Choose'
until the user selects an item in the pop-up menu:
fig = uifigure; myData = {'Andrew' 31 'Male' 'Choose'; ... 'Bob' 41 'Male' 'Choose'; ... 'Anne' 20 'Female' 'Choose'}; uit = uitable(fig, ... "Position", [100 150 380 100], ... "ColumnFormat",{[] [] [] {'group 1' 'group 2'}}, ... "ColumnEditable",true, ... "Data",myData);
Data Display of Editable Columns
This table describes how various data types display with specific
ColumnFormat
values.
ColumnFormat | ||||
'numeric' | 'char' | 'logical' | ||
Data Type of Data Array Value | Any numeric type | Table displays number as-is. | MATLAB converts the value to text and displays it left-justified
in the table. If MATLAB cannot convert the value, then NaN displays. | Not recommended. MATLAB might return a warning when the
user edits the cell, unless you define a CellEditCallback function. |
char | Table displays the value right-justified, as if it is a number. | Table displays the value as-is. | Not recommended. MATLAB might return a warning when the
user edits the cell, unless you define a CellEditCallback function. | |
logical | Table displays logical values as numbers. MATLAB might
return a warning when the user edits the cell, unless you define a CellEditCallback function. | Table displays logical value as left-justified 'true' or 'false' . MATLAB might
return a warning when the user edits the cell, unless you define a CellEditCallback function. | Table displays logical values as check boxes. |
RowName
— Row names
'numbered'
| n
-by-1 cell array of character vectors | n
-by-1 string array | empty cell array ({}
) | ...
Row names, specified as one of these values:
'numbered'
— The row headings are sequential numbers that start at1
.Cell array of character vectors, string array, or categorical array — Each element of the array becomes the name of a row. Row names are restricted to one line of text. If you specify a 1-by-
n
cell array, MATLAB stores and returns the value as ann
-by-1 cell array. If you specify anm
-by-n
array, MATLAB reshapes the array into a column vector.Empty cell array (
{}
) — The table has no row headings.Empty matrix (
[]
) — The table has no row headings
If the number of rows in the Data
property array does not
match the number of elements in the RowName
array, then the
number of rows in the resulting table reflects the number of rows in the
Data
property.
If you specify the Data
property as a table array, then the
default row names match the RowName
property of the table array.
Changing the RowName
property of the table UI component updates
the UI, but it will not update the row names in the table array.
Example: uit =
uitable(uifigure,"RowName",{'Name';'Number'},"Data",{'Bob';5})
Example: uit =
uitable(uifigure,"RowName",{'Name';[]},'Data',{'Bob';5})
Font
FontName
— Font name
system supported font name
Font name, specified as a system supported font name. The default font depends on the specific operating system and locale.
If the specified font is not available, then MATLAB uses the best match among the fonts available on the system where the app is running.
Example: 'Arial'
figure
-Based Apps
For tables in apps created with the
figure
function, you can additionally specify the font name
as 'FixedWidth'
. This uses fixed-width font that looks good in
any locale. The actual fixed-width font used depends on the FixedWidthFontName
property of the root object. Changing the FixedWidthFontName
property causes an immediate update of the display to use the new font.
FontSize
— Font size
positive number
Font size, specified as a positive number. The units of measurement are pixels. The default font size depends on the specific operating system and locale.
Example: 14
FontWeight
— Font weight
'normal'
(default) | 'bold'
Font weight, specified as one of these values:
'normal'
— Default weight as defined by the particular font'bold'
— Thicker character outlines than'normal'
Not all fonts have a bold font weight. For fonts that do not, specifying
'bold'
results in the normal font weight.
FontAngle
— Font angle
'normal'
(default) | 'italic'
Font angle, specified as 'normal'
or 'italic'
.
Not all fonts have an italic font angle. For fonts that do not, specifying
'italic'
results in the normal font angle.
FontUnits
— Font unit of measurement
'pixels'
| 'points'
| 'normalized'
| 'inches'
| 'centimeters'
Font unit 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:
|
'points' | One point is 1/72nd of an inch. |
'normalized' | Normalized values for specifying the font size as a fraction of the height. When you resize a UI component, MATLAB scales the displayed font to maintain that fraction. |
'inches' | Inches. |
'centimeters' | Centimeters. |
figure
-Based Apps
For tables in apps created using the figure
function, the
default value of FontUnits
is
'points'
.
Interactivity
Visible
— State of visibility
'on'
(default) | on/off logical value
State of visibility, specified as 'on'
or 'off'
,
or as numeric or logical 1
(true
) or
0
(false
). A value of 'on'
is equivalent to true
, and 'off'
is equivalent to
false
. Thus, you can use the value of this property as a logical
value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
'on'
— Display the object.'off'
— Hide the object without deleting it. You still can access the properties of an invisible UI component.
To make your app start faster, set the Visible
property to
'off'
for all UI components that do not need to appear at
startup.
Enable
— Operational state of table
'on'
(default) | 'inactive'
| 'off'
Operational state of table, specified as 'on'
,
'off'
, or 'inactive'
. The
Enable
property controls whether a UI component responds to
button clicks. There are three possible values:
'on'
– The UI component is operational.'off'
– The UI component is not operational and appears grayed-out.'inactive'
– The UI component is not operational, but it has the same appearance as whenEnable
is'on'
.
The value of the Enable
property and the type of button click
determine how the UI responds.
Enable Value | Response to Left-Click | Response to Right-Click |
---|---|---|
'on' | The |
|
'off' or 'inactive' |
|
|
Tooltip
— Tooltip
''
(default) | character vector | cell array of character vectors | string array | 1-D categorical array
Tooltip, specified as a character vector, cell array of character vectors, string array, or 1-D categorical array. Use this property to display a message when the user hovers the pointer over the component at run time. The tooltip displays even when the component is disabled. To display multiple lines of text, specify a cell array of character vectors or a string array. Each element in the array becomes a separate line of text. If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.
ContextMenu
— Context menu
empty GraphicsPlaceholder
array (default) | ContextMenu
object
Context menu, specified as a ContextMenu
object created using the uicontextmenu
function. Use this property to display a context menu when
you right-click on a component.
Color and Styling
ForegroundColor
— Cell text color
[0 0 0]
(default) | RGB triplet | hexadecimal color code | 'r'
| 'g'
| 'b'
| ...
Cell text color, specified as an RGB triplet, a hexadecimal color code, or one of
the color options listed in the table. When you set cell text color using the
ForegroundColor
property it applies to all the cells in the
table UI component.
RGB triplets and hexadecimal color codes are useful for specifying custom colors.
An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range
[0,1]
; for example,[0.4 0.6 0.7]
.A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (
#
) followed by three or six hexadecimal digits, which can range from0
toF
. The values are not case sensitive. Thus, the color codes"#FF8800"
,"#ff8800"
,"#F80"
, and"#f80"
are equivalent.
Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.
Color Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|---|---|
"red" | "r" | [1 0 0] | "#FF0000" | |
"green" | "g" | [0 1 0] | "#00FF00" | |
"blue" | "b" | [0 0 1] | "#0000FF" | |
"cyan"
| "c" | [0 1 1] | "#00FFFF" | |
"magenta" | "m" | [1 0 1] | "#FF00FF" | |
"yellow" | "y" | [1 1 0] | "#FFFF00" | |
"black" | "k" | [0 0 0] | "#000000" | |
"white" | "w" | [1 1 1] | "#FFFFFF" |
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.
RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|
[0 0.4470 0.7410] | "#0072BD" | |
[0.8500 0.3250 0.0980] | "#D95319" | |
[0.9290 0.6940 0.1250] | "#EDB120" | |
[0.4940 0.1840 0.5560] | "#7E2F8E" | |
[0.4660 0.6740 0.1880] | "#77AC30" | |
[0.3010 0.7450 0.9330] | "#4DBEEE" | |
[0.6350 0.0780 0.1840] | "#A2142F" |
BackgroundColor
— Table background color
[1 1 1; 0.94 0.94 0.94]
(default) | RGB triplet | hexadecimal color code | 'r'
| 'g'
| 'b'
| matrix of color values | ...
Table background color, specified as an RGB triplet, a hexadecimal color code, a color name, a short name, or a matrix of color values.
Specify a matrix of color values with m
rows when you want the
shading of the table rows to follow a repeating pattern of m
different colors. MATLAB uses the rows of the matrix when the RowStriping
property is 'on'
. The table background is not striped unless both
RowStriping
is 'on'
and
BackgroundColor
is a matrix with multiple rows.
RGB triplets and hexadecimal color codes are useful for specifying custom colors.
An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range
[0,1]
; for example,[0.4 0.6 0.7]
.A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (
#
) followed by three or six hexadecimal digits, which can range from0
toF
. The values are not case sensitive. Thus, the color codes"#FF8800"
,"#ff8800"
,"#F80"
, and"#f80"
are equivalent.
Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.
Color Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|---|---|
"red" | "r" | [1 0 0] | "#FF0000" | |
"green" | "g" | [0 1 0] | "#00FF00" | |
"blue" | "b" | [0 0 1] | "#0000FF" | |
"cyan"
| "c" | [0 1 1] | "#00FFFF" | |
"magenta" | "m" | [1 0 1] | "#FF00FF" | |
"yellow" | "y" | [1 1 0] | "#FFFF00" | |
"black" | "k" | [0 0 0] | "#000000" | |
"white" | "w" | [1 1 1] | "#FFFFFF" |
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.
RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|
[0 0.4470 0.7410] | "#0072BD" | |
[0.8500 0.3250 0.0980] | "#D95319" | |
[0.9290 0.6940 0.1250] | "#EDB120" | |
[0.4940 0.1840 0.5560] | "#7E2F8E" | |
[0.4660 0.6740 0.1880] | "#77AC30" | |
[0.3010 0.7450 0.9330] | "#4DBEEE" | |
[0.6350 0.0780 0.1840] | "#A2142F" |
Example: uitable(uifigure,"Data",rand(10,3),"BackgroundColor",[0 0
1])
creates a table with a blue background color.
Example: uitable(uifigure,"Data",rand(10,3),"BackgroundColor","r")
creates a table with a red background color.
Example: uitable(uifigure,"Data",rand(10,3),"BackgroundColor",["#FF0000";
"#0000FF"])
creates a table with alternating red and blue striped
rows.
Example: uitable(uifigure,"Data",rand(10,3),"BackgroundColor",[0 1 0; 0 0
1])
creates a table with alternating green and blue striped
rows.
RowStriping
— Alternate row shading
'on'
(default) | on/off logical value
Alternate row shading, specified as 'on'
or
'off'
, or as numeric or logical 1
(true
) or 0
(false
). A
value of 'on'
is equivalent to true
, and
'off'
is equivalent to false
. Thus, you can
use the value of this property as a logical value. The value is stored as an on/off
logical value of type matlab.lang.OnOffSwitchState
.
This property controls the shading pattern of the table rows. When the
RowStriping
value is set to 'on'
, the
BackgroundColor
matrix specifies the row colors to display in a
repeating pattern. If the BackgroundColor
matrix has only one
row, then the shading is the same in all table rows.
When RowStriping
is set to 'off'
, then the
first color in the BackgroundColor
matrix defines the shading for
all rows in the table.
Position
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.
InnerPosition
— 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]
. All measurements are in units
specified by the Units
property.
This property value is identical to the Position
and
OuterPosition
property values.
OuterPosition
— 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]
. All measurements are in units
specified by the Units
property.
This property value is identical to the Position
and
InnerPosition
property values.
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.
Callbacks
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.
ButtonDownFcn
— Button-press callback function
''
(default) | function handle | cell array | character vector
Button-press 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.
For more information about specifying a callback property value as a function handle, cell array, or character vector, see Specify a Callback Function.
The ButtonDownFcn
callback is a function that executes when
the user clicks a mouse button on the UI component. The callback executes in the
following situations:
The user right-clicks the table, and the
Enable
property is set to'on'
.The user right-clicks or left-clicks the table, and the
Enable
property is set to'off'
or'inactive'
.
KeyPressFcn
— Key press callback function
''
(default) | function handle | cell array | character vector
Key press 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.
For more information about specifying a callback property value as a function handle, cell array, or character vector, see Specify a Callback Function.
This callback function executes when the Table
object
has focus and the user presses a key. If you do not define a function for this property,
MATLAB passes key presses to the parent figure. Repeated key presses retain the
focus of the Table
object, and the function
executes with each key press. If the user presses multiple keys at approximately the
same time, MATLAB detects the key press for the last key pressed.
If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.
Property | Description | Examples: | |||
---|---|---|---|---|---|
a | = | Shift | Shift-a | ||
Character | The character that displays as a result of pressing a key or keys. The character can be empty or unprintable. | 'a' | '=' | '' | 'A' |
Modifier | A cell array containing the names of one or more modifier keys that are being pressed (such as, Ctrl, Alt, Shift). | {1x0 cell} | {1x0 cell} | {'shift'} | {'shift'} |
Key | The key being pressed, identified by the (lowercase) label on the key, or a text description. | 'a' | 'equal' | 'shift' | 'a' |
Source | The object that has focus when the user presses the key. | Table object | Table object | Table object | Table object |
EventName | The action that caused the callback function to execute. | 'KeyPress' | 'KeyPress' | 'KeyPress' | 'KeyPress' |
Pressing modifier keys affects the callback data in the following ways:
Modifier keys can affect the
Character
property, but do not change theKey
property.Certain keys, and keys modified with Ctrl, put unprintable characters in the
Character
property.Ctrl, Alt, Shift, and several other keys, do not generate
Character
property data.
You also can query the CurrentCharacter
property
of the figure to determine which character the user pressed.
KeyReleaseFcn
— Key-release callback function
''
(default) | function handle | cell array | character vector
Key-release 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.
For more information about specifying a callback property value as a function handle, cell array, or character vector, see Specify a Callback Function.
This callback function executes when the Table
object
has focus and the user releases a key.
If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.
Property | Description | Examples: | |||
---|---|---|---|---|---|
a | = | Shift | Shift-a | ||
Character | Character interpretation of the key that was released. | 'a' | '=' | '' | 'A' |
Modifier | Current modifier, such as | {1x0 cell} | {1x0 cell} | {1x0 cell} | {1x0 cell} |
Key | Name of the key that was released, identified by the lowercase label on the key, or a text description. | 'a' | 'equal' | 'shift' | 'a' |
Source | The object that has focus when the user presses the key. | Table object | Table object | Table object | Table
object |
EventName | The action that caused the callback function to execute. | 'ase' | 'ase' | 'ase' | 'ase' |
Pressing modifier keys affects the callback data in the following ways:
Modifier keys can affect the
Character
property, but do not change theKey
property.Certain keys, and keys modified with Ctrl, put unprintable characters in the
Character
property.Ctrl, Alt, Shift, and several other keys, do not generate
Character
property data.
You also can query the CurrentCharacter
property
of the figure to determine which character the user pressed.
CreateFcn
— Creation function
''
(default) | function handle | cell array | character vector
Object creation function, specified as one of these values:
Function handle.
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.
Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.
For more information about specifying a callback as a function handle, cell array, or character vector, see Callbacks in App Designer.
This property specifies a callback function to execute when MATLAB creates the object. MATLAB initializes all property values before executing the CreateFcn
callback. If you do not specify the CreateFcn
property, then MATLAB executes a default creation function.
Setting the CreateFcn
property on an existing component has no effect.
If you specify this property as a function handle or cell array, you can access the object that is being created using the first argument of the callback function. Otherwise, use the gcbo
function to access the object.
DeleteFcn
— Deletion function
''
(default) | function handle | cell array | character vector
Object deletion function, specified as one of these values:
Function handle.
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.
Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.
For more information about specifying a callback as a function handle, cell array, or character vector, see Callbacks in App Designer.
This property specifies a callback function to execute when MATLAB deletes the object. MATLAB executes the DeleteFcn
callback before destroying the
properties of the object. If you do not specify the DeleteFcn
property, then MATLAB executes a default deletion function.
If you specify this property as a function handle or cell array, you can access the
object that is being deleted using the first argument of the callback function.
Otherwise, use the gcbo
function to access the
object.
CellSelectionCallback
— Cell selection callback function
function handle | cell array | character vector
Note
This property is not recommended for tables in App Designer or in apps created
using the uifigure
function. In
uifigure
-based apps, to execute commands when the app user
selects different elements of the table, use the SelectionChangedFcn
property instead.
Cell selection 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.
This callback function executes when the user selects cells. The function can
access specific information about the user’s interaction with the cell (such as the
cell indices). MATLAB passes this information in a CellSelectionChangeData
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 CellSelectionChangeData
object is not available
to callback functions specified as character vectors.
The following table describes properties of the
CellSelectionChangeData
object.
Property | Description |
---|---|
Indices | This is an |
DisplayIndices | This is an |
Source | Component executing the callback. |
EventName |
|
For more information about writing callbacks, see Callbacks in App Designer.
Callback Execution Control
Interruptible
— Callback interruption
'on'
(default) | on/off logical value
Callback interruption, specified as 'on'
or 'off'
, or as
numeric or logical 1
(true
) or
0
(false
). A value of 'on'
is equivalent to true
, and 'off'
is equivalent to
false
. Thus, you can use the value of this property as a logical
value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
This property determines if a running callback can be interrupted. There are two callback states to consider:
The running callback is the currently executing callback.
The interrupting callback is a callback that tries to interrupt the running callback.
MATLAB determines callback interruption behavior whenever it executes a command that
processes the callback queue. These commands include drawnow
, figure
, uifigure
, getframe
, waitfor
, and pause
.
If the running callback does not contain one of these commands, then no interruption occurs. MATLAB first finishes executing the running callback, and later executes the interrupting callback.
If the running callback does contain one of these commands, then the
Interruptible
property of the object that owns the running
callback determines if the interruption occurs:
If the value of
Interruptible
is'off'
, then no interruption occurs. Instead, theBusyAction
property of the object that owns the interrupting callback determines if the interrupting callback is discarded or added to the callback queue.If the value of
Interruptible
is'on'
, then the interruption occurs. The next time MATLAB processes the callback queue, it stops the execution of the running callback and executes the interrupting callback. After the interrupting callback completes, MATLAB then resumes executing the running callback.
Note
Callback interruption and execution behave differently in these situations:
If the interrupting callback is a
DeleteFcn
,CloseRequestFcn
, orSizeChangedFcn
callback, then the interruption occurs regardless of theInterruptible
property value.If the running callback is currently executing the
waitfor
function, then the interruption occurs regardless of theInterruptible
property value.If the interrupting callback is owned by a
Timer
object, then the callback executes according to schedule regardless of theInterruptible
property value.
BusyAction
— Callback queuing
'queue'
(default) | 'cancel'
Callback queuing, specified as 'queue'
or 'cancel'
. The BusyAction
property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:
The running callback is the currently executing callback.
The interrupting callback is a callback that tries to interrupt the running callback.
The BusyAction
property determines callback queuing behavior only
when both of these conditions are met:
Under these conditions, the BusyAction
property of the
object that owns the interrupting callback determines how MATLAB handles the interrupting callback. These are possible values of the
BusyAction
property:
'queue'
— Puts the interrupting callback in a queue to be processed after the running callback finishes execution.'cancel'
— Does not execute the interrupting callback.
BeingDeleted
— Deletion status
on/off logical value
This property is read-only.
Deletion status, returned as an on/off logical value of type matlab.lang.OnOffSwitchState
.
MATLAB sets the BeingDeleted
property to
'on'
when the DeleteFcn
callback begins
execution. The BeingDeleted
property remains set to
'on'
until the component object no longer exists.
Check the value of the BeingDeleted
property to verify that the object is not about to be deleted before querying or modifying it.
HitTest
— Ability to become current object
'on'
(default) | on/off logical value
Ability to become current object, specified as
'on'
or 'off'
, or as numeric or logical
1
(true
) or 0
(false
). A value of 'on'
is equivalent to
true
, and 'off'
is equivalent to
false
. Thus, you can use the value of this property as a logical
value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
'on'
— Sets the current object to theTable
when the user clicks the component in the running app. Both theCurrentObject
property of theFigure
and thegco
function return theTable
as the current object.'off'
— Sets the current object to be the closest ancestor of theTable
whoseHitTest
is'on'
when the user clicks the component in the running app.
Parent/Child
Parent
— Parent container
Figure
object (default) | Panel
object | Tab
object | ButtonGroup
object | GridLayout
object
Parent container, specified as a Figure
object
created using the uifigure
function, or one of its child
containers: Tab
, Panel
, ButtonGroup
, or GridLayout
. If no container is specified, MATLAB calls the uifigure
function to create a new Figure
object that serves as the parent container.
Children
— Children of table
empty array
Children of table, returned as an empty array. Table objects have no children, so setting this property has no effect.
HandleVisibility
— Visibility of object handle
'on'
(default) | 'callback'
| 'off'
Visibility of the object handle, specified as 'on'
, 'callback'
,
or 'off'
.
This property controls the visibility of the object in its parent's
list of children. When an object is not visible in its parent's list
of children, it is not returned by functions that obtain objects by
searching the object hierarchy or querying properties. These functions
include get
, findobj
, clf
,
and close
. Objects are valid
even if they are not visible. If you can access an object, you can
set and get its properties, and pass it to any function that operates
on objects.
HandleVisibility Value | Description |
---|---|
'on' | The object is always visible. |
'callback' | The object is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command-line, but allows callback functions to access it. |
'off' | The object is invisible at all times. This option is useful
for preventing unintended changes to the UI by another function. Set
the HandleVisibility to 'off' to
temporarily hide the object during the execution of that function.
|
Identifiers
Type
— Type of graphics object
'uitable'
This property is read-only.
Type of graphics object, returned as 'uitable'
.
Tag
— Object identifier
''
(default) | character vector | string scalar
Object identifier, specified as a character vector or string scalar. You can specify a unique Tag
value to serve as an identifier for an object. When you need access to the object elsewhere in your code, you can use the findobj
function to search for the object based on the Tag
value.
UserData
— User data
[]
(default) | array
User data, specified as any MATLAB array. For example, you can specify a scalar, vector, matrix, cell array, character array, table, or structure. Use this property to store arbitrary data on an object.
If you are working in App Designer, create public or private properties in the app to share data instead of using the UserData
property. For more information, see Share Data Within App Designer Apps.
uifigure
-Based Apps Only
DisplayData
— Table data in current display
table array | numeric array | logical array | cell array | string array | cell array of character vectors
This property is read-only.
Note
This property is valid only for tables in App Designer and in apps created
using the uifigure
function.
Table data in the current display, returned as a table, numeric, logical, cell, or string array, or as a cell array of character vectors.
Use this property if you want to update your visualizations based on whether a user has sorted or rearranged columns or edited cells in a table.
MATLAB updates DisplayData
when table columns are sorted
or rearranged, or when cells are edited. If a user does not sort or rearrange columns,
then DisplayData
has the same content as the
Data
property. When a user edits a cell, MATLAB updates both the Data
and
DisplayData
properties.
Example: Difference Between Data
and DisplayData
Create a table UI component with some data and with sortable columns. Then, sort the table by the values in the first column.
fig = uifigure; tbl = uitable(fig,Data=[4 9; 7 1; 2 3],ColumnSortable=true);
Query the Data
property and the
DisplayData
property of the table. The
Data
property returns the original table data before the
table was sorted.
tbl.Data
ans = 4 9 7 1 2 3
The DisplayData
property returns the table data as it
appears in the app.
tbl.DisplayData
ans = 2 3 4 9 7 1
ColumnSortable
— Ability to sort columns
[]
(default) | logical 1-by-n
array | logical scalar
Note
This property is valid only for tables in App Designer and in apps created using
the uifigure
function.
Ability to sort columns, specified as:
An empty logical array (
[]
) — No columns are sortable.A logical 1-by-
n
array — This array specifies which columns are sortable. 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 that column sortable. A value offalse
makes that column unsortable. 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 that do not have specified values are not sortable.A logical scalar — The entire table is sortable (
true
) or unsortable (false
).
Example: uit = uitable(uifigure,'Data',rand(3),'ColumnSortable',[true true
false]);
Example: uit =
uitable(uifigure,'Data',rand(5),'ColumnSortable',true);
If the Data
property contains cell array data or table array
data with cell array columns, then only columns with uniform data types are sortable
in the running app. Cell array columns with nonuniform data types cannot be sorted in
the running app, even when the ColumnSortable
property is
true
.
StyleConfigurations
— Configurations of added styles
empty n
-by-3 table array (default) | n
-by-3 table array
This property is read-only.
Note
This property is valid only for tables in App Designer and in apps created
using the uifigure
function.
Configuration of added styles created using the uistyle
function, returned as an n
-by-3 table array. Each row of the table
array corresponds to a style that is currently applied to the table UI component.
Styles that are added consecutively are given a style order number of
n+1
. The Target
and
TargetIndex
columns specify the part of the table UI component
that the style was added to. The Style
column specifies the style
class name.
Use this property if you want to remove a style from the table UI component using
the removeStyle
function.
Example: Remove a Style
First, add three styles to a table UI component.
s1 = uistyle("BackgroundColor","yellow"); s2 = uistyle("BackgroundColor","red"); s3 = uistyle("FontColor","b","FontWeight","bold"); fig = uifigure; fig.Position = [100 100 520 220]; uit = uitable(fig); uit.Data = rand(5); uit.Position = [20 30 480 135]; addStyle(uit,s1,"row",[1 2 4 5]); addStyle(uit,s2,"cell",[2 1; 4 2; 1 3; 1 5]) addStyle(uit,s3,"column",2);
When you query uit.StyleConfigurations
, a 3-by-3 table array
is returned. The row style was added to the table UI component first, so it is style
order number 1
. The TargetIndex
value for the
row style, {1×4 double}
, indicates that four rows were specified
when the style was added. Similarly, the second style was added to four cells in the
table. The third style was added to the second column.
uit.StyleConfigurations
ans = 3×3 table Target TargetIndex Style ______ ____________ ___________________________ 1 row {1×4 double} [1×1 matlab.ui.style.Style] 2 cell {4×2 double} [1×1 matlab.ui.style.Style] 3 column {[ 2]} [1×1 matlab.ui.style.Style]
Remove the second style that was added to the table, by specifying style order
number 2
. Notice how the table UI component updates.
removeStyle(uit,2)
Selection
— Table selection
[]
(default) | positive integer | vector of positive integers | n
-by-2 array of positive integers
Note
This property is valid only for tables in App Designer and in apps created
using the uifigure
function.
Table selection, specified as a positive integer, vector of positive integers,
or n
-by-2 array of positive integers. Use this property to
programmatically set the table selection, or to query the table elements that the app
user has selected. The type of value that you can specify depends on the value of the
SelectionType
and Multiselect
properties.
SelectionType | Multiselect | Supported Values | Examples | Result |
---|---|---|---|---|
'row' | 'on' | Vector of positive integers | [1 3 4 8] | Select all rows with the corresponding row indices. |
'off' | Positive integer | 6 | Select the row with the corresponding row index. | |
'column' | 'on' | Vector of positive integers | [2 5 7] | Select all columns with the corresponding column indices. |
'off' | Positive integer | 2 | Select the column with the corresponding column index. | |
'cell' | 'on' | n -by-2 array of positive integers | [1 1; 3 4; 4 2] | Select all cells with the corresponding row and column subscripts. |
'off' | 1-by-2 array of positive integers | [3 2] | Select the cell with the corresponding row and column subscripts. |
When SelectionType
is 'row'
or
'column'
and MultiSelect
is
'on'
, you can specify Selection
as either a
row or a column vector. However, MATLAB converts and stores the value as a row vector.
Difference Between Selection
and DisplaySelection
The Selection
and DisplaySelection
properties both return the indices of the selected cells, but these indices
correspond to different configurations of the table data and can be used for
different purposes.
Selection
— Set or query the indices of the selected cells corresponding to theData
property. For example, useSelection
to perform a calculation on the user-selected data or update the style of the selected data.DisplaySelection
— Query the indices of the selected cells corresponding to theDisplayData
property. For example, useDisplaySelection
to extract the selected data in the order in which the table data appears in the app.
The two properties have the same values if a user does not sort or rearrange the table columns.
For example, create a table UI component with some data and with sortable columns. Then, sort the table by the values in the first column, and select the first row of the sorted table.
fig = uifigure; tbl = uitable(fig,Data=[4 9; 7 1; 2 3],ColumnSortable=true);
Query the Selection
property and the
DisplaySelection
property of the table. The
Selection
property returns the indices of the selected cells
in the original table data.
tbl.Selection
ans = 3 1 3 2
The DisplaySelection
property returns the indices of the
selected cells in the displayed table data.
tbl.DisplaySelection
ans = 1 1 1 2
DisplaySelection
— Table selection in current display
[]
(default) | positive integer | vector of positive integers | n
-by-2 array of positive integers
This property is read-only.
Note
This property is valid only for tables in App Designer and in apps created
using the uifigure
function.
Table selection in the current display, returned as a positive integer, vector
of positive integers, or n
-by-2 array of positive integers. Use
this property to query the table elements that the app user has selected as the
selection appears in the current table display.
The type of value that DisplaySelection
returns depends on
the value of the SelectionType
and
Multiselect
properties.
SelectionType | Multiselect | Value | Examples |
---|---|---|---|
'row' | 'on' | Indices of the selected rows in the current display, returned as a row vector of positive integers | [1 3 4 8] |
'off' | Index of the selected row in the current display, returned as a positive integer | 6 | |
'column' | 'on' | Indices of the selected columns in the current display, returned as a row vector of positive integers | [2 5 7] |
'off' | Index of the selected column in the current display, returned as a positive integer | 2 | |
'cell' | 'on' | Row and column subscripts of the selected cells in the current display,
returned as an n -by-2 array of positive integers | [1 1; 3 4; 4 2] |
'off' | Row and column subscripts of the selected cell in the current display, returned as a 1-by-2 array of positive integers | [3 2] |
Difference Between Selection
and DisplaySelection
The Selection
and DisplaySelection
properties both return the indices of the selected cells, but these indices
correspond to different configurations of the table data and can be used for
different purposes.
Selection
— Set or query the indices of the selected cells corresponding to theData
property. For example, useSelection
to perform a calculation on the user-selected data or update the style of the selected data.DisplaySelection
— Query the indices of the selected cells corresponding to theDisplayData
property. For example, useDisplaySelection
to extract the selected data in the order in which the table data appears in the app.
The two properties have the same values if a user does not sort or rearrange the table columns.
For example, create a table UI component with some data and with sortable columns. Then, sort the table by the values in the first column, and select the first row of the sorted table.
fig = uifigure; tbl = uitable(fig,Data=[4 9; 7 1; 2 3],ColumnSortable=true);
Query the Selection
property and the
DisplaySelection
property of the table. The
Selection
property returns the indices of the selected cells
in the original table data specified using the Data
property.
tbl.Selection
ans = 3 1 3 2
The DisplaySelection
property returns the indices of the
selected cells in the displayed table data.
tbl.DisplaySelection
ans = 1 1 1 2
SelectionType
— Table selection type
'cell'
(default) | 'row'
| 'column'
Note
This property is valid only for tables in App Designer and in apps created
using the uifigure
function.
Table selection type, specified as 'cell'
,
'row'
, or 'column'
. The table selection type
specifies which table elements MATLAB selects when the user interacts with the table. For example, if
SelectionType
is 'row'
and the app user clicks
a cell in the second row of the table, this selects the entire second row.
Multiselect
— Multiple element selection
'on'
(default) | on/off logical value
Note
This property is valid only for tables in App Designer and in apps created
using the uifigure
function.
Multiple element selection, specified as 'on'
or
'off'
, or as numeric or logical 1
(true
) or 0
(false
). A
value of 'on'
is equivalent to true
, and
'off'
is equivalent to false
. Thus, you can
use the value of this property as a logical value. The value is stored as an on/off
logical value of type matlab.lang.OnOffSwitchState
.
SelectionChangedFcn
— Selection changed callback
''
(default) | function handle | cell array | character vector
Note
This property is valid only for tables in App Designer and in apps created using
the uifigure
function. In figure
-based
apps, to execute commands when the app user selects different elements of the table,
use the CellSelectionCallback
property instead.
Selection changed callback, 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 execute commands when the app user selects a different cell, row, or column of the table.
This callback function can access specific information about the user’s
interaction with the table, such as the elements that they select. MATLAB passes this information in a
TableSelectionChangedData
object as the second argument to your
callback function. In App Designer, this argument is called event
.
You can query the object properties using dot notation. For example,
event.Selection
returns the selected cell, row, or column
indices. The TableSelectionChangedData
object is not available to
callback functions specified as character vectors.
The following table describes properties of the
TableSelectionChangedData
object.
Property | Description |
---|---|
Selection | Array containing the indices of the elements the user selected in
the running app. If When a column is sorted,
|
PreviousSelection | Array containing the cell, row, or column indices of the previously selected table data. |
SelectionType | Type of the selected table elements, given as
|
DisplaySelection | Array containing the cell, row, or column indices corresponding to
the location of the selected elements as they appear visually in the sorted
table. If a user does not sort the table, then
|
PreviousDisplaySelection | Array containing the cell, row, or column indices corresponding to
the location of the previously selected elements as they appear visually in
the sorted table. If a user does not sort the table, then
|
Source | Component that executes the callback. |
EventName |
|
For more information about writing callbacks, see Callbacks in App Designer.
The table executes the SelectionChangedFcn
callback when the
user changes the table selection by clicking, by using the arrow keys, or by using one
of these keyboard shortcuts.
Contiguous selection options:
Click a cell and drag.
Click one cell, then Shift+Click another cell to select all cells in between.
Click one cell, then press Shift+Arrow keys to add contiguous cells.
Click on a row or column header to select the whole row or column.
Click a cell, then press Ctrl+Space to select all the cells in that column (regardless of whether all the cells are in view).
Click a cell, then press Shift+Space to select all the cells in that row (regardless of whether all the cells are in view).
Select a row or column. Then Shift+Click another row or column header to select all the rows or columns in between.
Click one cell, then press Shift+Page Up or Shift+Page Down to select all visible cells above or below that cell.
Press Ctrl+A to select all of the cells in the table.
Noncontiguous selection options:
Select a cell or a group of cells. Then, Ctrl+Click to select or deselect a noncontiguous cell, row, or column.
DisplayDataChangedFcn
— Display data changed callback
''
(default) | function handle | cell array | character vector
Note
This property is valid only for tables in App Designer and in apps created
using the uifigure
function.
Display data changed callback, 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.
This callback executes when the DisplayData
changes. This
occurs when the app user performs one of these actions:
Edits a cell
Sorts a column of the table
Rearranges columns of the table
Use this callback if you want information about user interactions that caused the
DisplayData
to change. If you need specific information about
edited cells, create a CellEditCallback
instead.
This callback function can access specific information about whether columns are
sorted or rearranged or cells are edited. MATLAB passes this information in a DisplayDataChangedData
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.InteractionColumn
returns the index of
the column that was interacted with in Data
. The
DisplayDataChangedData
object is not available to callback
functions specified as character vectors.
Property | Description |
---|---|
DisplayRowName | Cell array of RowName property values in the
sorted display. DisplayRowName will always be a
permutation of the original RowName property. |
DisplayColumnName | Cell array of ColumnName property values in the
sorted display. DisplayColumnName will always be a
permutation of the original ColumnName
property. |
Interaction | User interaction that triggered the callback, given as
'sort' , 'edit' , or
'rearrange' . |
InteractionColumn | Index of modified column in Data . |
InteractionDisplayColumn | Index of modified column in DisplayData . |
InteractionVariable | VariableNames property of the modified column for
table array data. If Data contains a data type other than
a table array, then InteractionVariable returns an empty
character array. |
DisplaySelection | Array containing the cell, row, or column indices corresponding to the location of the selected elements in the display of the sorted table. |
PreviousDisplaySelection | Array containing the cell, row, or column indices corresponding to the location of the previously selected elements in the display of the sorted table. |
Source | Component executing the callback. |
EventName |
|
For more information about specifying a callback as a function handle, cell array, or character vector, see Callbacks in App Designer.
ClickedFcn
— Clicked callback
''
(default) | function handle | cell array | character vector
Note
This property is valid only for tables in App Designer and in apps created using
the uifigure
function.
Clicked 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.
This callback function executes when the user clicks anywhere in the table UI component.
This callback function can access specific information about the user’s
interaction with the table. MATLAB passes this information in a ClickedData
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.InteractionInformation
returns information about where the
user clicked in the table. The ClickedData
object is
not available to callback functions specified as character vectors.
This table lists the properties of the ClickedData
object.
Property | Value |
---|---|
InteractionInformation | Information about where in the component the app user clicked. This information is stored as an object with these properties:
You can query the object properties using dot notation. For
example, |
Source | Component that executes the callback |
EventName | 'Clicked' |
This table lists the properties of the InteractionInformation
object associated with the table UI
component.
Property | Value |
---|---|
DisplayRow | Row that the user clicked as it appears visually in the table, returned as a scalar. If the user has not sorted the table, then
|
DisplayColumn | Column that the user clicked as it appears visually in the table, returned as a scalar. If the user has not rearranged the table,
then |
Row | Row that the user clicked as it corresponds to the original table data, returned as a scalar. If the user has not sorted the
table, then |
Column | Column that the user clicked as it corresponds to the original table data, returned as a scalar. If the user has not rearranged
the table, then |
RowHeader | Whether the user clicked on the table row header, returned as a logical
0 (false ) or 1
(true ). |
ColumnHeader | Whether the user clicked on the table column header, returned as a
logical 0 (false ) or
1 (true ). |
Location | Location where the user clicked relative to the bottom-left corner
of the parent container of the table, returned as a two-element vector of
the form The value of
|
ScreenLocation | Location where the user clicked relative to the bottom-left corner
of their primary display, returned as a two-element vector of the form
The value of |
For more information about writing callbacks, see Callbacks in App Designer.
Example: Select Background Color When Table Cell Is Clicked
Create a table UI component with some data. Specify a
ClickedFcn
callback function named
colorCells
that executes when a user clicks the table. In the
colorCells
function:
Use the
event.InteractionInformation
object to access information about whether the user clicked a cell.If the user did click a cell (as opposed to a header or blank area), open a color picker for the user to choose a background color.
Use the selected color to create a
Style
object and add it to the table cell.Bring keyboard focus back to the table UI component.
To try this example, save the code in a new script and run it. Click a cell in the table and select a background color for that cell.
fig = uifigure; t = uitable(fig); t.Data = rand(5); t.ClickedFcn = @colorCells; function colorCells(src,event) r = event.InteractionInformation.Row; c = event.InteractionInformation.Column; if ~isempty(r) && ~isempty(c) removeStyle(src) color = uisetcolor; s = uistyle(BackgroundColor=color); addStyle(src,s,"cell",[r c]); focus(src) end end
DoubleClickedFcn
— Double-clicked callback
''
(default) | function handle | cell array | character vector
Note
This property is valid only for tables in App Designer and in apps created using
the uifigure
function.
Double-clicked callback, 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.
This callback function executes when the user double-clicks anywhere in the table UI component.
This callback function can access specific information about the user’s
interaction with the table. MATLAB passes this information in a DoubleClickedData
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.InteractionInformation
returns information about where the
user double-clicked in the table. The DoubleClickedData
object is not available to callback functions specified
as character vectors.
This table lists the properties of the DoubleClickedData
object.
Property | Value |
---|---|
InteractionInformation | Information about where in the component the app user double-clicked. This information is stored as an object with these properties:
You can query the object properties using dot notation. For
example, |
Source | Component that executes the callback |
EventName | 'DoubleClicked' |
This table lists the properties of the InteractionInformation
object associated with the table UI
component.
Property | Value |
---|---|
DisplayRow | Row that the user double-clicked as it appears visually in the table, returned as a scalar. If the user has not sorted the
table, then |
DisplayColumn | Column that the user double-clicked as it appears visually in the table, returned as a scalar. If the user has not rearranged the
table, then |
Row | Row that the user double-clicked as it corresponds to the original table data, returned as a scalar. If the user has not sorted the
table, then |
Column | Column that the user double-clicked as it corresponds to the original table data, returned as a scalar. If the user has not
rearranged the table, then |
RowHeader | Whether the user double-clicked on the table row header, returned as a
logical 0 (false ) or
1 (true ). |
ColumnHeader | Whether the user double-clicked on the table column header, returned as a
logical 0 (false ) or
1 (true ). |
Location | Location where the user double-clicked relative to the bottom-left
corner of the parent container of the table, returned as a two-element
vector of the form The value of
|
ScreenLocation | Location where the user double-clicked relative to the bottom-left
corner of their primary display, returned as a two-element vector of the
form The value of |
For more information about writing callbacks, see Callbacks in App Designer.
Example: Select Background Color When Table Cell Is Double-Clicked
Create a table UI component with some data. Specify a
DoubleClickedFcn
callback function named
colorCells
that executes when a user double-clicks the table.
In the colorCells
function:
Use the
event.InteractionInformation
object to access information about whether the user double-clicked a cell.If the user did double-click a cell (as opposed to a header or blank area), open a color picker for the user to choose a background color.
Use the selected color to create a
Style
object and add it to the table cell.Bring keyboard focus back to the table UI component.
To try this example, save the code in a new script and run it. Double-click a cell in the table and select a background color for that cell.
fig = uifigure; t = uitable(fig); t.Data = rand(5); t.DoubleClickedFcn = @colorCells; function colorCells(src,event) r = event.InteractionInformation.Row; c = event.InteractionInformation.Column; if ~isempty(r) && ~isempty(c) removeStyle(src) color = uisetcolor; s = uistyle(BackgroundColor=color); addStyle(src,s,"cell",[r c]); focus(src) end end
Layout
— Layout options
empty LayoutOptions
array (default) | GridLayoutOptions
object
Note
This property is valid only for tables in App Designer and in apps created
using the uifigure
function.
Layout options, specified as a GridLayoutOptions
object.
This property specifies options for components that are children of grid layout
containers. If the component is not a child of a grid layout container (for example,
it is a child of a figure or panel), then this property is empty and has no effect.
However, if the component is a child of a grid layout container, you can place the
component in the desired row and column of the grid by setting the
Row
and Column
properties on the
GridLayoutOptions
object.
For example, this code places a table UI component in the third row and second column of its parent grid.
g = uigridlayout([4 3]);
uit = uitable(g,'Data',rand(10,3));
uit.Layout.Row = 3;
uit.Layout.Column = 2;
To make the table span multiple rows or columns, specify the
Row
or Column
property as a two-element
vector. For example, this table spans columns 2
through
3
:
uit.Layout.Column = [2 3];
figure
-Based Apps Only
Extent
— Size of enclosing rectangle
four-element row vector
This property is read-only.
Note
This property is valid only for tables in apps created using the
figure
function.
Size of enclosing rectangle, returned as a four-element row vector. The first
two elements of the vector are always zero. The third and fourth elements are the
width and height of the rectangle containing the table, respectively. All measurements
are in units specified by the Units
property.
MATLAB determines the size of the rectangle based on the current
Data
, RowName
and
ColumnName
property values. MATLAB estimates the width and height values using the column and row widths.
The estimated extent can be larger than the figure.
Consider using the Extent
property value when specifying the
width and height values of the Position
property.
Object Functions
addStyle | Add style to UI component |
removeStyle | Remove style from UI component |
scroll | Scroll to location within component |
focus | Focus UI component |
Examples
Display Table Data
Create a table array t
with different data types by reading data from a file. Select the first 15 rows of four variables from t
.
t = readtable("patients.xls"); vars = ["Age","Systolic","Diastolic","Smoker"]; t = t(1:15,vars);
Create a table UI component to display the tabular data. The data type determines how the data appears in the component. For example, logical data displays as a check box. For more information, see Format Tabular Data in Apps.
fig = uifigure; uit = uitable(fig,"Data",t,"Position",[20 20 350 300]);
Programmatically Update Table Data
Display and programmatically update data in a table UI component.
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 table UI component.
uit.Data.Validity(1) = {'definite tsunami'};
Convert the maximum height data from meters to feet by accessing and modifying the data in the MaxHeight
variable.
uit.Data.MaxHeight = uit.Data.MaxHeight*3.281;
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.
In a file named tableDataApp.m
, write a function that implements the app:
Create a
table
array of tsunami data.Create a UI figure with a grid layout manager.
Create a sortable and editable table UI component in the figure. Store the
table
array in the componentData
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.
Update the bubble chart when the app user sorts columns or edits cells in the table UI component by writing a
DisplayDataChangedFcn
callback. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.
function tableDataApp % 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]; gl = uigridlayout(fig,[1 2]); % Create table UI component uit = uitable(gl); uit.Data = t; uit.ColumnSortable = true; uit.ColumnEditable = [false false true]; % Create bubble chart ax = geoaxes(gl); lat = t.Latitude; long = t.Longitude; sz = t.MaxHeight; bubblechart(ax,lat,long,sz) % Specify table callback uit.DisplayDataChangedFcn = @(src,event) updatePlot(src,ax); end function updatePlot(src,ax) t = src.DisplayData; lat = t.Latitude; long = t.Longitude; sz = t.MaxHeight; bubblechart(ax,lat,long,sz) end
Run the app.
tableDataApp
A sortable column displays arrows in the header when you point to it. Sort the table by the maximum height of the tsunamis.
Edit the maximum height of the tsunami in the second row to be 30 meters by double-clicking the table cell and entering the new height. The bubble chart updates in response.
Change Color of Specific Cells Based on Data
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.
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", ... "Cause","EarthquakeMagnitude"]; tdata = tdata(1:20,vars); fig = uifigure("Position",[500 500 760 360]); uit = uitable(fig, ... "Data",tdata, ... "Position",[20 20 720 320]);
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 in the table with NaN
.
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
Create an app that plots data on a map when the app user selects the data in a table.
In a file named selectTsunamis.m
, write a function that implements the app:
Load the tsunami data.
Create a UI figure with a table UI component and a geographic bubble chart in a grid layout manager.
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. TheplotTsunami
callback function plots a bubble for each selected row, where the size of the bubble represents the maximum tsunami height. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.
function selectTsunamis % Load data t = readtable("tsunamis.xlsx"); vars = ["Latitude","Longitude","MaxHeight"]; t = t(1:20,vars); % Create UI components fig = uifigure("Position",[100 100 800 350]); gl = uigridlayout(fig,[1 2]); gl.ColumnWidth = {'1x','2x'}; tbl = uitable(gl); gb = geobubble(gl,[],[]); % Configure table tbl.Data = t; tbl.SelectionType = "row"; tbl.Multiselect = "on"; tbl.SelectionChangedFcn = @(src,event) plotTsunami(src,event,gb); end % Plot tsunami data for each selected row function plotTsunami(src,event,gb) rows = event.Selection; data = src.Data(rows,:); gb.LatitudeData = data.Latitude; gb.LongitudeData = data.Longitude; gb.SizeData = data.MaxHeight; end
Run the app.
selectTsunamis
Select multiple table rows by holding Ctrl while clicking. The plot updates with the selected tsunami data.
Programmatically Scroll to Table Row
Since R2021a
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.
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)
Version History
Introduced in R2008aR2024a: Specify background color using hexadecimal color codes or color names
When modifying table colors using the BackgroundColor
property, you
can specify colors as hexadecimal color codes or color names, in addition to RGB
triplets.
R2023b: Query selected table data in current table display
Use the DisplaySelection
property of the table to query the cells
that are selected in the current table display. This property is useful when an app user has
sorted or rearranged columns in the table and you want to know which cells are selected
based on the app user's view of the data.
R2022b: 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.
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.
R2022a: RearrangeableColumns
property is not recommended
Starting in R2022a, using the RearrangeableColumns
property to
specify whether users can rearrange table columns in a figure
-based app
is not recommended. Use the ColumnRearrangeable
property instead. The
new property can have the same values as the old one.
There are no plans to remove support for the RearrangeableColumns
property at this time. However, the RearrangeableColumns
property no
longer appears in the list returned by calling the get
function on a
table UI component.
R2022a: 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.
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'
.
R2020a: UIContextMenu
property is not recommended
Starting in R2020a, using the UIContextMenu
property to assign a
context menu to a graphics object or UI component is not recommended. Use the
ContextMenu
property instead. The property values are the
same.
There are no plans to remove support for the UIContextMenu
property
at this time. However, the UIContextMenu
property no longer appears in
the list returned by calling the get
function on a graphics object or UI
component.
R2018b: TooltipString
property is not recommended
Starting in R2018b, using the TooltipString
property to specify a
tooltip for a UI component is not recommended. Use the Tooltip
property
instead. The property values are the same.
There are no plans to remove support for the TooltipString
property
at this time. However, the TooltipString
property no longer appears in
the list returned by calling the get
function on a UI component.
R2014b: Selected
property is not recommended
Starting in R2014b, using the Selected
property is not recommended.
It no longer has any effect on objects of this type.
R2014b: SelectionHighlight
property is not recommended
Starting in R2014b, using the SelectionHighlight
property is not
recommended. It no longer has any effect on objects of this type.
MATLAB 命令
您点击的链接对应于以下 MATLAB 命令:
请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。
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)