Main Content

uitabgroup

Create container for tabbed panels

collapse all in page

Syntax

tg = uitabgroup
tg = uitabgroup(Name,Value)
tg = uitabgroup(parent)
tg = uitabgroup(parent,Name,Value)

Description

tg = uitabgroup creates a tab group in the current figure and returns the TabGroup object. If there is no figure available, MATLAB® calls the figure function to create one. Tab groups are containers for tabs. They allow you to identify the selected tab and detect when the user selects a different tab.

tg = uitabgroup(Name,Value) specifies tab group property values using one or more name-value arguments. For example, you can specify the position of the tab group or the location of tab labels.

tg = uitabgroup(parent) creates the tab group in the specified parent container. The parent container can be a figure created with either the figure or uifigure function, or a child container such as a panel. Property values for uitabgroup vary slightly depending on whether the app is created with the figure or uifigure function. For more information, see Name-Value Arguments.

tg = uitabgroup(parent,Name,Value) specifies the parent container and one or more property values.

example

Examples

collapse all

Create a figure containing a tab group and two tabs.

f = figure;
tabgp = uitabgroup(f,"Position",[.05 .05 .3 .8]);
tab1 = uitab(tabgp,"Title","Settings");
tab2 = uitab(tabgp,"Title","Options");

Tab group with two tabs in a figure window. The tabs have titles "Settings" and "Options". The "Settings" tab is selected.

Get the currently selected tab.

currenttab = tabgp.SelectedTab
currenttab = 

  Tab (Settings) with properties:

              Title: 'Settings'
    BackgroundColor: [0.9400 0.9400 0.9400]
           Position: [0.0119 0.0089 0.9702 0.9107]
              Units: 'normalized'

The Scrollable property enables scrolling within a tab that has components outside its borders. To use scrolling, the figure must be created with the uifigure function. App Designer uses this type of figure for creating apps.

Create a tab group containing one tab. Add six UI components to the tab, where the first three lie outside the upper border of the tab.

fig = uifigure;
tg = uitabgroup(fig,"Position",[20 20 196 145]);
t = uitab(tg,"Title","Member Information");
ef1 = uieditfield(t,"Text","Position",[11 165 140 22],"Value","First Name");
ef2 = uieditfield(t,"Text","Position",[11 140 140 22],"Value","Last Name");
ef3 = uieditfield(t,"Text","Position",[11 115 140 22],"Value","Address");
dd = uidropdown(t,"Position",[11 90 140 22],"Items",{'Male','Female'});
cb = uicheckbox(t,"Position",[11 65 140 22],"Text","Member");
b = uibutton(t,"Position",[11 40 140 22],"Text","Send");

Tab group with one tab labeled "Member Information" in a UI figure window. Only the UI components at the bottom of the tab (the drop-down list, check box, and button) are visible.

Enable scrolling by setting the Scrollable property of the tab to "on". By default, the scroll bar displays at the top.

t.Scrollable = "on";

Tab group with one tab labeled "Member Information" in a UI figure window. Only the components at the top (the edit fields, drop-down list, and check box) are visible. The tab has a vertical scroll bar.

In a new script, create a tab group with two tabs in a UI figure. Specify the SelectionChangedFcn property as a handle to a function named displaySelection. This function executes when a user switches between tabs in the tab group.

At the bottom of the script, define the displaySelection function to accept the two input arguments that MATLAB passes to callback functions:

  • src — The component that executed the callback

  • event — Information about the user interaction that triggered the callback

In the callback function, write code to display the title of the visible tab in the Command Window.

fig = uifigure;
tg = uitabgroup(fig,"SelectionChangedFcn",@displaySelection);
t1 = uitab(tg,"Title","Data");
t2 = uitab(tg,"Title","Plots");

function displaySelection(src,event)
    t = event.NewValue;
    title = t.Title;
    disp("Viewing the " + title + " tab")
end

Run the script and toggle between tabs to display the tab titles.

For more information, see Create Callbacks for Apps Created Programmatically.

Input Arguments

collapse all

Parent container, specified as a figure created with either the figure or uifigure function, or a child container:

  • Panels, tabs, and button groups can be containers in either type of figure.

  • Grid layouts can be containers only in figures created with the uifigure function.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: uitabgroup(TabLocation='bottom') specifies that the tab labels are at the bottom of the tab group.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: uitabgroup("TabLocation","bottom") specifies that the tab labels are at the bottom of the tab group.

Note

The properties listed here are a subset of the available properties. For the full list, see TabGroup.

Currently selected tab, specified as a Tab object. Use this property to determine the currently selected tab within a tab group. You can also use this property to set the default tab selection. The default value of the SelectedTab property is the first Tab that you add to the TabGroup.

Selection changed callback, 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 (not recommended). MATLAB evaluates this expression in the base workspace.

This callback function executes when the user selects a different tab within the tab group.

This callback function can access specific information about the user’s interaction with the tabs. MATLAB passes this information in a SelectionChangedData 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.NewValue returns the currently selected tab. The SelectionChangedData object is not available to callback functions specified as character vectors.

The following table lists the properties of the SelectionChangedData object.

Property

Description

OldValue

Previously selected Tab, or [] if none was selected

NewValue

Currently selected Tab

Source

Component that executes the callback

EventName

'SelectionChanged'

For more information about writing callbacks, see Callbacks in App Designer.

Tab label location, specified as 'top', 'bottom', 'left', or 'right'. This property specifies the location of the tab labels with respect to the tab group.

Location and size of the tab group, specified as a four-element vector of the form [left bottom width height].

This table describes each element in the vector.

ElementDescription
leftDistance from the inner left edge of the parent container to the outer left edge of the tab group
bottomDistance from the inner bottom edge of the parent container to the outer bottom edge of the tab group
widthDistance between the right and left outer edges of the tab group
heightDistance between the top and bottom outer edges of the tab group

All measurements are in units specified by the Units property.

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 decorations such as a menu bar or title.

Units of measurement, specified as one of the values in this table.

Units ValueDescription
'pixels' (default in uifigure-based apps)

Distances in pixels are independent of your system resolution on Windows® and Macintosh systems:

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

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

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

'normalized' (default in figure-based apps)

These units are normalized with respect to the parent container. The lower-left corner of the container maps to (0,0) and the upper-right corner maps to (1,1).

'inches'Inches.
'centimeters'Centimeters.
'points'Points. One point equals 1/72nd of an inch.
'characters'

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

  • Character width = width of the letter x.

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

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

The recommended value is 'pixels', because most MATLAB app building functionality measures distances in pixels. You can create an object that rescales based on the size of the parent container by parenting the object to a grid layout manager created using the uigridlayout function. For more information, see Lay Out Apps Programmatically.

Version History

Introduced in R2014b

See Also

Functions

Properties