Main Content

Table Properties

Control table UI component appearance and behavior

Table UI components display rows and columns of data in an app. The uitable function creates a table UI component and sets any required properties before displaying it. By changing property values of a Table object, you can modify certain aspects of its appearance and behavior. Use dot notation to refer to a specific object and property.

fig = uifigure;
uit = uitable(fig,'Data',[1 2 3; 4 5 6; 7 8 9]);
uit.FontSize = 10;

Some properties and property values of Table objects differ depending on whether the table is a child of a figure created using the uifigure function or the figure function. The uifigure function is the recommended function to use when building new apps, and is the function used in App Designer apps. For more information, see Ways to Build Apps.

Table

expand all

Table data, specified as one of the following types of array:

  • Table array (uifigure-based apps only) — Displays any combination of data types that table arrays support, such as datetime, duration, and categorical.

  • Numeric array — Displays numeric values such as double or single.

  • Logical array — Displays check boxes. true values correspond to selected boxes, whereas false 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 the ColumnName property of the Table 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 the RowName property of the Table 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 Table Array Data Types in App Designer 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.

Column names, specified as one of these values:

  • 'numbered' — The column headings are sequential numbers that start at 1.

  • 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 an n-by-1 cell array. If you specify an m-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})

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 the ColumnName 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.

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

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 of n is equal to the number of columns in the table. Each value in the array corresponds to a table column. A value of true in the array makes the cells in that column editable. A value of false 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.

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 Table Array Data Types in App Designer 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 Data property array is logical, then true or false appears in the table.

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 Data value evaluates to true. The corresponding values in the Data property array must be of type logical to ensure that the data displays correctly in the table.

To edit a cell, the user selects or clears the check box. Then, MATLAB sets the corresponding Data value to true or false. The ColumnEditable property value must be true to allow users to select or clear the check boxes.

'numeric'

Display a right-justified value equivalent to the Command Window display for numeric data. If an element in the Data property array is logical, then 1 or 0 appears in the table. If an element in the Data property array is not numeric and not logical, then NaN appears in the table.

To edit a cell, the user can enter any text.

If a user enters text that represents a constant, such as pi, you can code the CellEditCallback function to convert the value to the numeric equivalent. In this case, MATLAB attempts to convert the user-entered text to a numeric value and stores it in the Data property. Then, the CellEditCallback function executes. See the CellEditCallback description for an example.

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 ColumnEditable property is set to true or false.

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 Data property array value to the selected menu item. The ColumnEditable property value must be true to allow users to select items in the pop-up menu.

A format name accepted by the format function, such as: 'short' or 'long'

Display the Data property values using the specified format. The values display as right-justified.

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('Parent', 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 ValueAny numeric typeTable 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.
charTable 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.
logicalTable 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.

Row names, specified as one of these values:

  • 'numbered' — The row headings are sequential numbers that start at 1.

  • 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 an n-by-1 cell array. If you specify an m-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

expand all

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.

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

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.

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.

Font unit of measurement, specified as one of the values in this table.

Units ValueDescription
'pixels' (default)

Distances in pixels are independent of your system resolution on Windows® and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

  • On Linux® systems, the size of a pixel is determined by your system resolution.

'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

expand all

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.

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 when Enable is 'on'.

The value of the Enable property and the type of button click determine how the UI responds.

Enable ValueResponse to Left-ClickResponse to Right-Click
'on'

The SelectionChangedFcn function executes. The Selection property updates in the callback data object that MATLAB passes to the callback function.

  1. The figure’s WindowButtonDownFcn callback executes.

  2. The ButtonDownFcn callback executes.

'off' or 'inactive'

  1. The figure’s WindowButtonDownFcn callback executes.

  2. The ButtonDownFcn callback executes.

  1. The figure’s WindowButtonDownFcn callback executes.

  2. The ButtonDownFcn callback executes.

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.

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

expand all

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 from 0 to F. 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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
'red''r'[1 0 0]'#FF0000'

Sample of the color red

'green''g'[0 1 0]'#00FF00'

Sample of the color green

'blue''b'[0 0 1]'#0000FF'

Sample of the color blue

'cyan' 'c'[0 1 1]'#00FFFF'

Sample of the color cyan

'magenta''m'[1 0 1]'#FF00FF'

Sample of the color magenta

'yellow''y'[1 1 0]'#FFFF00'

Sample of the color yellow

'black''k'[0 0 0]'#000000'

Sample of the color black

'white''w'[1 1 1]'#FFFFFF'

Sample of the color white

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]'#0072BD'

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]'#D95319'

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]'#EDB120'

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]'#7E2F8E'

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]'#77AC30'

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]'#4DBEEE'

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]'#A2142F'

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Table background color, specified as an RGB triplet or an m-by-3 matrix of RGB triplets. An RGB triplet is a row vector that specifies the intensities of the red, green, and blue components of the color. The intensities must be in the range, [0,1]. Color names are not valid.

