Uitable Properties

Control uitable appearance and behavior

Uitables are tables that list data in a figure. The uitable function creates a table and sets any required properties before displaying it. By changing uitable property values, you can modify certain aspects of its appearance and behavior.

Starting in R2014b, you can use dot notation to refer to a particular object and property:

t = uitable;
fgcolor = t.ForegroundColor;
t.ForegroundColor = [0 0 1];

If you are using an earlier release, use the get and set functions to query and set properties.

Appearance

expand all

VisibleUitable visibility'on' (default) | 'off'

Uitable visibility, specified as 'on' or 'off'. When Visible is 'off', the uitable is not visible, but you can query and set its properties.

To make your GUI start faster, set the Visible property of all uitables that are not initially displayed to 'off'.

BackgroundColorUitable cell background colorRGB triplet | 2-by-3 matrix of RGB triplets

Uitable cell background color, specified as an RGB triplet or a 2-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]. If you specify a 2-by-3 matrix, then each row of the matrix must be an RGB triplet. Color names are not valid.

If you specify the background color as a 2-by-3 matrix, then MATLAB® uses the second row of the matrix when the RowStriping property is 'on'. The table background is not striped unless both RowStriping is 'on' and the background color is a 2-by-3 matrix.

The following table lists the RGB triplets for commonly used 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]

Example: [1 1 1]

Example: [1 1 1; .9 .9 .9]

ForegroundColorCell text color[0 0 0] (default) | RGB triplet | short name | long name

Cell text color, specified as an RGB triplet, short name, or long name. The color you specify sets the text color for all cells.

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]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Example: [0 0 1]

Example: 'b'

Example: 'blue'

Location and Size

expand all

PositionLocation and size of uitable[left bottom width height]

