TabGroup Properties

Control tab group appearance and behavior in figure-based apps

expand all in page

The properties listed here are valid for tab groups in GUIDE or in apps created with the figure function. If you are using App Designer or the uifigure function, see TabGroup Properties instead. For more information, see GUIDE Migration Strategies.

Tab groups are containers for grouping and managing tabs. Properties control the appearance and behavior of a tab group. Use dot notation to refer to a particular object and property.

f = figure;
tg = uitabgroup(f);
tg.Position = [.1 .1 .8 .8];

Tabs

expand all

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.

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

The default value of the SelectedTab property is the first tab that you add to the tab group.

Interactivity

expand all

State of visibility, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

  • 'on' — Display the object.

  • 'off' — Hide the object without deleting it. You still can access the properties of an invisible UI component.

To make your app start faster, set the Visible property to 'off' for all components that do not need to appear at startup.

Changing the size of an invisible container triggers the SizeChangedFcn callback when it becomes visible.

Changing the Visible property of a container does not change the values of the Visible properties of child components. This is true even though hiding the container causes the child components to be hidden.

Context menu, specified as a ContextMenu object created using the uicontextmenu function. Use this property to display a context menu when you right-click on a component.

Position

expand all

Location and size, 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 tag 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.

Note

The Position values are relative to the parent container’s drawable area. The drawable area is the area inside the borders of the container and does not include the area occupied by the title. If the parent container is a figure, then the drawable area also excludes the menu bar and tool bar.

Example: Modify One Value in the Position Vector

You can combine dot notation and array indexing when you want to change one value in the Position vector. For example, this code sets the width of the tab group to .5 without changing any of the other Position values:

tg = uitabgroup;
tg.Position(3) = .5;

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

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

Units of measurement, specified one of the values from this table.

Units ValueDescription
'normalized'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).
'pixels'

Pixels.

Starting in R2015b, 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.

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

MATLAB® measures all units from the lower left corner of the parent object.

If you change the value of the Units property, it is good practice to return it to its default value after completing your computation to avoid affecting other functions that assume the Units property is set to the default value.

The order in which you specify the Units and Position properties has these effects:

  • If you specify the Units property before the Position property, then MATLAB sets Position using the units you specified.

  • If you specify the Units property after the Position property, MATLAB sets the position using the default Units. Then, MATLAB converts the Position values to the equivalent values in the units you specified.

Callbacks

expand all

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.

If you set the SelectionChangedFcn property to a function handle (or cell array containing a function handle), MATLAB passes a SelectionChangedData object containing event data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation. For example, if the second argument in your callback is called event, then event.NewValue returns the currently selected Tab.

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 specifying a callback property value as a function handle, cell array, or character vector, see How to Specify Callback Property Values.

Size change 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 (not recommended). MATLAB evaluates this expression in the base workspace.

Define this callback to customize the app layout when the size of this container changes (e.g., when the user resizes the window).

The SizeChangedFcn callback executes when:

  • This container becomes visible for the first time.

  • This container is visible while its size changes.

  • This container becomes visible for the first time after its size changes. This situation occurs when the size changes while the container is invisible, and then it becomes visible later.

Other important points to consider when defining a SizeChangedFcn callback:

  • Consider delaying the display of this container until after all the variables that the SizeChangedFcn uses are defined. This practice can prevent the SizeChangedFcn callback from returning an error. To delay the display of the container, set its Visible property to 'off'. Then, set the Visible property to 'on' after you define the variables that your SizeChangedFcn callback uses.

  • If your app contains nested containers, they resize from the inside out.

  • To access the container that is resizing from within the SizeChangedFcn, refer to the source object (the first input argument in the callback) or use the gcbo function.

Tip

As an easy alternative to specifying a SizeChangedFcn callback, you can set the Units property of all the objects you put inside a container to 'normalized'. Doing so makes those components scale proportionally with the container.

See Lay Out a UI Programmatically for more information about managing layouts with SizeChangedFcn callbacks.

Button-press 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 (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or character vector, see How to Specify Callback Property Values.

The ButtonDownFcn callback is a function that executes when the user clicks a mouse button within the container.

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

For more information about specifying a callback property value as a function handle, cell array, or character vector, see How to Specify Callback Property Values.

This property specifies a callback function to execute when MATLAB creates the component. MATLAB initializes all component 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 object that is being created.

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

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

For more information about specifying a callback property value as a function handle, cell array, or character vector, see How to Specify Callback Property Values.

The DeleteFcn property specifies a callback function to execute when MATLAB deletes the component (for example, when the user closes the window). MATLAB executes the DeleteFcn callback before destroying the properties of the component 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 get the component object that is being deleted.

Callback Execution Control

expand all

Callback interruption, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

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 (if one exists). The Interruptible property of the object owning the running callback determines if interruption is allowed:

  • A value of 'on' allows other callbacks to interrupt the object's callbacks. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, getframe, waitfor, or pause.

    • If the running callback contains one of these 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.

  • A value of 'off' blocks all interruption attempts. The BusyAction property of the object owning the interrupting callback determines if the interrupting callback is discarded or put into a queue.

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.

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

See Interrupt Callback Execution for an example that shows how the Interruptible and BusyAction properties affect the behavior of a program.

Callback queuing specified as 'queue' (default) 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 source of the interrupting callback determines how MATLAB handles its execution. The BusyAction property has these 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. The Interruptible property of the object whose callback is running determines if interruption is allowed. If Interruptible is set to:

  • on — Interruption occurs at the next point where MATLAB processes the queue. This is the default.

  • off — The BusyAction property (of the object owning the interrupting callback) determines if MATLAB enqueues or ignores the interrupting callback.

See Interrupt Callback Execution for an example that shows how the BusyAction and Interruptible properties affect the behavior of a program.

This property is read-only.

Deletion status, returned as an on/off logical value of type matlab.lang.OnOffSwitchState.

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.

Parent/Child

expand all

Parent object, specified as a Figure, Panel, or Tab object. Use this property to specify the parent container when creating a tab group or to move an existing tab group to a different parent container.

TabGroup children, returned as an empty GraphicsPlaceholder or a 1-D array of component objects. The children of TabGroup objects are Tab objects.

You cannot add or remove children using the Children property. Use this property to view the list of children or to reorder the children. The order of the children in this array reflects the order of the tabs displayed on the screen.

To add a child to this list, set the Parent property of the child component to the TabGroup object.

Objects with the HandleVisibility property set to 'off' are not listed in the Children property.

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

This property controls the visibility of the object handle 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. These functions include get, findobj, gca, gcf, gco, newplot, cla, clf, and close. The HandleVisibility property also controls the visibility of the object’s handle in the parent figure's CurrentObject property. Handles are still valid even if they are not visible. If you can access an object, you can set and get its properties, and pass it to any function that operates on objects.

HandleVisibility ValueDescription
'on'The object handle is always visible.
'callback'The object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command-line, but allows callback functions to access it.
'off'The object handle is invisible at all times. This option is useful for preventing unintended changes to the UI by another function. Set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

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

Identifiers

expand all

This property is read-only.

Type of graphics object, returned as 'uitabgroup'.

Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value to serve as an identifier for an object. 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.

User data, specified as any array. Specifying UserData can be useful for sharing data within apps. See Share Data Among Callbacks for more information.

Compatibility Considerations

expand all

Not recommended starting in R2020a

See Also

|

Topics

Introduced in R2014b

MATLAB Documentation

Support