Documentation Center

  • Trial Software
  • Product Updates

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 the GUIDE Layout Editor View menu, 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.

Property Name

Description

BackgroundColorBackground color of cells.
BeingDeletedThis object is being deleted.
BusyActionCallback routine interruption
ButtonDownFcnButton-press callback routine
CellEditCallbackCallback when data in a cell is changed.
CellSelectionCallbackCallback when cell is selected
Childrenuitable objects have no children
ClippingDoes not apply to uitable objects
ColumnEditableDetermines data in a column as editable
ColumnFormatDetermines display and editability of columns
ColumnNameColumn header label
ColumnWidthWidth of each column in pixels
CreateFcnCallback routine during object creation
DataTable data
DeleteFcnCallback routine during object deletion
EnableEnable or disable the uitable
ExtentSize of uitable rectangle
FontAngleCharacter slant of cell content
FontNameFont family for cell content
FontSizeFont size of cell content
FontUnitsFont size units for cell content
FontWeightWeight of cell text characters
ForegroundColorColor of text in cells
HandleVisibilityControl access to object's handle
InterruptibleCallback routine interruption mode
KeyPressFcnKey press callback function
Parentuitable parent
PositionSize and location of uitable
RearrangeableColumnsLocation of the column
RowNameRow header label names
RowStripingColor striping of label rows
TagUse-specified object label
TooltipStringContent of tooltip for object
TypeClass of graphics object
UIContextMenuAssociate context menu with uitable
UnitsUnits of measurement
UserDataUser-specified data
Visibleuitable visibility

BackgroundColor

1-by-3 or 2-by-3 matrix of RGB triples