Specify an m-by-3 matrix when you want the shading of the table rows to follow a repeating pattern of m different colors. Each row of the matrix must be an RGB triplet. 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 an m-by-3 matrix.

Example: uit = uitable(uifigure,'Data',rand(10,3),'BackgroundColor',[0.85 0.85 1])

Example: uit = uitable(uifigure,'Data',rand(10,3),'BackgroundColor',[1 1 1 ;0.85 0.85 1])

The following table lists the RGB triplets for certain colors.

ColorRGB Triplet
Yellow[1 1 0]
Magenta[1 0 1]
Cyan[0 1 1]
Red[1 0 0]
Green[0 1 0]
Blue[0 0 1]
White[1 1 1]
Black[0 0 0]

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

expand all

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.

ElementDescription
leftDistance from the inner left edge of the parent container to the outer left edge of the table
bottomDistance from the inner bottom edge of the parent container to the outer bottom edge of the table
widthDistance between the right and left outer edges of the table
heightDistance 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.

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.

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 of measurement, specified as one of the values in this table.

Units ValueDescription
'pixels' (default)

Distances in pixels are independent of your system resolution on Windows and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

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 (0,0) and the upper-right corner maps to (1,1).

'inches'Inches.
'centimeters'Centimeters.
'points'Points. One point equals 1/72nd of an inch.

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.

figure-Based Apps

For tables in apps created using the figure function, the default value of Units is 'normalized'.

In addition, you can specify Units as 'characters'. Character units are based on the default uicontrol font of the graphics root object:

  • Character width = width of the letter x.

  • Character height = distance between the baselines of two lines of text.

To access the default uicontrol font, use get(groot,'defaultuicontrolFontName') or set(groot,'defaultuicontrolFontName').

Callbacks

expand all

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, Indices returns the original 1-by-2 array of a cell before it was sorted—DisplayIndices returns the new location of the edited cell that displays visually in the sorted table.

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 DisplayIndices has the same content as the Indices property.

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 Data property array.

The NewData property is empty if MATLAB detects an error in the user-entered data.

Error

This is the error message returned if MATLAB detects an error in the user-entered data.

The Error property is empty when MATLAB successfully writes the value to the Data property.

If the Error property is not empty, then the CellEditCallback can display the message, or it can attempt to fix the problem.

Source

Component executing the callback.

EventName

'CellEdit'.

When the user edits a table cell, MATLAB performs these steps:

  1. Tries to store the new value into the Data property of the table

  2. Calls 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 Write Callbacks in App Designer.

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

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

