Uipanel visibility, specified as 'on' or 'off'. The Visible property determines whether the uipanel displays on the screen. If the Visible property of a uipanel is set to 'off', the entire uipanel is invisible, but you can still specify and access its properties.

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

Note   Changing the Visible property of a uipanel does not change the Visible property of its child components even though hiding the uipanel prevents its children from displaying.

Uipanel background color, specified as an RGB triplet, short name, or long name. The color you specify fills the area bounded by the uipanel.

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.

Data Types: double | char

Uipanel title color, specified as an RGB triplet, short name, or long name.

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.

Example: [0 0 1]

Example: 'b'

Example: 'blue'

Border of the uipanel area, specified as 'etchedin', 'none', 'etchedout', 'beveledin', 'beveledout', or 'line'.

• For a 3-D look, use etched or beveled borders.

  Use the HighlightColor and ShadowColor properties to specify the color of 3-D borders.

• For a 2-D look, use a line border.

  Use the HighlightColor property to specify the line border color.

Width of the uipanel border, specified as a positive integer value. The unit of measurement is pixels. Etched and beveled borders wider than three pixels might not appear correctly at the corners.

Uipanel border highlight color, specified as an RGB triplet, short name, or long name.

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.

Uipanel border shadow color, specified as an RGB triplet, short name, or long name.

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.

Note:   The behavior of the Clipping property has changed. It no longer has any effect on uipanels. Child objects are now clipped to the uipanel boundary regardless of the value of this property. This property might be removed in a future release.

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

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 changes the width of the uipanel to 0.5:

p = uipanel;
p.Position(3) = 0.5;
p.Position

ans =

      0   0   0.5000  1.0000

Location and size of the uipanel, including borders and title, 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 property value.

This property is read only.

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

All measurements are in units specified by the Units property.

Note:   These are some important points to consider when using the InnerPosition property: InnerPosition values are affected by the presence of a title, font characteristics, BorderType, and BorderWidth. InnerPosition values are relative to the parent container's drawable area. The drawable area is the area inside the borders of the container and exclude 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.

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

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.

Uipanel resize 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.

Define this callback function to control the UI layout when the size of the uipanel changes.

The SizeChangedFcn callback executes under these circumstances:

• The uipanel becomes visible for the first time.

• The uipanel is visible while its drawable area changes. The drawable area is the area inside the outer bounds of the uipanel.

• The uipanel becomes visible for the first time after its drawable area changes. This situation occurs when the drawable area changes while the uipanel is invisible, and then it becomes visible later.

These are some of the important characteristics of the SizeChangedFcn callback and some recommended best practices:

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

• Use the gcbo function in your SizeChangedFcn code to get the uipanel object that the user is resizing. See the description of the figure SizeChangedFcn for an example that uses gcbo.

• All visible Uipanels that are specified in normalized units resize before the parent figure does. All visible, nested uipanels resize from inside-out.

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

See Managing the Layout in Resizable UIs for more information on controlling the resize behavior of programmatic UIs.

See Resize Behavior for more information on the resize behavior of GUIDE UIs.

Data Types: function_handle | cell | char

Callback function that executes when the uipanel size changes, 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.

Note:   Use of the ResizeFcn property is not recommended. It might be removed in a future release. Use SizeChangedFcn instead.

Data Types: function_handle | cell | char

Font for displaying the uipanel title, specified as a system supported font name or 'FixedWidth'. The default font depends on the specific operating system and locale.

To use a fixed-width font that looks good in any locale, specify 'FixedWidth'. The actual fixed-width font used depends on the FixedWidthFontName property of the root object. Changing the FixedWidthFontName property causes an immediate update of the display to use the new font.

Example: 'Arial'

Font size for the uipanel title, specified as a positive number. The FontUnits property specifies the units. The default size is system-dependent.

Example: 12

Example: 12.5

Data Types: double