Cell background color. Color used to fill the uitable cells. Specify as an 1-by-3 or 2-by-3 matrix of RGB triples, such as [.8 .9. .8] or [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. (Color names are not allowed.) The default is a 1-by-3 matrix of platform-dependent colors. See ColorSpec for information about RGB colors.

Row 2 of the matrix is used only if the RowStriping property is on. The table background is not striped unless both RowStriping is on and the BackgroundColor color matrix has two rows.

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 queuing

Determines how MATLAB handles the execution of interrupting callbacks.

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. The BusyAction property of the interrupting callback determines how MATLAB handles its execution. When the BusyAction property is set to:

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

  • 'cancel' — Discards the interrupting callback as MATLAB finishes execution.

For information about how the Interruptible property of the callback controls whether other callbacks can interrupt the running callback, see the Interruptible property description.

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.

Define this routine as a string that is a valid MATLAB expression or the name of a MATLAB function 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 program 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 program 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

Indices1-by-2 matrix

Row index and column index of the cell the user edited.

PreviousData1-by-1 matrix or cell array

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

EditDataString

User-entered string.

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

ErrorString

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. The CellEditCallback is issued when the user has modified a table cell and presses Enter or clicks anywhere outside the cell.

CellSelectionCallback

function 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. The callback includes event data, a structure with one member

Event Data Structure Field

Type

Description

Indicesn-by-2 matrix

Row index and column index of the cells the user currently has selected

Once a cell selection has been made, cells within it can be removed one at a time by Ctrl-clicking them.

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 have control over changes users potentially might make to data.

Specify elements of a logical matrix as true 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. If a column that contains pop-up menus is not editable, the currently selected choice appears without displaying the pop-up control. The 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.,'short' or 'bank'

Displays the Data value using the specified format. For example, for a two-column table, set(htable,'ColumnFormat',{'short','bank'}).

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
numericcharlogical
Data Type numericValues 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.
charMATLAB converts the entered number to a text string.Values match. MATLAB displays the string as is.Does not work: warning is thrown.
logicalDoes not work: warning is 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.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

n-by-1 cell array of strings | 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.

If you specify the ColumnName value as a 1–by-n cell array of strings, MATLAB stores and returns the value as a n-by-1 cell array of strings.

ColumnWidth

1–by-n cell array | 'auto'

Column widths. The width of each column in units of pixels. Column widths are always specified in pixels; they do not obey the Units property. Each column in the cell array corresponds to a column in the uitable. By default, the width of the column name, as specified in ColumnName, along with some other factors, is used to determine the width of a column. If ColumnWidth is a cell array and the width of a column is set to 'auto'or if auto is selected for that column in the Property Inspector GUI for columns, the column width defaults to a size determined by the table. The table decides the default size using a number of factors, including the ColumnName and the minimum column size.

To default all column widths in an existing table, use

set(uitable_handle,'ColumnWidth','auto')

To default some column widths but not others, use a cell array containing a mixture of pixel values and 'auto'. For example,

set(uitable_handle,'ColumnWidth',{64 'auto' 40 40 'auto' 72})
CreateFcn

string or function handle

Callback routine executed during object creation. The specified function executes when MATLAB creates a uitable object. MATLAB 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.

Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. The act of copying the uicontrol object fires the CreateFcn repeatedly, which raises a series of error messages after exceeding the root object's RecursionLimit property.

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 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 performs these actions in this order:

  1. Sets the figure's SelectionType property.

  2. Executes the uitable's CellSelectionCallback routine (but only for table cells, not header cells). Row and column indices of the cells the user selects continuously update the Indices field in the eventdata passed to the callback.

  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 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, RowName and ColumnName 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.

When the uitable's Units property is set to 'Normalized', its Extent is measured relative to the figure, regardless of whether the table is contained in (parented to) a uipanel or not.

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. However, doing this can cause the table to extend beyond the right or top edge of the figure and/or its uipanel parent, if any, for tables with large extents.

FontAngle

{normal} | italic | oblique

Character slant of cell content. MATLAB 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 modifies the screen FontSize accordingly. pixels, inches, centimeters, and points are absolute units (1 point = 1/72 inch).

FontWeight

light | {normal} | demi | bold

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

ForegroundColor

1-by-3 matrix of RGB triples or a color name

Color of text in cells. Determines the color of the text defined for cell contents. Text in all cells share the current color. Specify as a 1-by-3 matrix of RGB triples, such as [0 0 .8] or as a color name. The default is a 1-by-3 matrix of platform-dependent colors. See ColorSpec for information about specifying RGB colors.

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.

    Note:   Use of the Uitable Properties Hittest property is not recommended. This property may be removed in a future release.

Interruptible

off | {on}

Callback routine interruption

Controls whether MATLAB can interrupt an object's callback function when subsequent callbacks attempt to interrupt it.

For user interface objects, the Interruptible property affects the callbacks for these properties only:

  • ButtonDownFcn

  • KeyPressFcn

  • KeyReleaseFcn

  • WindowButtonDownFcn

  • WindowButtonMotionFcn

  • WindowButtonUpFcn

  • WindowKeyPressFcn

  • WindowKeyReleaseFcn

  • WindowScrollWheelFcn

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. MATLAB handles both callbacks based on the Interruptible property of the object of the running callback.

When the Interruptible property is set to:

  • 'off', MATLAB finishes execution of the running callback without any interruptions

  • 'on', these conditions apply:

    • If there is a drawnow, figure, getframe, waitfor, or pause command in the running callback, then MATLAB executes the interrupting callbacks which are already in the queue and returns to finish execution of the current callback.

    • If one of the above functions is not in the running callback, then MATLAB finishes execution of the current callback without any interruption.

The BusyAction property of the object of interrupting callback determines whether the callback should be ignored or should be put in the queue.

Setting the Interruptible property to on (default), allows a callback from other user interface objects to interrupt callback functions originating from this object.

    Note:   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 may be changed as another callback is executed.

After the function that interrupts a callback completes, the callback resumes execution where it halted when interrupted. For more information, see Control Callback Execution and Interruption.

    Note:   If the interrupting callback is a DeleteFcnor 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. An object's ButtonDownFcn or Callback routine is processed according to the rules described previously in this section.

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 a MATLAB function file, or any legal MATLAB expression.

If the specified value is the name of a function code 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.

RearrangeableColumns

on | {off}

This object can be rearranged. The RearrangeableColumns property provides a mechanism that you can use to reorder the columns in the table. All columns are rearrangable when this property is turned on. MATLAB software sets the RearrangeableColumns property to off by default.

When this property is on, the user of a table can move any column of data (but not the row labels) at a time left or right to reorder it by clicking and dragging its header. Rearranging columns does not affect the ordering of columns in the table's Data, only the user's view of it.

RowName

n-by-1 cell array of strings | 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. Row names are restricted to one line of text.

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.

If you specify the RowName value as a 1–by-n cell array of strings, MATLAB stores and returns the value as a n-by-1 cell array of strings.

RowStriping

{on} | off

Color striping of table rows. When RowStriping is on, the background of consecutive rows of the table display in the pair of colors that the BackgroundColor color matrix specifies. The first color matrix row applies to odd-numbered rows, and the second to even-numbered rows. If the BackgroundColor matrix has only one row, it is applied to all rows (that is, no striping occurs).

When RowStriping is off, the first color specified for BackgroundColor is applied to all rows.

Selected

on | {off}

Is object selected. When this property is on, MATLAB 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.

    Note:   Use of the Uitable Properties Selected property is not recommended. This property may be removed in a future release.

SelectionHighlight

{on} | off

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

    Note:   Use of the Uitable Properties SelectionHighlight property is not recommended. This property may be removed in a future release.

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.

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 value. For example:

h = uitable;
s = sprintf('UITable tooltip line 1\nUITable tooltip line 2');
set(h,'TooltipString',s)
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 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 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.

Was this topic helpful?