MATLAB Function Reference

Uitable Properties - Describe table properties

Modifying Properties

You can set and query graphics object properties in two ways:

• The Property Inspector is an interactive tool that enables you to see and change object property values. The Property inspector is available from GUIDE, or use the inspect function at the command line.

• The set and get functions enable you to set and query the values of properties.

You can set default uitable properties by typing:

set(h,'DefaultUitablePropertyName',PropertyValue...)

Where h can be the root handle (0), a figure handle, or a uitable handle. PropertyName is the name of the uitable property and PropertyValue is the value you specify as the default for that property.

For more information about changing the default value of a property see Setting Default Property Values. For an example, see the CreateFcn property.

Uitable Properties

This section lists all properties useful to uitable objects along with valid values and descriptions of their use. In the property descriptions, curly braces { } enclose default values.

BackgroundColor

2-by-3 matrix of RGB triples

Cell background color. Color used to fill the uitable cells. Specify as an 2-by-3 matrix of RGB triples, such as [1 1.9; .9 1 1]. Each row is an RGB triplet of real numbers between 0.0 and 1.0 that defines one color. The default is a 1–by-3 matrix of platform-dependent colors. See ColorSpec for information about RGB colors.

Row 2 and subsequent rows of the matrix are used only if the RowStriping property is on.

BeingDeleted

on | {off} (read-only)

This object is being deleted. The BeingDeleted property provides a mechanism that you can use to determine if objects are in the process of being deleted. MATLAB^® software sets the BeingDeleted property to on when the object's delete function callback is called (see the DeleteFcn property) It remains set to on while the delete function executes, after which the object no longer exists.

For example, some functions may not need to perform actions on objects that are being deleted, and therefore, can check the object's BeingDeleted property before acting.

BusyAction

cancel | {queue}

Callback routine interruption. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, the callback associated with the new event uses the value of BusyAction to decide whether or not to attempt to interrupt the executing callback.

• If the value is cancel, the new event is discarded and the second callback does not execute.

• If the value is queue, and the Interruptible property of the first callback is on, the second callback is added to the event queue and executes in its turn after the first callback finishes execution.

Note   If the interrupting callback is DeleteFcn or CreateFcn or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of that object's Interruptible property. See the Interruptible property for information about controlling a callback's interruptibility.

ButtonDownFcn

string or function handle (GUIDE sets this property)

Button-press callback routine. A callback routine that can execute when you press a mouse button while the pointer is on or near a uitable. Specifically:

• If the uitable Enable property is set to on, the ButtonDownFcn callback executes when you click the right or left mouse button in a 5-pixel border around the uitable or when you click the right mouse button on the control itself.

• If the uitable Enable property is set to inactive or off, the ButtonDownFcn executes when you click the right or left mouse button in the 5-pixel border or on the control itself.

This is useful for implementing actions to interactively modify control object properties, such as size and position, when they are clicked on (using the selectmoveresize function, for example).

Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace.

To add a ButtonDownFcn callback in GUIDE, select View Callbacks from the Layout Editor View menu, then select ButtonDownFcn. GUIDE sets this property to the appropriate string and adds the callback to the M-file the next time you save the GUI. Alternatively, you can set this property to the string %automatic. The next time you save the GUI, GUIDE sets this property to the appropriate string and adds the callback to the M-file.

CellEditCallback

function handle, cell array containing function handle and additional arguments, or string (not recommended)

Callback to edit user-entered data

Callback function executed when the user modifies a table cell. It can perform evaluations, validations, or other customizations. If this function is called as a function handle, uitable passes it two arguments. The first argument, source, is the handle of the uitable. The second argument, eventdata, is an event data structure that contains the fields shown in the following table. All fields in the event data structure are read only.

