Main Content

Update UIControl Objects and Callbacks

In apps created using the uifigure function, add UI components to your app using component functions such as uibutton and uidropdown. Creating apps using the figure and uicontrol functions will continue to be supported. However, there are benefits to using UI components in a uifigure-based app over UIControl objects in a figure-based app. For example, these are some functionalities that exist only in uifigure-based apps:

  • New component types, such as trees, hyperlinks, and instrumentation components

  • Layout tools to configure your app layout, such as grid layout managers

  • Additional component customization options, such as component properties that control text alignment and component placeholder text

To take advantage of these benefits, transition your figure-based app to use the uifigure function. Then, follow these steps to replace UIControl objects in your app with UI components:

  1. Replace calls to the uicontrol function with calls to the corresponding UI component function.

  2. Update properties of the UI component.

  3. Update callbacks of the UI component.

Replace uicontrol Function Calls

The uicontrol function has an argument for specifying the style of the control. Every UIControl style corresponds to a UI component object with similar functionality and appearance. In uifigure-based apps, replace calls to the uicontrol function with the corresponding UI component function. This table provides a list of the UIControl styles and the corresponding UI component function.

UIControl ObjectsUI Component Objects
StyleAppearanceFunctionAppearance
'pushbutton'

UIControl object with push button style

uibutton

Button UI component

'togglebutton'

Two UIControl objects with toggle button style in a button group

  • uibutton with 'state' style for a single, independent state button

  • uitogglebutton for a group of linked toggle buttons

Two toggle button UI components in a button group

'checkbox'

UIControl object with check box style

uicheckbox

Check box UI component

'radiobutton'

Two UIControl objects with radio button style in a button group

uiradiobutton

Two radio button UI components in a button group

'edit' (single line)

UIControl object with single-line edit field style

uieditfield

Edit field UI component

'edit' (multiple lines)

UIControl object with multi-line edit field style

uitextarea

Text area UI component

'text'

UIControl object with text style

uilabel

Label UI component

'slider'

UIControl object with slider style

uislider

Slider UI component

'listbox'

UIControl object with list box style

uilistbox

List box UI component

'popupmenu'

UIControl object with pop-up menu style

uidropdown

Drop-down UI component

'frame'

UIControl object with frame style

Panel UI component

Some UI components have slightly different configurations and behavior than their UIControl equivalent. In many cases, you can update your code to adjust for these differences using the following steps.

Slider Differences

The slider UI component created using uislider has a different appearance than the slider UIControl object.

If your app uses a UIControl slider to allow users to scroll in a container, consider removing your code that manages scrolling and using these alternatives instead:

  • Set the Scrollable property of the container to 'on' to enable scrolling.

  • Use the scroll function to scroll within the container programmatically.

Text Input Differences

The 'edit' style UIControl objects align text in the center by default, whereas uieditfield and uitextarea UI components align text on the left. You can specify the text alignment of these UI components by specifying the HorizontalAlignment property.

If your app uses an 'edit' style UIControl object to allow users to input numeric values, you can instead create a numeric edit field using the uieditfield function by specifying the style argument as "numeric":

fig = uifigure;
ef = uieditfield(fig,"numeric");

Parent Container Differences

Both the uicontrol function and UI component functions have an optional first input argument to specify the parent container. If you omit this argument in the uicontrol function, the function adds the control to the current figure. If you omit this argument in a UI component function such as uibutton or uicheckbox, the function creates a new UI figure and adds the component to that figure.

In uifigure-based apps, create the main app UI figure using the uifigure function and return the Figure object as a variable. Then, pass that variable as the first argument to the UI component functions.

fig = uifigure;
btn = uibutton(fig,"BackgroundColor","blue");
cbx = uicheckbox(fig,"Position",[220 100 84 22]);

For more information, see Update App Figure and Containers.

Update Component Properties

UI component objects and UIControl objects have many of the same properties. For example, both types of objects have Position, BackgroundColor, and FontSize properties. You can use the same code to set these properties for both UIControl objects and UI components.

However, if you set certain UIControl properties in your app, you might need to update the names or values of these properties when you transition to using UI components. This table lists some common properties of UIControl objects that differ from UI component properties and suggested actions to take if you set these properties in your code. If you encounter an error related to a property that is not listed in the table, see the properties page of the specific UI component to resolve the error. For a list of all UI components and links to their properties, see App Building Components.

UIControl PropertyDescriptionSuggested Actions
String

The String property of a UIControl object specifies the display text for the component. Depending on the UI component, this property is replaced by Text, Value, or Items.

  • Labels, buttons, and check boxes — Replace references to String with Text.

  • Edit fields and text areas — Replace references to String with Value.

  • Drop-down components and list boxes — Replace references to String with Items.

UnitsThe Units property of a UIControl object specifies the units of measurement for the object. UI component objects do not have a Units property. All UI components use pixel units to measure distances.

Update the Position property of your UI components to use pixel units.

Alternatively, if you use normalized units to manage app resize behavior, instead update your app layout to use a grid layout manager.

For more information, see Manage App Resize Behavior Programmatically.

