matlab app designer call external function

Table (App Designer) Properties

Control appearance and behavior of table

Valid for tables used in App Designer or figures created with the uifigure function. For tables used in GUIDE or apps created with the figure function, see Uitable Properties.

Tables are components for presenting rows and columns of data in an app. The uitable function creates a table and sets any required properties before displaying it. By changing table property values, you can modify certain aspects of its appearance and behavior.

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

Appearance

expand all

`Visible` — Table visibility
`'on'` (default) | `'off'`

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

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

`BackgroundColor` — Table background color
`[1 1 1; 0.94 0.94 0.94]` (default) | RGB triplet | m-by-3 matrix of RGB triplets

Table 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(uifigure,'Data',rand(10,3),'BackgroundColor',[0.85 0.85 1])

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

The following table lists the RGB triplets for certain colors.

Color	RGB 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]`

`ForegroundColor` — Cell text color
`[0 0 0]` (default) | RGB triplet | short name | long name

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

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

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

Example: t = uitable(uifigure,'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 Name	Short Name	RGB 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

`Data` — Table data
numeric array | logical array | cell array

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.

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

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

Table Layout

expand all

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

Row heading names, specified as one of these values:

'numbered' — The row headings are sequential numbers that start at 1.
Cell array — Each element of the cell array becomes the name of a row. Row names are restricted to one line of text. If you specify a 1-by-n cell array, MATLAB stores and returns the value as an 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 reflects the number of rows in the Data property.

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

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

`ColumnName` — Column heading names
`'numbered'` (default) | n-by-1 cell array of character vectors | empty cell array (`{}`) | empty matrix (`[]`)

Column heading names, specified as one of these values:

'numbered' — The column headings are sequential numbers that start at 1.
Cell array — Each element of the cell array becomes the name of a column. Column names are restricted to one line of text. If you specify a 1-by-n cell array, MATLAB stores and returns the value as an n-by-1 cell array.
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(uifigure,'ColumnName',{'Name'; 'Number'},'Data',{'Bob' 5})

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

`ColumnWidth` — Width of table columns
`'auto'` (default) | 1-by-n cell array

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.

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

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

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

`ColumnFormat` — Cell display format
empty cell array (`{}`) (default) | 1-by-n cell array of character vectors

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 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 a check box. To edit a cell, the user selects or clears the check box. Then, MATLAB sets the corresponding `Data` value to `true` or `false`. The `ColumnEditable` property value must be `true` to allow users to select or clear 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 that 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 = uifigure; myData = {'Andrew' 31 'Male' 'Choose'; ...           'Bob' 41 'Male' 'Choose';  ...           'Anne' 20 'Female' 'Choose';}; t = uitable('Parent', f,...             'Position', [100 100 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 Value	Any numeric type	Table 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.
	`char`	Table 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.
	`logical`	Table 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.

`RowStriping` — Alternate row shading
`'on'` (default) | `'off'`

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

When the RowStriping value is set to 'on', the BackgroundColor matrix specifies the 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

`Position` — Location and size of table
`[left bottom width height]`

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

Element	Description
`left`	Distance from the inner left edge of the parent container to the outer left edge of the table
`bottom`	Distance from the inner bottom edge of the parent container to the outer bottom edge of the table
`width`	Distance between the right and left outer edges of the table
`height`	Distance between the top and bottom outer edges of the table

All measurements are in units specified by the Units property.

Note: The Position values are relative to the drawable area of the parent container. The drawable area is the area inside the borders of the container and does not include the area occupied by the title.

`OuterPosition` — Location and size of table
`[left bottom width height]`

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

`InnerPosition` — Location and size of table
`[left bottom width height]`

Location and size of the table, 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` — Units of measurement
`'pixels'` (default)

Units of measurement, specified as 'pixels'. MATLAB measures all units from the lower left corner of the parent object.

Font Style

expand all

`FontName` — Font for cell content
system supported font name

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

If the specified font is not available, then MATLAB uses the best match among the fonts available on the system where the app is running.

Example: 'Arial'

`FontSize` — Font size
positive number

Font size, specified as a positive number. MATLAB uses the units specified by FontUnits. The default size is system-dependent.

Example: 14

`FontUnits` — Font size units
`'pixels'`

Font size units, specified 'pixels'.

`FontWeight` — Font weight
`'normal'` (default) | `'bold'`

Font weight, specified as 'normal' or 'bold'.

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

`FontAngle` — Character slant
`'normal'` (default) | `'italic'`

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

Interactive Control

expand all

`CellEditCallback` — Cell edit callback function
function handle | cell array | character vector

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.

Use this callback function to perform calculations or validate input when the app user changes the contents of a table cell.

