Documentation

This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.

Uitable Properties

Control appearance and behavior of table

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 query and set properties.

t = uitable('Data',[1 2 3; 4 5 6; 7 8 9]);
d = t.Data;
t.Data = d + 1;

If you are using an earlier release, use the get and set functions instead.

Appearance

expand all

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 app start faster, set the Visible property of all uitables that are not initially displayed to 'off'.

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

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]

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

Example: t = uitable('Data',rand(10,3),'ForegroundColor',[0 0 1])

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

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

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 the long and short color name options and the equivalent RGB triplet values.

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]

Table Data

expand all

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

Table Layout

expand all

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 table has no row headings.

  • Empty matrix ([]) — The table has no row headings

If the number of rows in the Data property array does not match the number of elements in the RowName array, then the number of rows in the resulting table is the larger of the two values.

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

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

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 by including a vertical slash (|) in the column name. For example, the value, 'Telephone|Number', produces a column heading with a newline character between the words, "Telephone" and "Number".

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

  • Empty matrix ([]) — The table has no column headings

If the number of columns in the Data property array does not match the number of elements in the ColumnName array, then the number of columns in the resulting table is the larger of the two values.

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

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.

Cell Format Value

Description

'char'

Display a left-justified values

To edit a cell, the user types text to replace the existing value.

If an element in the Data property array is logical, then true or false appears in the table.

'logical'

Display check boxes.

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

The ColumnEditable property value must be true to allow users to select or 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 value equivalent to the Command Window display for numeric data. If an element in the Data property array is logical, then 1 or 0 appears in the table. If an element in the Data property array is not numeric and not logical, then NaN appears in the table.

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

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

A 1-by-n cell array of character vectors, such as {'one' 'two' 'three'}

Display a pop-up menu.

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 format name accepted by the format function, such as: 'short' or 'long'

Display the Data property values using the specified format.

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.

 ColumnFormat
'numeric''char''logical'
Data Type of Data Array ValueAny numeric typeTable displays number as-is.MATLAB converts the value to text and displays it left-justified in the table. If MATLAB cannot convert the value, then NaN displays.Not recommended. MATLAB might return a warning when the user edits the cell, unless you define a CellEditCallback function.
charTable displays the value right-justified, as if it is a number.Table displays the value as-is.Not recommended. MATLAB might return a warning when the user edits the cell, unless you define a CellEditCallback function.
logicalTable displays logical values as numbers. MATLAB might return a warning when the user edits the cell, unless you define a CellEditCallback function.Table displays logical value as left-justified 'true' or 'false'. MATLAB might return a warning when the user edits the cell, unless you define a CellEditCallback function.Table displays logical values as check boxes.

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

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

expand all

Location and size of the uitable, specified as a four-element vector of the form [left bottom width height]. This table describes each element in the vector.

ElementDescription
leftDistance from the inner left edge of the parent container to the outer left edge of the 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:   The Position values are relative to the parent container's drawable area. The drawable area is the area inside the borders of the container and does not include the area occupied by the title. If the parent container is a figure, then the drawable area also excludes 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: 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 uitable to match the Extent of the table:

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

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

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

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

Units ValueDescription
'pixels' (default)

Pixels.

Starting in R2015b, distances in pixels are independent of your system resolution on Windows® and Macintosh systems:

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

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

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

'normalized'These units are normalized with respect to the parent container. The lower-left corner of the container maps to (0,0) and the upper-right corner maps to (1,1).
'inches'Inches.
'centimeters'Centimeters.
'points'Points. One point equals 1/72nd of an inch.
'characters'

These units are based on the default uicontrol font of the graphics root object:

  • Character width = width of the letter x.

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

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

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

This property affects the Position property. If you change the units, then it is good practice to return it to its default value after completing your computation to prevent affecting other functions that assume Units is 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.

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.

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

Font Style

expand all

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

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

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.

Font size, 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: t = uitable('Data',rand(10,3),'FontSize',14)

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

Units ValueDescription
'points'Points. One point is 1/72nd of an inch.
'normalized'Normalized values for specifying the font size as a fraction of the uitable height. When you resize the uitable, MATLAB scales the displayed font to maintain that fraction.
'inches'Inches.
'centimeters'Centimeters.
'pixels'

Pixels.

Starting in R2015b, distances in pixels are independent of your system resolution on Windows and Macintosh systems:

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

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

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

Font weight, specified as one of these values:

  • 'normal' — Default weight as defined by the particular font

  • 'bold' — Thicker character outlines than normal

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.

    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.

Character slant, 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

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

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

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

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

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

NewData

Value that MATLAB wrote to the Data property array. This value 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 message, or it can attempt to fix the problem.

Source

Table object that is executing the CellEditCallback function.

EventName

'CellEdit'

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

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

  2. Calls the CellEditCallback function (if it exists)

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

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:

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

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

This callback function executes when the 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

  • Selects a rectangular group of cells by holding the Shift key while selecting the cells

  • 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 a CellSelectionChangeData object containing event data as the second argument to the callback function. This object contains the properties listed in the following table.

Property

Description

Indices

n-by-2 array containing the row and column indices of the cell the user selected.

Source

The table object that is executing the CellSelectionCallback function.

EventName

'CellSelection'

Ability to edit column cells, specified as:

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

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

  • A logical scalar— The entire table editable or uneditable.

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.

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

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

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

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

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

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

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

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

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

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

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

This callback function executes when the 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 text description.'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.

Key-release callback function, specified as one of these values:

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

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

This callback function executes when the 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', or an empty cell array if there is no modifier.

{1x0 cell}{1x0 cell}{1x0 cell}{1x0 cell}
Key

Name of the key that was released, identified by the lowercase label on the key, or a text description.

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

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

Tooltip text, specified as a character vector (e.g., 'Hello World'). 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 character vector containing the newline (\n) characters. Then set the TooltipString to the value returned by sprintf.

Example: Specify TooltipString Containing Two Lines

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

Data Types: char

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.

    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.

    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

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.

    • Timer objects execute according to schedule 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.

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 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 interrupting callback) determines if MATLAB enqueues or ignores the interrupting callback.

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

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

This property is read only.

Deletion status of uitable, returned as 'off' or 'on'. 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.

Uitable creation function, specified as one of these values:

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

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

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

Uitable deletion function, specified as one of these values:

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

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

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

Identifiers

expand all

This property is read only.

Type of graphics object, returned as 'uitable'.

Uitable identifier, specified as a character vector. This value to serves 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: t = uitable('Tag','table1')

Data to associate with the uitable object, specified as any array. Specifying UserData can be useful for sharing data values within and across UIs. 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'}

Parent/Child

expand all

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, uibuttongroup, or uitab.

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

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 option blocks access to the uitable at the command-line, but allows callback functions to access it.
'off'The uitable handle is invisible at all times. This option is useful for preventing unintended changes to the UI by another function. Set the HandleVisibility to 'off' to temporarily hide the 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.

Was this topic helpful?