Location and size of the uitable relative to the parent, specified as the vector, [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 uitable
bottomDistance from the inner bottom edge of the parent container to the outer bottom edge of the uitable
widthDistance between the right and left outer edges of the uitable
heightDistance between the top and bottom outer edges of the uitable

All measurements are in units specified by the Units property.

    Note:   If the parent of the uitable is a figure, then the Position values are relative to the figure's drawable area. The drawable area of a figure is the area inside the window borders, excluding the menu bar and tool bar.

Use the Extent property to determine proper sizing for a uitable with respect to the table 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: [0 0 300 300]

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 Postion vector. For example, this code sets the width and height of the uitable to match the Extent of the table:

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

UnitsUnits of measurement'pixels' (default) | 'normalized' | 'inches' | 'centimeters' | 'points' | 'characters'

Units of measurement, specified as 'pixels', 'normalized', 'inches', 'centimeters', 'points', or 'characters'.

MATLAB uses these units to interpret the location and size values of the Position property:

  • The size of a uitable specified in pixel units depends on the system display settings and resolution.

  • Normalized units map the lower left corner of the parent container to (0,0) and the upper right corner to (1.0,1.0).

  • Inches, centimeters, and points are absolute units. 1 point = 1/72 inch.

  • Character units are determined by the default system font. Each character unit is the width of the letter x. The height of each character unit is the distance between the baselines of two lines of text.

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

If you change the value of the Units property, it is good practice to return it to its default value after completing your computation to avoid affecting other functions that assume the Units property is set to the default value.

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

  • If you specify the Units before the Position property, then MATLAB sets Position using the units you specify.

  • If you specify the Units property after the Position property, MATLAB sets the position using the default Units. Then, MATLAB converts the Position value to the equivalent value in units you specify.

ExtentSize of uitable rectanglefour-element row vector

This property is read only.

Size of the uitable 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 uitable, 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.

When the uitable Units property is set to 'normalized', the Extent values are measured relative to the figure, regardless of whether the uitable is contained in (parented to) a uipanel.

Consider using the Extent property value when specifying the width and height values of the uitable Position property.

Font Style

expand all

FontNameFont for displaying cell contentstring

Font for displaying the cell content, specified as a string. To display and print properly, this must be a font that your system supports. To display and print properly, the font name must refer to a font that the user's system supports. The default font is system dependent.

To use a fixed-width font, set the FontName property to the string, 'FixedWidth'. This setting instructs MATLAB to use the value of the root FixedWidthFontName property, which you can set in the startup.m file.

For more information about the startup.m file, see Specifying Startup Options in MATLAB Startup File

Example: 'Arial'

FontSizeFont size for uitable cell contentpositive number

Font size for the uitable cell content, specified as a positive number. MATLAB uses the units specified by FontUnits. The default size is system-dependent. If you set FontUnits to 'normalized', then the FontSize value is a number between 0 and 1.

Example: 12

Example: 12.5

Data Types: double

FontUnitsUnits of font size for uitable cell contents'points' (default) | 'normalized' | 'inches' | 'centimeters' | 'pixels'

Units of font size for the uitable cell contents, specified as 'points', 'normalized', 'inches', 'centimeters', or 'pixels'.

If you set this property to 'normalized', then MATLAB interprets the font size as a fraction of the uitable height. When you resize the uitable, MATLAB scales the displayed font to maintain that fraction.

The other FontUnits options (pixels, inches, centimeters, and points) are absolute units. 1 point = 1/72 inch.

FontWeightFont weight for uitable cell contents'normal' (default) | 'bold'

Font weight for the uitable cell contents, specified as a value from the following table.

FontWeight ValueDescription
'normal'Normal font weight
'bold'Heavy font weight

Not all fonts support all font weights. Therefore, if you specify an unsupported value for the FontWeight property, the result might appear the same as the default.

    Note:   The 'light' and 'demi' font weight values have been removed in R2014b. If you specify either of these values, the result is a normal font weight.

FontAngleCharacter slant of uitable cell contents'normal' (default) | 'italic'

Character slant of the uitable cell contents, 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.

    Note:   The 'oblique' value has been removed. Use 'italic' instead.

Interactive Control

expand all

CellEditCallbackCell edit callback functionfunction handle | cell array | string

Cell edit callback function, specified as a function handle, 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This function makes the uitable respond 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 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

Indices

1-by-2 array containing the row and column indices of the cell the user edited.

PreviousData

Previous cell data. The default is an empty matrix, [].

EditData

User-entered string.

NewData

Value that MATLAB wrote to the Data property array. It is either the same as EditData or a converted value.

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

Error

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 string, or it can attempt to fix the problem.

When the user edits a cell, MATLAB attempts to store the user-entered value in the Data property, converting the value if necessary. Next, MATLAB calls the CellEditCallback function and passes the callback data. If there is no CellEditCallback function, and the user-entered data results in an error, then the contents of the cell 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 mygui
    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 mygui, 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.

CellSelectionCallbackCell selection callback functionfunction handle | cell array | string

Cell selection callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

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

  • Highlights a data cell (not a row or column header cell) by clicking it or navigating to it with an arrow key

  • Adds a new cell to their selection by Shift-clicking it

  • Deselects a cell by Ctrl-clicking it

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 one property, Indices. The Indices property is an n-by-2 array containing the row index and column index of the selected cells.

Example: @myfun

Example: {@myfun,x}

ColumnEditableAbility to edit column cellsempty matrix ([]) (default) | logical 1-by-n array | scalar logical value

Ability to edit column cells, specified as:

  • An empty matrix ([]) — No columns are editable.

  • A logical 1-by-n array — Specify which columns are editable. The value of n is equal to the number of columns in the table. A value of true in the array makes that the cells in a column are editable. A value of false makes the cells in a column uneditable. Each value in the array corresponds to a table column.

  • A scalar logical value — Make the entire table editable or uneditable.

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

Example: []

Example: [false true true]

Example: false

RearrangeableColumnsAbility to rearrange table columns'off' (default) | 'on'

Ability to rearrange table columns, specified as 'off' or 'on'. This property provides a way let users reorder the table columns (but not the labels) by clicking and dragging the column headers.

    Note:   Rearranging table columns in the GUI does not affect the ordering of the columns the Data property array.

ButtonDownFcnButton-press callback function'' (default) | function handle | cell array | string

Button-press callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

The ButtonDownFcn callback is a function that executes when the user clicks a mouse button on the uitable. The callback executes in the following situations:

  • The user right-clicks the uitable, and the uitable Enable property is set to 'on'.

  • The end user right-clicks or left-clicks the Uitable, and the uitable Enable property is set to 'off' or 'inactive'.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

KeyPressFcnKey press callback function'' (default) | function handle | cell array | string

Key press callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback function executes when the uitable 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 uitable, 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 descriptive string.'a''equal''shift''a'
SourceThe object that has focus when the user presses the key.uitable objectuitable objectuitable objectuitable 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.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

KeyReleaseFcnKey-release callback function'' (default) | function handle | cell array | string

Key-release callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback function executes when the uitable 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'. This value is always an empty cell array for aseFcn callbacks.

{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 descriptive string.

'a''equal''shift''a'
SourceThe object that has focus when the user presses the key.uitable objectuitable objectuitable objectuitable 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.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

EnableOperational state of uitable'on' (default) | 'inactive' | 'off'

Operational state of uitable, specified as 'on', 'off', or 'inactive'. The Enable property controls whether the uitable responds to button clicks. The are three possible values:

  • 'on' – The uitable is operational.

  • 'off' – The uitable is not operational and appears grayed-out.

  • 'inactive' – The uitable is not operational, but it has the same appearance as when Enable is 'on'.

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

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

The uitable's CellSelectionCallback function executes (only for table cells, not header cells). The Indices property updates in the callback data object that MATLAB passes to the callback function.

  1. The figure's WindowButtonDownFcn callback executes.

  2. The uitable ButtonDownFcn callback executes.

'off' or 'inactive'
  1. The figure's WindowButtonDownFcn callback executes.

  2. The uitable's ButtonDownFcn callback executes.

  1. The figure's WindowButtonDownFcn callback executes.

  2. The uitable's ButtonDownFcn callback executes.

TooltipStringTooltip textstring

Tooltip text, specified as a string. When the user hovers the mouse pointer over the uitable and leaves it there, the tooltip displays. If you want to create a tooltip that has more than one line of text, use sprintf to generate a string containing newline (\n) characters and then set the TooltipString to that string.

Example: 'Some string'

Example: Specify TooltipString Containing Two Lines

t = uitable;
s = sprintf('UITable tooltip line 1\nUITable tooltip line 2');
t.TooltipString = s;

Data Types: char

UIContextMenuUitable context menuempty GraphicsPlaceholder array (default) | uicontextmenu object

Uitable context menu, specified as a uicontextmenu object. Use this property to display a context menu when the user right-clicks on the uitable. Create the context menu using the uicontextmenu function.

SelectedSelection status of uitable'off' (default) | 'on'

    Note:   The behavior of the Selected property changed in R2014b, and it is not recommended. It no longer has any effect on uitables. This property might be removed in a future release.

SelectionHighlightAbility to highlight selection handles'on' (default) | 'off'

    Note:   The behavior of the SelectionHighlight property changed in R2014b, and it is not recommended. It no longer has any effect on uitables. This property might be removed in a future release.

Callback Execution Control

expand all

BusyActionCallback queuing'queue' (default) | 'cancel'

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 running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

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

  • 'queue' — Put the interrupting callback in a queue to be processed after the running callback finishes execution.

  • 'cancel' — Do not execute the interrupting callback.

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:

  • on — Interruption occurs at the next point where MATLAB processes the queue. This is the default.

  • off — The BusyAction property (of the object owning the executing callback) determines if MATLAB enqueues or ignores the interrupting callback.

InterruptibleCallback interruption'on' (default) | 'off'

Callback interruption, specified as 'on' or 'off'. The Interruptible 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. The Interruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put into a queue.

If a uitable callback is the running callback, then the Interruptible property determines if it can be interrupted by another callback. The Interruptible property has two possible values:

  • 'on' — A callback can interrupt the running callback. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, getframe, waitfor, or pause.

    • If the running callback contains one of these commands, then MATLAB stops the execution of the callback at this 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 these commands, then MATLAB finishes executing the callback without interruption.

  • 'off' — A callback cannot interrupt the running callback. MATLAB finishes executing the running callback without any interruptions. This is the default behavior.

    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.

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

HitTestAbility to become current object'on' (default) | 'off'

Ability to become current object, specified as 'on' or 'off':

  • Setting the value to 'on' allows the uitable to become the current object when the user clicks on it. A value of 'on' also allows the figure CurrentObject property and the gco function to report the uitable as the current object.

  • Setting the value to 'off' sets the figure CurrentObject property to an empty GraphicsPlaceholder array when the user clicks on the uitable.

    Note:   Use the Enable property to enable or disable a uitable.

Creation and Deletion Control

expand all

BeingDeletedDeletion status of uitable'off' (default) | 'on'

This property is read only.

Deletion status of uitable, returned as 'on' or 'off'. MATLAB sets the BeingDeleted property to 'on' when the delete function of the uitable begins execution (see the DeleteFcn property). The BeingDeleted property remains set to 'on' until the uitable no longer exists.

Check the value of the BeingDeleted property to verify that the uitable is not about to be deleted before querying or modifying it.

CreateFcnUitable creation functionfunction handle | cell array | string

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This property specifies a callback function to execute when MATLAB creates the uitable. MATLAB initializes all uitable 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 handle to the uitable that is being created.

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

    Note:   Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. Copying the uitable object causes the CreateFcn callback to execute repeatedly.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnUitable deletion functionfunction handle | cell array | string

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

The DeleteFcn property specifies a callback function to execute when MATLAB deletes the uitable (for example, when the end user deletes the figure). MATLAB executes the DeleteFcn callback before destroying the properties of the uitable. 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 handle to the uitable that is being deleted.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

TagUitable identifier'' (default) | string

Uitable identifier, specified as a string. You can specify a unique Tag value to serve as an identifier for the uitable. When you need access to the uitable elsewhere in your code, you can use the findobj function to search for the uitable based on the Tag value.

Example: 'table1'

Data Types: char

UserDataData to associate with the uitable objectempty array (default) | array

Data to associate with the uitable object, specified as any array. Specifying UserData can be useful for sharing data values within and across GUIs you create. See Share Data Among Callbacks for more information.

Example: [1 2 3]

Example: 'April 21'

Example: struct('value1',[1 2 3],'value2','April 21')

Example: {[1 2 3],'April 21'}

TypeType of graphics object'uitable'

This property is read only.

Type of graphics object, returned as 'uitable'.

Parent/Child

expand all

ParentUitable parentfigure | uipanel | uibuttongroup | uitab

Uitable parent, specified as a figure, uipanel, uibuttongroup, or uitab. You can move a uitable to a different figure, uipanel, uibuttongroup, or uitab by setting this property to the handle of the target figure, uipanel, uibuttgroup, or uitab.

ChildrenChildren of uitableempty array

Children of uitable, returned as an empty array. Uitable objects have no children. Setting this property has no effect.

HandleVisibilityVisibility of Uitable handle'on' (default) | 'callback' | 'off'

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

This property controls the visibility of the uitable 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 know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

HandleVisibility ValueDescription
'on'The uitable handle is always visible.
'callback'The uitable handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This protects the GUI from command-line users, while allowing callback routines to have complete access.
'off'The uitable handle is invisible at all times. This option might be useful when a callback routine invokes a function that might potentially damage the GUI (such as a function that evaluates user-typed strings). You can set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

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.

Table Data

expand all

DataTable contentnumeric array | cell array

Table content, specified as a numeric 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.

The ColumnFormat property specifies the format for displaying the table contents. Therefore, if there is a mismatch between the data type of the Data property array and the ColumnFormat property, MATLAB converts the data value 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: rand(10,3)

Example: {'blue' 5 true; 'orange' 25 false}

Table Layout

expand all

RowName Row heading names'numbered' (default) | n-by-1 cell array of strings | empty cell array ({} ) | empty matrix ([])

Row heading names, specified as one of these values:

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

  • Cell array — Each element of the cell 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 a n-by-1 cell array.

  • Empty cell array ({}) — The resulting table has no row headings.

  • Empty matrix ([]) — The resulting 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 is the larger of the two values.

Example: {'Name';'Telephone Number'}

Example: {'Name';[]}

ColumnNameColumn heading names'numbered' (default) | n-by-1 cell array of strings | empty cell array ({} ) | empty matrix ([])

Column heading names, specified as one of these values:

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

  • Cell array — Each element of the cell array becomes the name of a column. If you specify a 1-by-n cell array, MATLAB stores and returns the value as a n-by-1 cell array. Specify a multiline column name as a string vector separated by vertical slash (|) characters. For example, the value, 'Telephone|Number', produces a column heading with a newline character between the words, "Telephone" and "Number".

  • Empty cell array ({}) — The resulting table has no column headings.

  • Empty matrix ([]) — The resulting 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.

Example: {'Name'; 'Telephone Number'}

Example: {'Name'; []}

Example: {'Name'; 'Telephone|Number'}

ColumnWidthWidth of table columns'auto' (default) | 1-by-n cell array

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

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

Example: {64 60 40}

Example: {64 'auto' 40}

ColumnFormat Cell display formatempty cell array ({}) (default) | 1-by-n cell array of strings

Cell display format, specified as an empty cell array or a cell array of strings.

This property determines how the data in each column displays and the constraints for editing that data in the GUI. The length of the cell array must equal the number of columns in the table, and 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 strings described in the following table.

Cell Format

Description

'char'

Display a left-justified string.

To edit a cell, the user types a string that replaces the existing string.

'logical'

Display a check box.

To edit a cell, the user selects or clears the check box. Then, MATLAB sets the corresponding Data value to true or false accordingly.

The ColumnEditable property value must be true to allow users to select or deselect the check boxes.

Initially, a check box is selected when the corresponding Data value is true. The corresponding values in the Data property array must be of type logical to ensure the data displays correctly in the table.

'numeric'

Display a right-justified string 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 string.

If a user enters a string representing 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 string 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 strings. For example, {'one' 'two' 'three'}

Display a pop-up menu.

To edit a cell, the user selects an item from the pop-up menu. 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 string accepted by the format function, such as: 'short', 'bank', 'long'

Display the Data property values using the specified format.

Effect of Pop-Up Menu ColumnFormat and Various Data Types

The initial Data values do not have to be items in the pop-up menu. If the ColumnFormat value defines a pop-up menu, that pop-up menu displays the corresponding value in Data property until the user makes a selection.

For instance, suppose the Data property value for a given column is the string, 'Choose' in all the 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.

 ColumnFormat
'numeric''char''logical'
Data Type of Data Array ValueAny numeric typeTable displays number as-is.MATLAB converts the value to a text string and displays it left-justified in the table.Not recommended. MATLAB might return a warning when the user edits the cell, unless you define a CellEditCallback function.
charMATLAB converts the text string to a double value. If MATLAB cannot convert the string, thenNaN displays. See str2double for more information.Table displays the string 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 '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.

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

RowStripingAlternate row shading'on' (default) | 'off'

Alternate row shading, specified as 'on' or 'off'. This property controls the shading pattern of the table rows.

When the RowStriping value is set to 'on', the BackgroundColor matrix specifies the background color of consecutive rows . The first color matrix row defines the shading for odd-numbered rows in the table. The second color matrix row defines the shading for even-numbered rows. 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 property defines the shading for all rows in the table.

Was this topic helpful?