This callback function can access specific information about the user's interaction with the cell (such as the cell indices). MATLAB passes this information in a CellEditData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.Indices returns the indices of the selected cell. The CellEditData object is not available to callback functions specified as character vectors.

The following table describes properties of the CellEditData object.

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`	The table object that is executing the `CellEditCallback` function.
`EventName`	`'CellEdit'`

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

Tries to store the new value into the Data property of the table
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.

`CellSelectionCallback` — Cell selection callback function
function handle | cell array | character vector

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.

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

Highlights a data cell (not a row heading or column heading) 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

This callback function can access specific information about the user's interaction with the cell (such as the cell indices). MATLAB passes this information in a CellSelectionChangeData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.Indices returns the indices of the selected cell. The CellSelectionChangeData object is not available to callback functions specified as character vectors.

The following table describes properties of the CellSelectionChangeData object.

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

`ColumnEditable` — Ability to edit column cells
`[]` (default) | logical 1-by-n array | logical scalar

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(uifigure,'Data',rand(10,3),'ColumnEditable',[false true true])

Example: t = uitable(uifigure,'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.

`Enable` — Operational state of table
`'on'` (default) | `'off'`

Operational state of table, specified as 'on' or 'off'. The Enable property controls whether the table responds to user interaction. The are two possible values:

'on' – The table is operational.
'off' – The table appears grayed-out and does not respond to user interaction.

Callback Execution Control

expand all

`Interruptible` — Callback interruptibility status
`'on'` (default) | `'off'`

Callback interruptibility status, 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 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:

'off' — A callback cannot interrupt the running callback. MATLAB finishes executing the running callback without any interruptions. This is the default behavior.
'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, uifigure, getframe, waitfor, or pause command.
- If the running callback contains one of the 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.

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.

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

`BusyAction` — Callback queuing
`'queue'` (default) | `'cancel'`

Callback queuing, specified as 'queue' 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 object that owns the interrupting callback determines how MATLAB handles the execution of the interrupting callback. The BusyAction property has two possible 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 (if one exists). The Interruptible property of the object whose callback is executing determines if interruption is allowed. The Interruptible property has two possible values:

'on' — Interruption occurs at the next point where MATLAB processes the queue. This is the default.
'off' — BusyAction property (of the object owning the interrupting callback) determines if MATLAB enqueues or ignores the interrupting callback.

Creation and Deletion Control

expand all

`BeingDeleted` — Deletion status of this component
`'off'` (default) | `'on'`

This property is read only.

Deletion status of this component, returned as 'off' or 'on'. MATLAB sets the BeingDeleted property to 'on' when the DeleteFcn callback begins execution. The BeingDeleted property remains set to 'on' until the component object no longer exists.

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

`CreateFcn` — Component creation function
function handle | cell array | character vector

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

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

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

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

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

`DeleteFcn` — Component deletion function
function handle | cell array | character vector

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

The DeleteFcn property specifies a callback function to execute when MATLAB deletes a component in an app. MATLAB executes the DeleteFcn callback before destroying the properties of the object. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

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

Identifiers

expand all

`Type` — Type of graphics object
`'uitable'`

This property is read only.

Type of graphics object, returned as 'uitable'.

`Tag` — Object identifier
`''` (default) | character vector

Object identifier, specified as a character vector. You can specify a unique Tag value to serve as an identifier for any component object in your app. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.

Example: 'table1'

`UserData` — Data to associate with this component
empty array (default) | array

Data to associate with this component, specified as any array. Specifying UserData can be useful for sharing data values within and across apps you create programmatically.

Note: Do not use this property in apps you create with App Designer. For information on sharing data values within and across apps created with App Designer, see Share Data Across Callbacks in App Designer.

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

`Parent` — Table parent
figure object | panel object | buttongroup object | tab object

Table parent, specified as a Figure object, Panel object, ButtonGroup object, or Tab object. You can move a table to a different container by setting this property to the target Figure, Panel, ButtonGroup, or Tab.

`Children` — Children of table
empty array

Children of table, returned as an empty array. Table objects have no children, so setting this property has no effect.

`HandleVisibility` — Visibility of table handle
`'on'` (default) | `'callback'` | `'off'`

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

This property controls the visibility of the Table object in its parent's list of children. When an object 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, newplot, and close. Objects are still valid even if they are not visible. If you can access the Table object, you can set and get its properties, and pass it to any function that operates on Table objects.

HandleVisibility Value	Description
`'on'`	The `Table` object is always visible.
`'callback'`	The `Table` object is visible from within callbacks or functions invoked by callbacks, but not from within functions called at the command line.
`'off'`	The `Table` object is always invisible. This option is useful for preventing unintended changes to the UI by another function. Set the `HandleVisibility` to `'off'` to temporarily hide the object during the execution of that function.

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

Introduced in R2016b

Was this topic helpful?