Table

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

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:

For more information on displaying table array data, see Format Tabular Data in Apps.

Specify Numeric, Logical, Cell, String Array, or Cell Array of Character Vectors

Use the ColumnFormat property to specify the format for data that is a numeric, logical, cell, or string array, or a cell array of character vectors. If data is edited and results in a mismatch between the data type of the data and the ColumnFormat property, MATLAB converts the data or displays a warning. See the ColumnFormat property description for more information.

Column names, specified as one of these values:

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

If a user interactively resizes a table column in a running app, the resized column width persists even if you later update the ColumnWidth property.

Example: uit = uitable(uifigure,'ColumnWidth','auto','Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth','fit','Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth',{64,60,40},'Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth',{'2x','1x','1x'},'Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth',{64,"auto",40},'Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth',{'fit','1x','3x'},'Data',[1 2 3;4 5 6])

Ability to edit column cells, specified as:

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 rearrange table columns, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

When the value of ColumnRearrangeable is 'on', app users can reorder the table columns by clicking and dragging the column headers.

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

Example: Create Table with Rearrangeable Columns

Create a table with rearrangeable columns in a UI figure window. The table displays with a visual indicator in the column headers to show that the users can click and drag the columns.

fig = uifigure;
uit = uitable(fig,"Data",magic(3),"ColumnRearrangeable",true);

To rearrange the first and second columns, click the drag indicator in the header of column 1 and drag the column to the right of column 2.

While the Data property of the table UI component does not change, the DisplayData property is updated to store the data in the order that it is displayed in the table view.

tbl.Data

ans =

     8     1     6
     3     5     7
     4     9     2

tbl.DisplayData

ans =

     1     8     6
     5     3     7
     9     4     2

Cell display format, specified as an empty cell array or a 1-by-n cell array of character vectors.

Do not set this property when the Data property contains a table array. For more information, see Format Tabular Data in Apps.

This property sets the format for displaying numeric, logical, cell, or string array, and cell array of character vectors data types. The elements of the cell array correspond to columns in the Data property array. If you do not want to specify a display format for a particular column, specify [] for that column. If you do not specify a format for a column, MATLAB determines the default display by the data type of the data in the cell.

Elements of the cell array must be one of the values described in the table.

Effect of Pop-Up Menu ColumnFormat and Various Data Types

If the ColumnFormat value defines a pop-up menu, the initial Data value does not have to be one of the options in that menu. The initial Data value appears until the user makes a different selection.

For instance, suppose the Data property value for a given column is 'Choose' for all rows, and the ColumnFormat value specifies a pop-up menu with the choices of 'group 1' and 'group 2'. When MATLAB creates the table, those table cells display 'Choose' until the user selects an item in the pop-up menu:

fig = uifigure;
myData = {'Andrew' 31 'Male' 'Choose'; ...
    'Bob' 41 'Male' 'Choose';  ...
    'Anne' 20 'Female' 'Choose'};
uit = uitable(fig, ...
    "Position", [100 150 380 100], ...
    "ColumnFormat",{[] [] [] {'group 1' 'group 2'}}, ...
    "ColumnEditable",true, ...
    "Data",myData);

Data Display of Editable Columns

This table describes how various data types display with specific ColumnFormat values.

Row names, specified as one of these values:

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

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.

figure-Based Apps

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

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.

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:

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

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.

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.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

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

Table background color, specified as an RGB triplet, a hexadecimal color code, a color name, a short name, or a matrix of color values.

Specify a matrix of color values with m rows when you want the shading of the table rows to follow a repeating pattern of m different colors. MATLAB uses the rows of the matrix when the RowStriping property is 'on'. The table background is not striped unless both RowStriping is 'on' and BackgroundColor is a matrix with multiple rows.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

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

Example: uitable(uifigure,"Data",rand(10,3),"BackgroundColor",[0 0 1]) creates a table with a blue background color.