ValueThe Value property modifies the status of certain UIControl objects. For each of these UIControl styles, the equivalent UI component also has a Value property. However, the types of property values you specify might differ.
  • State buttons, toggle buttons, radio buttons, and check boxes — Specify Value as 0 (unselected or raised) or 1 (selected or depressed).

  • Drop-down components and list boxes — Specify Value as an element of Items.

  • Sliders — No changes needed. The Value property for sliders has the same effect in UIControl objects and Slider UI components.

ForegroundColorThe ForegroundColor property of a UIControl object specifies the text color for the component. In UI components, this property is named FontColor.Replace all references to ForegroundColor with FontColor.
Max and MinThe values of the Max and Min properties have different effects depending on the UIControl style. UI components have separate properties with more specific names and behavior.
  • Sliders — Use the Limits property to set the maximum and minimum slider values.

  • Edit fields and text areas — Create an edit field for single-line text and a text area for multi-line text.

  • List boxes — Set the MultiSelect property to 'on' to allow users to select multiple items.

CDataThe CData property specifies an icon or image associated with a UIControl object. UI components that support icons have an Icon property instead. In addition, there is an image UI component for displaying images in an app.
  • Push buttons and toggle buttons — Specify Icon as a 3-D array of truecolor RGB values or a path to an image file.

  • Standalone images — Use the uiimage function.

ExtentThe Extent property of the UIControl object stores the size of the object based on its text and font size. UI components have no equivalent property.If your app uses the Extent property to specify a component size based on the text it contains, update your app layout to use a grid layout manager by using the uigridlayout function. Specify the column width of grid columns that contain components with text as 'fit', which scales the component size to fit the text it contains.
SliderStepThe SliderStep property controls the magnitude of the slider value change when a user clicks the arrow buttons. There is no equivalent functionality for a Slider object created using the uislider function.Determine if this functionality is critical to your app before updating. There is no equivalent functionality in uifigure-based apps.

Update Callbacks

UIControl objects have a Callback property. The callback function assigned to this property executes in response to a user interaction, where the interaction depends on the style of the UIControl. For every UIControl style, the corresponding UI component has an equivalent callback property, but the property name is specific to the user interaction it corresponds to. To transition your app code, wherever you assign a callback function to a Callback property, update the property name to the equivalent callback property for the UI component. This table lists the callback property names for each component type.

UIControl StyleCallback User InteractionEquivalent UI Component Callback
'pushbutton'The user clicks the button.ButtonPushedFcn
'togglebutton'The user clicks the button.ButtonPushedFcn
'checkbox'The user sets or clears the check box.SelectionChangedFcn
'radiobutton'The user clicks the button.SelectionChangedFcn of the parent ButtonGroup container
'edit'The user enters text in the edit field.ValueChangedFcn
'slider'The user changes the slider value.ValueChangedFcn
'listbox'The user selects an item.ValueChangedFcn
'popupmenu'The user selects an item.ValueChangedFcn

For example, this code creates a button UIControl object that prints a statement to the MATLAB® Command Window when the user pushes the button.

c = uicontrol;
c.Style = "pushbutton";
c.Callback = @(src,event)disp("Button pushed");
The behavior is equivalent to creating a uibutton component and setting the ButtonPushedFcn callback property:
fig = uifigure;
btn = uibutton(fig)
btn.ButtonPushedFcn = @(src,event)disp("Button pushed");

If your app uses a KeyPressFcn callback to respond while a user types in an 'edit' style UIControl object, instead consider using the ValueChangingFcn callback when you update your uicontrol function to uieditfield or uitextarea. The ValueChangingFcn callback of an edit field or text area component executes repeatedly as the user types in the component.

fig = uifigure;
ef = uieditfield(fig);
ef.ValueChangingFcn = @(src,event)disp("Typing...");

Key Press and Button Down Callbacks

All UIControl objects have a ButtonDownFcn callback to respond when a user clicks on an object, and KeyPressFcn and KeyReleaseFcn callbacks to respond when a user presses a key when the object has focus. There is no equivalent callback associated with UI components. However, you can update your code to have the same behavior by specifying a WindowButtonDownFcn, WindowKeyPressFcn, or WindowKeyReleaseFcn callback on the UI figure that contains the component. You can then query the object that was last clicked by using the CurrentObject property.

UIControl CallbackUIFigure CallbackExample
ButtonDownFcnWindowButtonDownFcn
fig = uifigure;
lb = uilistbox(fig);
fig.WindowButtonDownFcn = {@processClick,lb};

function processClick(src,event,lb)
    if src.CurrentObject == lb
        disp("List box clicked")
    end
end
KeyPressFcnWindowKeyPressFcn
fig = uifigure;
lb = uilistbox(fig);
fig.WindowKeyPressFcn = {@processKeyPress,lb};

function processKeyPress(src,event,lb)
    if src.CurrentObject == lb
        disp("List box key pressed")
    end
end
KeyReleaseFcnWindowKeyReleaseFcn
fig = uifigure;
lb = uilistbox(fig);
fig.WindowKeyReleaseFcn = {@processKeyRelease,lb};

function processKeyRelease(src,event,lb)
    if src.CurrentObject == lb
        disp("List box key released")
    end
end

Related Topics