Table data, specified as a numeric array, logical array, or cell array. The table data can be any numeric type, logical, or char. Use a cell array to specify a mixture of different data types.

Table data is displayed in the format specified by the ColumnFormat property. If there is a mismatch between the data type of the table data and the value of the ColumnFormat property, MATLAB^® converts the data or displays a warning. See the ColumnFormat property description for more information.

To prevent warnings that might occur when users enter invalid data, write a CellEditCallback function to convert the data to the appropriate type.

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 is the larger of the two values. The same is true when the ColumnName property does not match the number of columns in the Data property array.

Example: t = uitable('Data',rand(10,3))

Example: t = uitable('Data',{'blue' 5 true; 'orange' 25 false})

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

Example: t = uitable('ColumnName',{'Name'; 'Number'},'Data',{'Bob' 5})

Example: t = uitable('ColumnName',{'Name'; []},'Data',{'Bob' 5})

Example: t = uitable('ColumnName',{'Name'; 'Telephone|Number'},'Data',{'Bob','555-1212'})

Width of table columns, specified as 'auto' or as a 1-by-n cell array.

Each column in the cell array corresponds to a column in the table. The values are in pixel units. If you specify 'auto', then MATLAB calculates the width of the column automatically using several factors, one of which is the ColumnName property value.

You can combine fixed column widths and 'auto' column widths in a cell array, or you can specify a single value of 'auto' to make all column widths automatic.

Selecting Auto Width in the Table Property Editor has the same effect as setting the ColumnWidth property to 'auto'.

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

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

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

Ability to edit column cells, specified as:

Example: t = uitable('Data',rand(10,3),'ColumnEditable',[false true true])

Example: t = uitable('Data',rand(10,3),'ColumnEditable',false)

Table columns that contain check boxes or pop-up menus must be editable so the user can interact with these controls.

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

This property determines how the data in each column displays, and the constraints for editing that data in the UI. 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 following 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:

f = figure;
myData = {'Andrew' 31 'Male' 'Choose'; ...
          'Bob' 41 'Male' 'Choose';  ...
          'Anne' 20 'Female' 'Choose';};