Event Data Structure Field	Type	Description
Indices	1-by-2 matrix	Row index and column index of the cell the user edited.
PreviousData	1-by-1 matrix or cell array	Previous data for the changed cell. The default is an empty matrix, [].
EditData	String	User-entered string.
New Data	1-by-1 matrix or cell array	Value that uitable wrote to Data. It is either the same as EditData or a converted value, for example, 2 where EditData is '2' and the cell is numeric. Empty if uitable detected an error in the user-entered data and did not write it to Data.
Error	String	Error that occurred when uitable tried to convert the EditData string into a value appropriate for Data. For example, uitable could not convert the EditData string consistent with the Column Format property, if any, or the data type for the changed cell. Empty if uitable wrote the value to Data. If Error is not empty, the CellEditCallback can pass the error string to the user or can attempt to manipulate the data. For example, the string 'pi' would raise an error in a numeric cell but the CellEditCallback could convert it to its numerical equivalent and store it in Data without passing the error to the user.

When a user edits a cell, uitable first attempts to store the user-entered value in Data, converting the value if necessary. It then calls the CellEditCallback and passes it the event data structure. If there is no CellEditCallback and the user-entered data results it an error, the contents of the cell reverts to its previous value and no error is displayed.

CellSelectionCallback

functional handle, cell array containing function handle and additional arguments, or string (not recommended)

Callback that executes when cell is selected. Callback function that executes when the user highlights a cell by navigating to it or clicking it. For multiple selection, this callback executes when new cells are added to the selection.

Children

matrix

The empty matrix; uitable objects have no children.

Clipping

{on} | off

This property has no effect on uitable objects.

ColumnEditable

logical 1–by-n matrix | scalar logical value |{ empty matrix ([])}

Determines if column is user-editable.

Determines if the data can be edited by the end user. Each value in the cell array corresponds to a column. False is default because the developer needs to be aware of editability.

Specify elements of a logical matrix astrue if the data in a column is editable by the user or false if it is not. An empty matrix indicates that no columns are editable.

Columns that contain check boxes or pop-up menus must be editable for the user to manipulate these controls. Elements of the ColumnEditable matrix must be in the same order as columns in the Data property. If you do not specify ColumnEditable, the default is an empty matrix ([]).

ColumnFormat

cell array of strings

Cell display formatting. Determines how the data in each column displays and is edited. Elements of the cell array must be in the same order as table columns in the Data property. If you do not want to specify a display format for a particular column, enter [] as a placeholder. If no format is specified for a column, the default display is determined by the data type of the data in the cell. Default ColumnFormat is an empty cell array ({}). In most cases, the default is similar to the command window.

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

Cell Format	Description
'char'	Displays a left-aligned string. To edit, the user types a string that replaces the existing string.
'logical'	Displays a check box. To edit, the user checks or unchecks the check box. uitable sets the corresponding Data value to true or false accordingly. Initially, the check box is checked if the corresponding Data value would produce true if passed to the logical function, and unchecked otherwise.
'numeric'	Displays a right-aligned string equivalent to the command window, for numeric data. If the cell Data value is boolean, then 1 or 0 is displayed. If the cell Data value is not numeric and not boolean, then NaN is displayed. To edit, the user can enter any string. This enables a user to enter a value such as 'pi' that can be converted to its numeric equivalent by a CellEditCallback. The uitable function first attempts to convert the user-entered string to a numeric value and store it in Data. It then calls the CellEditCallback. See CellEditCallback for more information.
1–by-n cell array of strings that define a pop-up menu, e.g., {'one' 'two' 'three'}	Displays a pop-up menu. To edit, the user makes a selection from the pop-up menu. uitable sets the corresponding Data value to the selected menu item. The initial values for the pop-up menus in the column are the corresponding strings in Data. These initial values do not have to be items in the pop-up menu. See Example 3 on the uitable reference page.
Valid string accepted by the format function, e.g.,'format short', '$ FORMAT BANK USD'	Displays the Data value using the specified format.

In some cases, you may need to insert an appropriate column in Data. If Data is a numerical or logical matrix, you must first convert it to a cell array using the mat2cell function.