Example: uitable(uifigure,"Data",rand(10,3),"BackgroundColor","r") creates a table with a red background color.

Example: uitable(uifigure,"Data",rand(10,3),"BackgroundColor",["#FF0000"; "#0000FF"]) creates a table with alternating red and blue striped rows.

Example: uitable(uifigure,"Data",rand(10,3),"BackgroundColor",[0 1 0; 0 0 1]) creates a table with alternating green and blue striped rows.

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.

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.

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.

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.

Cell edit callback function, specified as one of these values:

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.

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

If the value results in an error and there is no CellEditCallback function, then the cell data reverts to its previous value and no error displays.

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

Button-press callback function, specified as one of these values:

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:

Key press callback function, specified as one of these values:

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.

Pressing modifier keys affects the callback data in the following ways:

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:

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.

Pressing modifier keys affects the callback data in the following ways:

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:

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

This property specifies a callback function to execute when MATLAB creates the object. MATLAB initializes all property values before executing the CreateFcn callback. If you do not specify the CreateFcn property, then MATLAB executes a default creation function.

Setting the CreateFcn property on an existing component has no effect.

If you specify this property as a function handle or cell array, you can access the object that is being created using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

Object deletion function, specified as one of these values:

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

This property specifies a callback function to execute when MATLAB deletes the object. MATLAB executes the DeleteFcn callback before destroying the properties of the object. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

If you specify this property as a function handle or cell array, you can access the object that is being deleted using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

Cell selection callback function, specified as one of these values:

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.

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

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:

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:

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 BusyAction property determines callback queuing behavior only when both of these conditions are met:

Under these conditions, the BusyAction property of the object that owns the interrupting callback determines how MATLAB handles the interrupting callback. These are possible values of the BusyAction property:

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.

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.

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.

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

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

Example: Difference Between Data and DisplayData

Create a table UI component with some data and with sortable columns. Then, sort the table by the values in the first column.

fig = uifigure;
tbl = uitable(fig,Data=[4 9; 7 1; 2 3],ColumnSortable=true);

Query the Data property and the DisplayData property of the table. The Data property returns the original table data before the table was sorted.

tbl.Data

ans =

     4     9
     7     1
     2     3

The DisplayData property returns the table data as it appears in the app.

tbl.DisplayData

ans =

     2     3
     4     9
     7     1

Ability to sort columns, specified as:

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

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

If the Data property contains cell array data or table array data with cell array columns, then only columns with uniform data types are sortable in the running app. Cell array columns with nonuniform data types cannot be sorted in the running app, even when the ColumnSortable property is true.

This property is read-only.

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)

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.

When SelectionType is 'row' or 'column' and MultiSelect is 'on', you can specify Selection as either a row or a column vector. However, MATLAB converts and stores the value as a row vector.

Difference Between Selection and DisplaySelection

The Selection and DisplaySelection properties both return the indices of the selected cells, but these indices correspond to different configurations of the table data and can be used for different purposes.

The two properties have the same values if a user does not sort or rearrange the table columns.

For example, create a table UI component with some data and with sortable columns. Then, sort the table by the values in the first column, and select the first row of the sorted table.

fig = uifigure;
tbl = uitable(fig,Data=[4 9; 7 1; 2 3],ColumnSortable=true);

Query the Selection property and the DisplaySelection property of the table. The Selection property returns the indices of the selected cells in the original table data.

tbl.Selection

ans =

     3     1
     3     2

The DisplaySelection property returns the indices of the selected cells in the displayed table data.

tbl.DisplaySelection

ans =

     1     1
     1     2

This property is read-only.

Table selection in the current display, returned as a positive integer, vector of positive integers, or n-by-2 array of positive integers. Use this property to query the table elements that the app user has selected as the selection appears in the current table display.

The type of value that DisplaySelection returns depends on the value of the SelectionType and Multiselect properties.

Difference Between Selection and DisplaySelection

