uitable

Creates a table in a container object.

Syntax

h = uitable()

h = uitable(property, value, ...)

h = uitable(parent, property, value, ...)

Inputs

parent
Handle of a container object, which could be a figure, frame, uipanel, uitab or uibuttongroup.
Type: double | integer
property, value
backgroundcolor
Specifies the background color. Valid values are transparent or a real vector specifying RGB values in the range 0-255 or 0-1.
Type: string | vector
celleditcallback
Callback function that is triggered when a value is changed in a cell in h. If value is a function handle, it must be a function that takes at least two arguments: the first is the handle of the uitable, and the second is the event data to the uicontrol. Compose passes empty data to the second argument if there is no data to the uitable. If value is a string, it must represent a function handle or a function name. If value is a cell, it must contain the function name/function handle in the first cell element and parameters to pass to the callback function in the additional elements.
Type: cell | functionhandle | string
cellselectioncallback
Callback function that is triggered when cell selection changes.
If value is a function handle, it must be a function that takes at least two arguments: the first is the handle of the uitable, and the second is the event data to the uicontrol. Compose passes empty data to the second argument if there is no data to the uitable. If value is a string, it must represent a function handle or a function name. If value is a cell, it must contain the function name/function handle in the first cell element and parameters to pass to the callback function in the additional elements.
Type: cell | functionhandle | string
columneditable
Specifies the column(s) which are editable. Valid values are true(default), false, or matrix of size (1, n) where m is the number of column(s) with Boolean value(s) indicating which column(s) are editable.
Type: Boolean | matrix
columnformat
Specifies the column formats. The value must be a cell, specifying values of:
  • char(left justified data, default)
  • logical(center justified checkboxes)
  • numeric(right justified data)
  • cell(popupmenus with items specified by the cell)
  • [](default)
For data, of type mtx, this property is ignored and values are always right justified.
For data, of type checkboxes, icons, popupmenus, radio buttons or uicontrol, this property is ignored and gui elements are center justified.
Type: cell
columnname
Specifies the column labels of h. Valid values are numbered(default) or cell with label names.
Type: string | cell
columnwidth
Specifies the width of the columns. By default, the value is auto, where column widths are automatically adjusted. Individual column widths can be defined in a cell array of size (1, n), where n is the number of columns in data. The values in each of the cells specify the width of the individual column(s).
Type: cell | string
createfcn
Function that is triggered when h is created. If value is a function handle, it must be a function that takes at least two arguments. The first argument is the handle of the uicontrol. The second argument is the event data to the uicontrol, which is ignored for createfcn. If value is a string, it must represent a function handle or a function name. If value is a cell, it must contain the function name/function handle in the first cell element and parameters to pass to callback function in the additional elements. After it is being executed, createfcn cannot be interrupted.
Type: cell | functionhandle | string
data
Table data. If the data type is cell, the cell elements can only be one of the following types scalar | integer | Boolean | complex | string. Scalar values in for a cell data type can also be handles to a uicontrol widgets of style checkbox, radiobutton, listbox and popupmenu.
Icons can be specified in cell widgets of uitable using a string of the format '<iconlabel <IMG SRC="iconfile">'. All icons are center aligned.
Maximum dimensions of data in a uitable are [1000000 x 16000].
Type: cell | mat
deletefcn
Function triggered when h is deleted. If value is a function handle, it must be a function that takes at least two arguments. The first argument is the handle of the uicontrol. The second argument is the event data to the uicontrol, which is ignored for deletefcn. If value is a string, it must represent a function handle or a function name. If value is a cell, it must contain the function name/function handle in the first cell element and parameters to pass to callback function in the additional elements. After it is being executed, deletefcn cannot be interrupted.
Type: cell | functionhandle | string
enable
Specifies if h is enabled. Valid values are on(default) and off.
Type: string
fontangle
Specifies angle of the displayed font. Valid values are regular(default) and italic.
Type: string
fontname
Specifies name of the displayed font.
Type: string
fontsize
Specifies size of the displayed font.
Type: scalar
fontunits
Determines if fontsize property is absolute or relative based on fontsize of the parent of handle. Valid values are pixels (default) or normalized.
Type: string
fontweight
Specifies weight of the displayed font. Valid values are normal (default) and bold.
Type: string
headerformat
Specifies the format for header labels formats. The value must be a cell, specifying values of:
  • char(left justified)
  • logical(center justified checkbox)
  • numeric(right justified)
  • [](center justified default)
Type: cell
interruptible
Specifies if celleditcallback and cellselectioncallback functions can be interrupted by clicking on the Stop button in the user interface. Valid values are off (default) and on.
Type: string
keypressfcn
Function that is triggered when there is a key is pressed on h. If value is a function handle, it must be a function that takes two arguments. The first argument is the handle of the uicontrol. The second argument is the event data to the uicontrol, which has details on the key pressed. If value is a string, it must represent a function handle or a function name. If value is a cell, it must contain the function name/function handle in the first cell element and parameters to pass to the function in the additional elements.
Type: cell | functionhandle | string
parent
Specifies the parent.
Type: scalar
position
Position and size of h. Value is specified as a vector of form: [left top width height]. If units has a value of normalized, values must be between 0 to 1.
Type: vector
rowheight
Specifies the height of the row(s). By default, the value is auto, where row height(s) are automatically adjusted. Individual row height(s) can be defined in a cell of size (1, n), where n is the number of row(s). The values in cell will specify the height for the individual row(s).
Type: cell | string
rowname
Specifies the row labels of h. Valid values are numbered(default) or cell with label names.
Type: string | cell
rowstriping
If on, alternate rows of h will have a different background color. Valid values are off(default) and on. This property is available only on Windows.
Type: string
showgrid
Specified if grid is shown for the h. Valid values are on(default) and off.
Type: string
tag
User-defined string to tag h.
Type: string
tooltipstring
Tooltip.
Type: string
units
Specifies units of measurement. Valid values are pixels(default) and normalized. Value pixels indicates that h has a fixed size and position specified by position. Value normalized indicates that h will be resized if parent is resized.
Type: string
userdata
User-defined numerical data.
Type: complex | mtx | scalar
value
User-defined scalar data.
Type: scalar
visible
Specifies if h is visible. Valid values are on(default) and off.
Type: string