Data and ColumnFormat

When you create a table, you must specify value of Data. The Data property dictates what type of data can exist in any given cell. By default, the value of the Data also dictates the display of the cell to the end user, unless you specify a different format using the ColumnFormat property.

ColumnFormat controls the presentation of the Data to the end user. Therefore, if you specify a ColumnFormat of char (or pick Text from the Table Property Editor), you are asking the table to display the Data associated with that column as a string. For example, if the Data for a particular column is numeric, and you specify the ColumnFormat as char, then the display of the numeric data will be left-aligned

If your column is editable and the user enters a number, the number will be left-aligned. However, if the user enters a text string, the table displays a NaN.

Another possible scenario is that the value Data is char and you set the ColumnFormat to be a pop-up menu. Here, if the value of the Data in the cell matches one of the pop-up menu choices you define in ColumnFormat, then the Data is shown in the cell. If it does not match, then the cell defaults to display the first option from the choices you specify in ColumnFormat. Similarly, if Data is numeric or logical with the ColumnFormat as pop-up menu, if the Data value in the cell does not match any of the choices you specify in ColumnFormat, the cell defaults to display the first option in the pop-menu choice.

This table describes how Data values correspond with your ColumnFormat when the columns are editable.

		ColumnFormat Selections
		numeric	char	logical
Data Type	numeric	Values match. MATLAB displays numbers as is.	MATLAB converts the text string entered to a double. See str2double for more information. If string cannot be converted, NaN is displayed.	Does not work: warning is thrown. Note   If you have defined CellEditCallback, this warning will not be thrown
	char	MATLAB converts the entered number to a text string.	Values match. MATLAB displays the string as is.	Does not work: warning is thrown. Note   If you have defined CellEditCallback, this warning will not be thrown
	logical	Does not work: warning is thrown. Note   If you have defined CellEditCallback, this warning will not be thrown	If text string entered is true or false, MATLAB converts string to the corresponding logical value and displays it. For all others, it Does not work: warning is thrown. Note   If you have defined CellEditCallback, this warning will not be thrown	Values match. MATLAB displays logical value as a check box as is.

If you get a mismatch error, you have the following options:

• Change the ColumnFormat or value of Data to match.

• Implement the CellEditCallback to handle custom data conversion.

ColumnName

1–by-n cell array of strings| {'numbered'} | empty matrix ([])

Column heading names. Each element of the cell array is the name of a column. Multiline column names can be expressed as a string vector separated by vertical slash (|) characters, e.g.,'Standard|Deviation'

For sequentially numbered column headings starting with 1, specify ColumnName as 'numbered'. This is the default.

To remove the column headings, specify ColumnName as the empty matrix ([]).

The number of columns in the table is the larger of ColumnName and the number of columns in the Data property matrix or cell array.

ColumnWidth

1–by-n numerical matrix or cell array

Column widths. The width of each column in units specified by the Units property. Each value in the matrix or cell array corresponds to a column. The width of the column name, as specified in ColumnName, is used to determine the width of a column if ColumnWidth is a cell array and the width of that column is set to [].

CreateFcn

string or function handle

Callback routine executed during object creation. The specified function executes when MATLAB software creates a uitable object. MATLAB software sets all property values for the uitable before executing the CreateFcn callback so these values are available to the callback. Within the function, use gcbo to get the handle of the uitable being created.

Setting this property on an existing uitable object has no effect.

You can define a default CreateFcn callback for all new uitables. This default applies unless you override it by specifying a different CreateFcn callback when you call uitable. For example, the code

set(0,'DefaultUitableCreateFcn','set(gcbo,...
    ''BackGroundColor'',''blue'')')

creates a default CreateFcn callback that runs whenever you create a new uitable. It sets the default background color of all new uitables.

To override this default and create a uitable whose BackgroundColor is set to a different value, call uitable with code similar to