The Selection and DisplaySelection properties both return the indices of the selected cells, but these indices correspond to different configurations of the table data and can be used for different purposes.

The two properties have the same values if a user does not sort or rearrange the table columns.

For example, create a table UI component with some data and with sortable columns. Then, sort the table by the values in the first column, and select the first row of the sorted table.

fig = uifigure;
tbl = uitable(fig,Data=[4 9; 7 1; 2 3],ColumnSortable=true);

Query the Selection property and the DisplaySelection property of the table. The Selection property returns the indices of the selected cells in the original table data specified using the Data property.

tbl.Selection

ans =

     3     1
     3     2

The DisplaySelection property returns the indices of the selected cells in the displayed table data.

tbl.DisplaySelection

ans =

     1     1
     1     2

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.

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.

Selection changed callback, specified as one of these values:

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.

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

The table executes the SelectionChangedFcn callback when the user changes the table selection by clicking, by using the arrow keys, or by using one of these keyboard shortcuts.

Contiguous selection options:

Noncontiguous selection options:

Display data changed callback, specified as one of these values:

This callback executes when the DisplayData changes. This occurs when the app user performs one of these actions:

Use this callback if you want information about user interactions that caused the DisplayData to change. If you need specific information about edited cells, create a CellEditCallback instead.

This callback function can access specific information about whether columns are sorted or rearranged or cells are edited. MATLAB passes this information in a DisplayDataChangedData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.InteractionColumn returns the index of the column that was interacted with in Data. The DisplayDataChangedData object is not available to callback functions specified as character vectors.

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

Clicked function, specified as one of these values:

This callback function executes when the user clicks anywhere in the table UI component.

This callback function can access specific information about the user’s interaction with the table. MATLAB passes this information in a ClickedData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.InteractionInformation returns information about where the user clicked in the table. The ClickedData object is not available to callback functions specified as character vectors.

This table lists the properties of the ClickedData object.

This table lists the properties of the InteractionInformation object associated with the table UI component.

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

Example: Select Background Color When Table Cell Is Clicked

Create a table UI component with some data. Specify a ClickedFcn callback function named colorCells that executes when a user clicks the table. In the colorCells function:

To try this example, save the code in a new script and run it. Click a cell in the table and select a background color for that cell.

fig = uifigure;
t = uitable(fig);
t.Data = rand(5);
t.ClickedFcn = @colorCells;

function colorCells(src,event)
r = event.InteractionInformation.Row;
c = event.InteractionInformation.Column;
if ~isempty(r) && ~isempty(c)
    removeStyle(src)
    color = uisetcolor;
    s = uistyle(BackgroundColor=color);
    addStyle(src,s,"cell",[r c]);
    focus(src)
end
end

Double-clicked callback, specified as one of these values:

This callback function executes when the user double-clicks anywhere in the table UI component.

This callback function can access specific information about the user’s interaction with the table. MATLAB passes this information in a DoubleClickedData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.InteractionInformation returns information about where the user double-clicked in the table. The DoubleClickedData object is not available to callback functions specified as character vectors.

This table lists the properties of the DoubleClickedData object.

This table lists the properties of the InteractionInformation object associated with the table UI component.

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

Example: Select Background Color When Table Cell Is Double-Clicked

Create a table UI component with some data. Specify a DoubleClickedFcn callback function named colorCells that executes when a user double-clicks the table. In the colorCells function:

To try this example, save the code in a new script and run it. Double-click a cell in the table and select a background color for that cell.

fig = uifigure;
t = uitable(fig);
t.Data = rand(5);
t.DoubleClickedFcn = @colorCells;

function colorCells(src,event)
r = event.InteractionInformation.Row;
c = event.InteractionInformation.Column;
if ~isempty(r) && ~isempty(c)
    removeStyle(src)
    color = uisetcolor;
    s = uistyle(BackgroundColor=color);
    addStyle(src,s,"cell",[r c]);    
    focus(src)
end
end

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

This property is read-only.

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.