Units of font size for the uipanel title, specified as one of the values from this table.

Font weight of uipanel title, specified as a value from the following table.

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

Note:   The 'light' and 'demi' font weight values have been removed in R2014b. If you specify either of these values, the result is a normal font weight.

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

Note:   The 'oblique' value has been removed. Use 'italic' instead.

Uipanel title, specified as a character vector.

MATLAB does not interpret a vertical slash ('|') character as a line break, it displays as a vertical slash in the uipanel title.

If you want to specify a Unicode^® character, pass the Unicode decimal code to the char function. For example, ['Multiples of ' char(960)] displays as Multiples of π.

Example: 'Options'

Example: ['Multiples of ' char(960)]

Location of the uipanel title, specified as 'lefttop', 'centertop', 'righttop', 'leftbottom', 'centerbottom', or 'righttbottom'.

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. For example, 'disp(''hello world'')' calls the disp function. 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 on the uipanel.

Uipanel context menu, specified as a uicontextmenu object. Use this property to display a context menu when the user right-clicks on the uipanel. Create the context menu using the uicontextmenu function.

Note:   The behavior of the Selected property changed in R2014b, and it is not recommended. It no longer has any effect on uipanels. This property might be removed in a future release.

Note:   The behavior of the SelectionHighlight property changed in R2014b, and it is not recommended. It no longer has any effect on uipanels. This property might be removed in a future release.

Callback interruption, 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 uipanel 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:

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

• 'off' — A callback cannot interrupt the running callback. MATLAB finishes executing the running callback without any interruptions. This is the default behavior.

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

Ability to become current object, specified as 'on' or 'off':

• Setting the value to 'on' allows the uipanel to become the current object when the user clicks on it. A value of 'on' also allows the figure CurrentObject property and the gco function to report the uipanel as the current object.

• Setting the value to 'off' sets the figure CurrentObject property to an empty GraphicsPlaceholder array when the user clicks on the uipanel.

This property is read only.

Deletion status of uipanel, returned as 'off' or 'on'. MATLAB sets the BeingDeleted property to 'on' when the delete function of the uipanel begins execution (see the DeleteFcn property). The BeingDeleted property remains set to 'on' until the uipanel no longer exists.

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

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

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 uipanel. MATLAB initializes all uipanel 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 handle to the uipanel that is being created.

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

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

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

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 uipanel (for example, when the end user deletes the figure). MATLAB executes the DeleteFcn callback before destroying the properties of the uipanel. 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 handle to the uipanel that is being deleted.

This property is read only.

Type of graphics object, returned as 'uipanel'.

Uipanel identifier, specified as a character vector. This value to serves as an identifier for the uipanel. When you need access to the uipanel elsewhere in your code, you can use the findobj function to search for the uipanel based on the Tag value.

Example: 'panel1'

Data Types: char

Data to associate with the uipanel object, specified as any array. Specifying UserData can be useful for sharing data values within and across UIs. See Share Data Among Callbacks for more information.

Example: [1 2 3]

Example: 'April 21'

Example: struct('value1',[1 2 3],'value2','April 21')

Example: {[1 2 3],'April 21'}

Uipanel parent, specified as a figure, uipanel, uibuttongroup, or uitab. You can move a uipanel to a different figure, uipanel, uibuttongroup, or uitab by setting this property to the handle of the target figure, uipanel, uibuttongroup, or uitab.

Children of uipanel, returned as an empty GraphicsPlaceholder or a 1-D array of component objects. The children of uipanel can be axes, uipanels, uibuttongroups, and uicontrols.

You cannot add or remove children using the Children property of the uipanel. Use this property to view the list of children or to reorder the children. The order of the children in this array reflects the front-to-back order (stacking order) of the components on the screen.

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

Objects with the HandleVisibility property set to 'off' do not list in the Children property. For more information, see the HandleVisibility property description.

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

This property controls the visibility of the uipanel 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 know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

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.