hpt = uitable(...,'CreateFcn','set(gcbo,...
''BackgroundColor'',''white'')')

Note   To override a default CreateFcn callback you must provide a new callback and not just provide different values for the specified properties. This is because the CreateFcn callback runs after the property values are set, and can override property values you have set explicitly in the uitable call. In the example above, if instead of redefining the CreateFcn property for this uitable, you had explicitly set BackgroundColor to white, the default CreateFcn callback would have set BackgroundColor back to the default, i.e., blue.

See Function Handle Callbacks for information on how to use function handles to define a callback function.

Data

matrix or cell array of numeric, logical, or character data

Data content of uitable The matrix or cell array must be 2–dimensional. A cell array can mix data types.

Use get and set to modify Data. For example,

data = get(tablehandle,'Data')
data(event.indices[1],event.indices[2]) = pi(); 
set(tablehandle,'Data',data); 

See CellEditCallback for information about the event data structure. See ColumnFormat for information about specifying the data display format.

The number of rows in the table is the larger of RowName and the number of rows in Data. The number of columns in the table is the larger of ColumnName and the number of columns in Data.

DeleteFcn

string or function handle

Delete uitable callback routine. A callback routine that executes when you delete the uitable object (e.g., when you issue a delete command or clear the figure containing the uitable). MATLAB software executes the routine before destroying the object's properties so these values are available to the callback routine.

The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo.

See Function Handle Callbacks for information on how to use function handles to define a callback function.

Enable

{on} | inactive | off

Enable or disable the uitable. This property determines how uitables respond to mouse button clicks, including which callback routines execute.

• on – The uitable is operational (the default).

• inactive – The uitable is not operational, but looks the same as when Enable is on.

• off – The uitable is not operational and its image is grayed out.

When you left-click on a uitable whose Enable property is on, MATLAB software performs these actions in this order:

1. Sets the figure's SelectionType property.

2. Executes the uitable's ClickedCallback routine.

3. Does not set the figure's CurrentPoint property and does not execute either the table's ButtonDownFcn or the figure's WindowButtonDownFcn callback.

When you left-click on a uitable whose Enable property is off, or when you right-click a uitable whose Enable property has any value, MATLAB software performs these actions in this order:

1. Sets the figure's SelectionType property.

2. Sets the figure's CurrentPoint property.

3. Executes the figure's WindowButtonDownFcn callback.

Extent

position rectangle (read only)

Size of uitable rectangle. A four-element vector of the form [0,0,width,height] that contains the calculated values of the largest extent of the table based on the current Data, RowNames and ColumnNames property values. Calculation depends on column and row widths, when they are available. The calculated extent can be larger than the figure.

The first two elements are always zero. width and height are the dimensions of the rectangle. All measurements are in units specified by the Units property.

You can use this property to determine proper sizing for the uitable with respect to its content. Do this by setting the width and height of the uitable Position property to the width and height of the Extent property.

FontAngle

{normal} | italic | oblique

Character slant of cell content. MATLAB software uses this property to select a font from those available on your particular system. Setting this property to italic or oblique selects a slanted version of the font, when it is available on your system.

FontName

string

Font family for cell content. The name of the font in which to display cell content. To display and print properly, this must be a font that your system supports. The default font is system dependent.

To use a fixed-width font that looks good in any locale (and displays properly in Japan, where multibyte character sets are used), set FontName to the string FixedWidth (this string value is case sensitive):

set(uitable_handle,'FontName','FixedWidth')

This parameter value eliminates the need to hard code the name of a fixed-width font, which may not display text properly on systems that do not use ASCII character encoding (such as in Japan). A properly written MATLAB application that needs to use a fixed-width font should set FontName to FixedWidth and rely on the root FixedWidthFontName property to be set correctly in the end user's environment.

End users can adapt a MATLAB application to different locales or personal environments by setting the root FixedWidthFontName property to the appropriate value for that locale from startup.m. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

FontSize