t = uitable('Parent', f,...
            'Position', [25 25 334 78],...            
            '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.

For example, in the following table, the first column (X-Data) is left justified because the ColumnFormat value for that column is 'char'.

Row heading 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 is the larger of the two values.

Example: t = uitable('RowName',{'Name';'Number'},'Data',{'Bob';5})

Example: t = uitable('RowName',{'Name';[]},'Data',{'Bob';5})

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.

Font name, specified as a system supported font name or 'FixedWidth'. The default font depends on the specific operating system and locale.

To use a fixed-width font that looks good in any locale, specify 'FixedWidth'. 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.

Example: 'Arial'

Font size, specified as a positive number. The FontUnits property specifies the units. The default size is system-dependent.

Example: 12

Example: 12.5

Font weight, specified as a value from the following table.

MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold font weight. Therefore, specifying a bold font weight still can result in the normal font weight.

Font angle, specified as 'normal' or 'italic'. MATLAB uses this property to select a font from those available on your system. Setting this property to 'italic' selects a slanted version of the font, if it is available on your system.

Font units, specified as one of the values from this table.

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, string scalar, or categorical array. Use this property to display a message when the user hovers the pointer over the component at run time. The tooltip does not display when the component is disabled. If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.

To create multiple lines of text, use the sprintf function to insert newline characters ('\n') in your text. For example:

txt = sprintf('Line 1\nLine 2');

Then set the Tooltip property to the value returned by sprintf.

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.

Tooltip, specified as a character vector, string scalar, or categorical array. The tooltip appears when you hover over the component in the app. If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.

Cell text color, specified as an RGB triplet, a hexadecimal color code, or one of the color options listed in the table.

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.

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: t = uitable('Data',rand(10,3),'BackgroundColor',[0.85 0.85 1])

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

The following table lists the RGB triplets for certain colors.

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

Use the Extent property to determine proper sizing for a table with respect to the data. Set the width and height of Position property to the width and height of the Extent property. Be aware that if the table has large extents, doing this can cause the table to extend beyond the right or top edge of its parent container.

Example: Set Width and Height to Accommodate Data Size

You can combine dot notation and array indexing when you want to change one or two consecutive values in the Position vector. For example, this code sets the width and height of the table to match the Extent of the table:

t = uitable('Data',rand(10,3));
t.Position(3:4) = t.Extent(3:4);

Location and size, 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, 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.

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.

Units of measurement, specified as one of the values from this table.

MATLAB measures all units from the lower left corner of the parent object.

This property affects the Position property. If you change the Units property, consider returning its value to the default value after completing your computation to avoid affecting other functions that assume the default value.

The order in which you specify the Units and Position properties has these effects:

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

This function executes when the user changes the contents of a table cell. You can use this callback function to perform calculations or validate user input.

If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes a CellEditData object containing event 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.

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.

Example: Evaluate User Input

This example shows how to create a callback function that evaluates a user-entered data in a numeric table cell. Paste this code into an editor and run it to see how it works.

function myui
    f = figure;
    myData = { 'A '  31; 'B'  41; 'C'  5; 'D' 2.6};
    t = uitable('Parent',f,...
                'Position', [25 25 700 200], ...
                'Data',myData,...
                'ColumnEditable', [false true], ...
                'CellEditCallback',@converttonum);
        function converttonum(hObject,callbackdata)
             numval = eval(callbackdata.EditData);
             r = callbackdata.Indices(1)
             c = callbackdata.Indices(2)
             hObject.Data{r,c} = numval; 
        end
end

When you run myui, you can change a value in the second column of the table. In response, the converttonum callback function executes. The converttonum function uses the eval function to evaluate your input. Then, it sets the cell data to the value of numval. For example, if you enter pi or1+1, the converttonum function sets the table cell value to a numeric representation of the input. Because there is no error checking in the converttonum function, invalid expressions return an error and the new value of the table cell becomes NaN.

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

This callback function executes when the user performs one of the following actions:

If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes a CellSelectionChangeData object containing event data as the second argument to the callback function. This object contains the properties listed in the following table.

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

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

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

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.

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

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

Use the gcbo function in your CreateFcn code to get the component object that is being created.

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

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

The DeleteFcn property specifies a callback function to execute when MATLAB deletes the component (for example, when the user closes the window). MATLAB executes the DeleteFcn callback before destroying the properties of the component object. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

Use the gcbo function in your DeleteFcn code to get the component object that is being deleted.

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.

The Interruptible property determines if a running callback can be interrupted. There are two callback states to consider:

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:

See Interrupt Callback Execution for an example that shows how the Interruptible and BusyAction properties affect the behavior of a program.

Callback queuing specified as 'queue' (default) or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

The BusyAction property of the source of the interrupting callback determines how MATLAB handles its execution. The BusyAction property has these values:

Whenever MATLAB invokes a callback, that callback always attempts to interrupt an executing callback. The Interruptible property of the object whose callback is running determines if interruption is allowed. If Interruptible is set to:

See Interrupt Callback Execution for an example that shows how the BusyAction and Interruptible properties affect the behavior of a program.

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 object, specified as a Figure, Panel, ButtonGroup, or Tab object. Use this property to specify the parent container when creating a UI component or to move an existing UI component to a different parent container.

Table children, returned as an empty array. Table objects have no children. Setting this property has no effect.

Visibility of object handle, specified as 'on', 'callback', or 'off'.

This property controls the visibility of the object handle in its parent's list of children. When a handle is not visible in its parent's list of children, it is not returned by functions that obtain handles by searching the object hierarchy or querying handle properties. These functions include get, findobj, gca, gcf, gco, newplot, cla, clf, and close. The HandleVisibility property also controls the visibility of the object’s handle in the parent figure's CurrentObject property. Handles are still 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.

Set the graphics root ShowHiddenHandles property to 'on' to make all handles visible, regardless of their HandleVisibility value. This setting has no effect on their HandleVisibility values.

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 array. Specifying UserData can be useful for sharing data within apps. See Share Data Among Callbacks for more information.