Outputs

h
Handle of the uitable.
Type: scalar

Examples

Display matrix data in a table:
uitable('data', rand(3, 3));
Display cell array data in a table:
uitable('data', {'Apple',2,true;'Banana',3,true;'Coco',5,false});
Display matrix data with specific column widths and names:
h = uitable('data', rand(2, 3), 'columnwidth', {50, 100, 150}, 'columnname', {'col1', 'col2', 'sum'});
Display matrix data along with a callback function with input arguments when the cell values are edited:
function out = callbackfunc(h,callstate,argument1,argument2)
    printf('In celledit callback, arg1 [%s], arg2 [%d]\n', argument1, argument2)
end
h = uitable('data', rand(2, 3), 'celleditcallback',  {@callbackfunc, 'foo', 1});
Display a table with uicontrol
function foo(handle, callstate)
  disp('in celleditcallback: foo')
end

function out = checkboxcb(h,callstate,argument1,argument2)
  disp('in checkboxcb callback')
end

function out = radiocb(h,callstate,argument1,argument2)
  disp('in radiocb callback')
end

cb = uicontrol('style', 'checkbox', 'callback', {@checkboxcb,1,2});
rb = uicontrol('style', 'radio', 'callback', {@radiocb,1,2}, 'value', 1, 'string', 'radio1');

data  = {cb 'a' 'b'; rb 'txt' 6};

t = uitable('data', data, 'rowname', {'one', 'two'}, 'celleditcallback',  @foo);
Display a uitable with column formats and logical header:
Dialog = figure;

uiTable = uitable('parent', Dialog, 'units','normalized', 'position',[0.12 0.26 0.43 0.2] ...
    , 'data',{1,2,45;'foo',true, 0; 3, 4, 1} ...
    , 'columnformat',{'char', 'numeric', 'logical'}, 'headerformat', {[], [], 'logical'}...
    , 'rowstriping','on', 'columnname', {'Col 1','Col 2','Col 3'});
Figure 1. Table with column formats and logical header


Display a uitable with a column autopopulated with popmenus:

function uiTable_celleditcallback(handle, data, varargin)
    data
end

Dialog = figure;

uiTable = uitable('parent', Dialog, 'celleditcallback','uiTable_celleditcallback', 'units','normalized', 'position',[0.12 0.26 0.5 0.2] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'data',{1,2,45;'foo',true, 0; 3, 4, 1} ...
    , 'backgroundcolor',[255,255,255], 'columneditable',[], 'columnformat',{'char', 'numeric', {'Fixed','Adjustable'}} ...
    , 'columnwidth','auto', 'foregroundcolor',[20,20,20], 'interruptible','off' ...
    , 'rowheight','auto', 'rowstriping','off', 'tag','uiTable' ...
    , 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');
Figure 2. Table with a popupmenu format column


Display a uitable with icons only in a column:
function uiTable_celleditcallback(handle, data, varargin)
  data
end

Dialog = figure;

uiTable = uitable('parent', Dialog, 'celleditcallback','uiTable_celleditcallback', 'units','normalized', 'position',[0.12 0.26 0.43 0.2] ...
  , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
  , 'data',{'<IMG SRC="check_48.png">',2,45;'<IMG SRC="error_48.png">',true, 0; '<IMG SRC="warning_48.png">', 4, 1} ...
  , 'backgroundcolor',[255,255,255], 'columneditable',[], 'columnformat',{'char', 'numeric', 'logical'} ...
  , 'columnwidth','auto', 'foregroundcolor',[20,20,20], 'interruptible','off' ...
  , 'rowheight','auto', 'rowstriping','on', 'tag','uiTable' ...
  , 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on', 'rowname', {'','',''});
Figure 3. Table with icons in a column


Display a uitable with an icon-label in a cell:
function uiTable_celleditcallback(handle, data, varargin)
  data
end

Dialog = figure;

uiTable = uitable('parent', Dialog, 'celleditcallback','uiTable_celleditcallback', 'units','normalized', 'position',[0.12 0.26 0.43 0.2] ...
  , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
  , 'data',{1,2,45;'foo <IMG SRC="tri.png">',true, 0; 3, 4, 1} ...
  , 'backgroundcolor',[255,255,255], 'columneditable',[], 'columnformat',{'char', 'numeric', 'logical'} ...
  , 'columnwidth','auto', 'foregroundcolor',[20,20,20], 'interruptible','off' ...
  , 'rowheight','auto', 'rowstriping','on', 'tag','uiTable' ...
  , 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on', 'rowname', {'','',''});
Figure 4. Table with an icon-label in a cell