size in FontUnits

Font size for cell contents. A number specifying the size of the font in which to display cell contents, in units determined by the FontUnits property. The default point size is system dependent. If FontUnits is set to normalized, FontSize is a number between 0 and 1.

FontUnits

{points} | normalized | inches |
centimeters | pixels

Font size units for cell contents. This property determines the units used by the FontSize property. Normalized units interpret FontSize as a fraction of the height of the uitable. When you resize the uitable, MATLAB software modifies the screen FontSize accordingly. pixels, inches, centimeters, and points are absolute units (1 point = ¹/₇₂ inch).

FontWeight

light | {normal} | demi | bold

Weight of cell text characters. MATLAB software uses this property to select a font from those available on your particular system. Setting this property to bold causes MATLAB software to use a bold version of the font, when it is available on your system.

ForegroundColor

1-by-3 matrix of RGB triples

Color of text in cells. Determines the color of the text defined for cell contents. Specify as an n-by-3 matrix of RGB triples, such as [0 0 .8; .8 0 0]. Each row is an RGB triplet of real numbers between 0.0 and 1.0 that defines one color. The default is a 1–by-3 matrix of platform-dependent colors. See ColorSpec for information about RGB colors.

Row 2 and subsequent rows of the matrix are used only if the RowStriping property is on.

HandleVisibility

{on} | callback | off

Control access to object's handle. This property determines when an object's handle is visible 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. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close. Neither is the handle visible in the parent figure's CurrentObject property. Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

• Handles are always visible when HandleVisibility is on.

• Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles.

• Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function.

You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings. This does not affect the values of the HandleVisibility properties.

HitTest

{on} | off

Selectable by mouse click. When HitTest is off, the ButtonDownFcn callback does not execute.

Interruptible

{on} | off

Callback routine interruption mode. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, that callback attempts to interrupt the first callback. The MATLAB software processes the callbacks according to these factors:

• The Interruptible property of the object whose callback is executing

• Whether the executing callback contains drawnow, figure, getframe, pause, or waitfor statements

• The BusyAction property of the object whose callback is waiting to execute

If the Interruptible property of the object whose callback is executing is on (the default), the callback can be interrupted. Whenever the callback calls one of the drawnow, figure, getframe, pause, or waitfor functions, the function processes any events in the event queue, including the waiting callback, before performing its defined task.

If the Interruptible property of the object whose callback is executing is off, the callback cannot be interrupted (except by certain callbacks; see the note below). The BusyAction property of the object whose callback is waiting to execute determines what happens to the callback.

Note   If the interrupting callback is a DeleteFcn or CreateFcn callback or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of that object's Interruptible property. The interrupting callback starts execution at the next drawnow, figure, getframe, pause, or waitfor statement. A figure's WindowButtonDownFcn callback routine, or an object's ButtonDownFcn or Callback routine are processed according to the rules described above.

KeyPressFcn

string or function handle

Key press callback function. A callback routine invoked by a key press when the callback's uitable object has focus. Focus is denoted by a border or a dotted border, respectively, in UNIX and Microsoft Windows. If no uitable has focus, the figure's key press callback function, if any, is invoked. KeyPressFcn can be a function handle, the name of an M-file, or any legal MATLAB expression.

If the specified value is the name of an M-file, the callback routine can query the figure's CurrentCharacter property to determine what particular key was pressed and thereby limit the callback execution to specific keys.

If the specified value is a function handle, the callback routine can retrieve information about the key that was pressed from its event data structure argument.

Event Data Structure Field	Description	Examples:
		a	=	Shift	Shift/a
Character	Character interpretation of the key that was pressed.	'a'	'='	''	'A'
Modifier	Current modifier, such as 'control', or an empty cell array if there is no modifier	{1x0 cell}	{1x0 cell}	{'shift'}	{'shift'}
Key	Name of the key that was pressed.	'a'	'equal'	'shift'	'a'

