Table Properties

Control table UI component appearance and behavior in uifigure-based apps

expand all in page

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;

The properties listed here are valid for table UI components in App Designer, or in apps created with the uifigure function. For table UI components used in GUIDE, or in apps created with the figure function, see Table Properties.

Table

expand all

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

  • Table array — 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

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

This property is read-only.

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.

Column names, specified as one of these values:

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

  • Cell array of character vectors or categorical array — Each element of the array becomes the name of a column. Column 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 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', 'fit', '1x', or as a 1-by-n cell array of character vectors, strings, and numeric values.

  • 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 — 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 — 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 — 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 uitable.

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.

Ability to sort columns, specified as:

  • An empty logical array ([]) — No columns are sortable.

  • A logical scalar — The entire table is sortable (true) or unsortable (false).

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

Example: uit = uitable(uifigure,'Data',rand(5),'ColumnSortable',true);

Example: uit = uitable(uifigure,'Data',rand(3),'ColumnSortable',[true true false]);

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.

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 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 RowNames 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})

This property is read-only.

Configuration of added styles, 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. For instance, in this example, three styles are added 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)

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.

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 size units, specified as 'pixels'.

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

  • If you set this property to 'on', the app user can interact with the component.

  • If you set this property to 'off', the component appears dimmed, indicating that the app user cannot interact with it, and that it will not trigger a callback.

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'

'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 TripletHexadecimal Color CodeAppearance
[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'

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 'pixels'. MATLAB measures all units from the lower left corner of the parent object.

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

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.

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. A single data cell (not a row or column heading) can be selected by clicking it or navigating to it with an arrow key. Multiple cells can be selected with any of the actions described in the tables. When selecting multiple cells, use different actions depending on whether they are contiguous or discontiguous.

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 Shift+arrow key to add contiguous cells.
Click on a row or column header to select the whole row or column.
Click a cell, then Ctrl+space to select all the cells in that column (regardless of whether all the cells are in view).
Click a cell, then 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 Shift+PgUp or Shift+PgDn to select all visible cells above or below that cell.
Press Ctrl+A to select all of the cells in the table

Discontiguous Selection Options
Click and drag to select a contiguous group of cells (or select a single cell). Then, Ctrl+click to focus another cell, and finally Shift+click to select the cell that is in focus, or Shift+click and drag to select a range of cells that spread from it. (Pressing Shift+arrow key also selects more than one cell.)
Ctrl+click on a row or column header to select the entire row or column. Then repeat to select another non-adjacent row or column.

When a cell is focused using Ctrl+click, the cell outline turns blue () . When a cell is selected using click or Shift+click, the cell fill-color changes to blue ().

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

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 How to Specify Callback Property Values.

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

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 How to Specify Callback Property Values.

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 How to Specify Callback Property Values.

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.

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.

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running callback (if one exists). The Interruptible property of the object owning the running callback determines if interruption is allowed.

  • A value of 'on' allows other callbacks to interrupt the object's callbacks. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, uifigure, getframe, waitfor, or pause command.

    • If the running callback contains one of those commands, then MATLAB stops the execution of the callback at that point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes.

    • If the running callback does not contain one of those commands, then MATLAB finishes executing the callback without interruption.

  • A value of 'off' blocks all interruption attempts. The BusyAction property of the object owning the interrupting callback determines if the interrupting callback is discarded or put into a queue.

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.

  • Timer objects execute according to schedule regardless of the Interruptible property value.

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.

Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. The Interruptible property of the object owning the running callback determines if interruption is permitted. If interruption is not permitted, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put in the queue. 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.

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.

See Also

| | | |

Topics

Introduced in R2016b

MATLAB Documentation

Support