CharacterThe character that displays as a result of pressing a key or keys. The character can be empty or unprintable.'a''=''''A'
ModifierA 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'}
KeyThe key being pressed, identified by the (lowercase) label on the key, or a text description.'a''equal''shift''a'
SourceThe object that has focus when the user presses the key.Table objectTable objectTable objectTable object
EventNameThe 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 the Key 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.

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 'control', or an empty cell array if there is no modifier.

{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'
SourceThe object that has focus when the user presses the key.Table objectTable objectTable objectTable object
EventNameThe 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 the Key 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.

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

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

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 n-by-2 array containing the row and column indices of the cell the user selected in the running app. For multicolumn variables in a table array, the column indices refer to the whole column. When a column is sorted, Indices returns the original 1-by-2 array of a cell before it was sorted—DisplayIndices returns the new location of the selected cell that displays visually in the sorted table.

DisplayIndices

This is an n-by-2 array containing the row and column indices corresponding to the location of the selected cell in the display of the sorted table. If a user does not sort the table, then DisplayIndices has the same content as the Indices property.

Source

Component executing the callback.

EventName

'CellSelection'.

For more information about writing callbacks, see Write Callbacks in App Designer.

Callback Execution Control

expand all

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, the BusyAction 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, or SizeChangedFcn callback, then the interruption occurs regardless of the Interruptible property value.

  • If the running callback is currently executing the waitfor function, then the interruption occurs regardless of the Interruptible property value.

  • If the interrupting callback is owned by a Timer object, then the callback executes according to schedule regardless of the Interruptible property value.

Note

When an interruption occurs, MATLAB does not save the state of properties or the display. For example, the object returned by the gca or gcf command might change when another callback executes.

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:

  • The running callback contains a command that processes the callback queue, such as drawnow, figure, uifigure, getframe, waitfor, or pause.

  • The value of the Interruptible property of the object that owns the running callback is 'off'.

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.

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.

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 the Table when the user clicks the component in the running app. Both the CurrentObject property of the Figure and the gco function return the Table as the current object.

  • 'off' — Sets the current object to be the closest ancestor of the Table whose HitTest is 'on' when the user clicks the component in the running app.

Parent/Child

expand all

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 of table, returned as an empty array. Table objects have no children, so setting this property has no effect.

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

expand all

This property is read-only.

Type of graphics object, returned as 'uitable'.

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.

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

expand all

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 columns or edited cells in a table.

DisplayData updates when table columns are sorted or when cells are edited. If a user does not sort columns, then DisplayData has the same content as the value stored in the Data property. When a user edits a cell, the Data and DisplayData properties both update.

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 of n is equal to the number of columns in the table. Each value in the array corresponds to a table column. A value of true in the array makes that column sortable. A value of false 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 of numeric or character arrays, or cell array of character vectors are sortable in the running app. Cell array columns with uniform logical data or nonuniform data types cannot be sorted in the running app, even when the ColumnSortable property is true.

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)

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.

SelectionTypeMultiselectSupported ValuesExamplesResult
'row''on'Vector of positive integers[1 3 4 8]

Select all rows with the corresponding row indices.

'off'Positive integer6

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 integer2

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, the value is always converted to and stored as a row vector.

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.

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.

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 SelectionType is 'cell', this is an n-by-2 array containing the row and column indices of the cells the user selected. If the SelectionType is 'row' or 'column', this is a 1-by-n array containing the indices of the rows or columns the user selected. For multicolumn variables in a table array, the column indices refer to the whole column.

When a column is sorted, Selection returns the location of the selection in the unsorted table data. To return the location where the selection appears visually in the sorted table, use the DisplaySelection property instead.

PreviousSelection

Array containing the cell, row, or column indices of the previously selected table data.

SelectionType

Type of the selected table elements, given as 'cell', 'row', or 'column'.

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 DisplaySelection has the same value as Selection.

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 PreviousDisplaySelection has the same value as PreviousSelection.

Source

Component that executes the callback.

EventName

'SelectionChanged'.

For more information about writing callbacks, see Write Callbacks in App Designer.

The table executes the SelectionChangedFcn callback when the user selects a table element 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 a noncontiguous cell, row, or column.

Note

This property is valid only for tables in App Designer and in apps created using the uifigure function.

Callback when display data changes, 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, because a user either edits a cell or sorts columns of a 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 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.

PropertyDescription
DisplayRowNameCell array of RowName property values in the sorted display. DisplayRowName will always be a permutation of the original RowName property.
DisplayColumnNameCell array of ColumnName property values in the sorted display. DisplayColumnName will always be a permutation of the original ColumnName property.
Interaction'sort' or 'edit'
InteractionColumnIndex of modified column in Data.
InteractionDisplayColumnIndex of modified column in DisplayData.
InteractionVariableVariableNames 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.

SourceComponent executing the callback.
EventName

'DisplayDataChanged'.

For more information about specifying a callback as a function handle, cell array, or character vector, see Write Callbacks in App Designer.

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

expand all

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.

Note

This property is valid only for tables in apps created using the figure function.

Ability to rearrange table columns, specified as 'off' or 'on', 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 provides a way to let users reorder the table columns (but not the labels) by clicking and dragging the column headers.

Note

Rearranging table columns in the UI does not affect the columns in the Data property array.

Compatibility Considerations

expand all

Not recommended starting in R2020a

Not recommended starting in R2018b

Not recommended starting in R2014b

Not recommended starting in R2014b

Introduced in R2008a