The uitable KeyPressFcn callback executes for all keystrokes, including arrow keys or when a user edits cell content.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

Parent

handle

Uitable parent. The handle of the uitable's parent object. You can move a uitable object to another figure, uipanel, or uibuttongroup by setting this property to the handle of the new parent.

Position

position rectangle

Size and location of uitable. The rectangle defined by this property specifies the size and location of the table within the parent figure window, ui, or uibuttongroup. Specify Position as a 4–element vector:

[left bottom width height]

left and bottom are the distance from the lower-left corner of the parent object to the lower-left corner of the uitable object. width and height are the dimensions of the uitable rectangle. All measurements are in units specified by the Units property.

Note   If you are specifying both Units and Position in the same call to uitable, specify Units first if you want Position to be interpreted using those units.

RearrangeableColumn

on | {off} (read-only)

This object can be rearranged. The RearrangeableColumn property provides a mechanism that you can use to rearrange the columns in the table. MATLAB software sets the RearrangeableColumn property to off by default. Rearranging the columns will not change the value of your data.

RowName

1–by-n cell array of strings| {'numbered'} | empty matrix ([])

Row heading names. Each element of the cell array is the name of a row. Multiline row names can be expressed as a string vector separated by vertical slash (|) characters, e.g.,'Standard|Deviation'

For sequentially numbered row headings starting with 1, specify RowName as 'numbered'. This is the default.

To remove the row headings, specify RowName as the empty matrix ([]).

The number of rows in the table is the larger of RowName and the number of rows in the Data property matrix or cell array.

RowStriping

{on} | off

Color striping of table rows. When RowStriping is on, consecutive rows of the table display in the colors you specify for the BackgroundColor and ForegroundColor properties. For both BackgroundColor and ForegroundColor, the first color applies to the first row, the second color to the second row, etc.

When RowStriping is off, the first color specified for both BackgroundColor and ForegroundColor is used for all rows.

Selected

on | {off}

Is object selected. When this property is on, MATLAB software displays selection handles if the SelectionHighlight property is also on. You can, for example, define the ButtonDownFcn to set this property, allowing users to select the object with the mouse.

SelectionHighlight

{on} | off

Object highlight when selected. When the Selected property is on, MATLAB software indicates the selected state by drawing four edge handles and four corner handles. When SelectionHighlight is off, MATLAB software does not draw the handles.

Tag

string (GUIDE sets this property)

User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. You can define Tag as any string.

TooltipString

string

Content of tooltip for object. The TooltipString property specifies the text of the tooltip associated with the uitable. When the user moves the mouse pointer over the table and leaves it there, the tooltip is displayed.

Type

string (read only)

Class of graphics object. For uitable objects, Type is always the string 'uitable'.

UIContextMenu

handle

Associate a context menu with uitable. Assign this property the handle of a uicontextmenu object. MATLAB software displays the context menu whenever you right-click over the uitable. Use the uicontextmenu function to create the context menu.

Units

{pixels} | normalized | inches | centimeters | points | characters (GUIDE default: normalized)

Units of measurement. MATLAB uses these units to interpret the Extent and Position properties. All units are measured from the lower-left corner of the parent object.

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

• pixels, inches, centimeters, and points are absolute units (1 point = 1/72 inch).

• Character units are characters using the default system font; the width of one character is the width of the letter x, the height of one character is the distance between the baselines of two lines of text.

If you change the value of Units, it is good practice to return it to its default value after completing your computation so as not to affect other functions that assume Units is set to the default value.

UserData

matrix

User-specified data. Any data you want to associate with the uitable object. MATLAB software does not use this data, but you can access it using set and get.

Visible

{on} | off

Uitable visibility. By default, all uitables are visible. When set to off, the uitable is not visible, but still exists and you can query and set its properties.

Note   Setting Visible to off for uitables that are not displayed initially in the GUI, can result in faster startup time for the GUI.

uitable

uitoggletool