Main Content

Configure Custom UI Components for App Designer

Starting in R2021a, when you create a custom UI component class, you can configure your component for app creators to use interactively in App Designer. After you configure a UI component, app creators can add the component to the Component Library and can interact with the component on the App Designer canvas and in the Property Inspector.

Follow these configuration steps if you have authored a UI component class defined as a subclass of the matlab.ui.componentcontainer.ComponentContainer base class, and you would like to use it in either of these ways:

  • Access your UI component from the App Designer Component Library and interactively use it to create an App Designer app.

  • Share your UI component for others to use interactively to create apps in App Designer.

Custom UI Component Class Prerequisites

To allow your custom UI component to be used interactively in App Designer, there are some requirements that your UI component class must satisfy.

To successfully configure your UI component, the setup method of your UI component class cannot have required input arguments. Also, the component class cannot dynamically add additional UI components to its parent container. The only exception is that the class can dynamically add a ContextMenu component in the parent figure.

For a public property of your component class to appear in the Property Inspector, you must specify its type or assign a default value to it. If the property is an enumeration, you must both specify its type and assign it a default value. In addition, the property type must belong to the list of types supported by App Designer. This table shows the allowable property types and their appearance in the Property Inspector.

Property CategorySupported Data TypesProperty Inspector Input
NumericalScalars or arrays of type single, double, int8, int32, int64, uint8, uint16, uint32, or uint64Edit field
LogicallogicalCheck box
TextScalars of type string, scalars or row vectors of type char, and scalars or vectors of type cellText area
EnumerationenumerationEditable drop-down menu

For more information on specifying property types and assigning default values, see Manage Properties of Custom UI Components.

Create a UI Component Class to Configure

Create a folder named MyComponents in a particular location, for example, C:\. Copy the ColorSelector class definition and save it with the name ColorSelector.m in the folder C:\MyComponents.

classdef ColorSelector < matlab.ui.componentcontainer.ComponentContainer    
    % UI component to select colors

    % Public properties
    properties
        Value {validateattributes(Value, ...
            {'double'},{'<=',1,'>=',0,'size',[1 3]})} = [1 0 0]; 
    end

    % Events
    events (HasCallbackProperty, NotifyAccess = protected) 
        ValueChanged % ValueChangedFcn will be the generated callback property 
    end
    
    % Private properties
    properties (Access = private, Transient, NonCopyable) 
        Grid matlab.ui.container.GridLayout 
        Button matlab.ui.control.Button 
        EditField matlab.ui.control.EditField 
    end

    methods (Access = protected) 
        function setup(obj) 
            % Grid layout to manage building blocks 
            obj.Grid = uigridlayout(obj,[1 2],'ColumnWidth',{'1x',22}, ... 
                'RowHeight',{'fit'},'ColumnSpacing',2,'Padding',2);              

            % Edit field for value display and button to launch uisetcolor 
            obj.EditField = uieditfield(obj.Grid,'Editable',false, ... 
                'HorizontalAlignment','center'); 
            obj.Button = uibutton(obj.Grid,'Text',char(9998), ... 
                'ButtonPushedFcn',@(o,e) obj.getColorFromUser()); 

        end 
        function update(obj)     
            % Update edit field and button colors 
            set([obj.EditField obj.Button], 'BackgroundColor', obj.Value, ... 
                'FontColor', obj.getContrastingColor(obj.Value));  

            % Update the display text 
            obj.EditField.Value = num2str(obj.Value, '%0.2g ');            
        end 
    end

    methods (Access = private) 
        function getColorFromUser(obj) 
            c = uisetcolor(obj.Value); 
            if (isscalar(c) && (c == 0)) 
                return; 
            end 
            
            % Update the Value property 
            obj.Value = c;              

            % Execute user callbacks and listeners
            notify(obj,'ValueChanged'); 
        end         
        function contrastColor = getContrastingColor(~,color) 
            % Calculate opposite color 
            c = color * 255; 
            contrastColor = [1 1 1]; 
            if (c(1)*.299 + c(2)*.587 + c(3)*.114) > 186 
                contrastColor = [0 0 0]; 
            end 
        end 
    end 
end

Configure App Designer Metadata

Configure your custom UI component for use in App Designer by using the appdesigner.customcomponent.configureMetadata function.

Call the function by passing it the path to your component class file. The function opens the App Designer Custom UI Component Metadata dialog. This dialog allows you to specify metadata about the component. App Designer uses this metadata to display the component in the Component Library.

appdesigner.customcomponent.configureMetadata('C:\MyComponents\ColorSelector.m');

App Designer Custom Component Metadata dialog for the ColorSelector component.

The dialog prepopulates all of the required metadata from the component class definition. You can edit the prepopulated metadata using the form. Select OK to configure the ColorSelector UI component.

After you select OK, the function creates a folder named resources inside the MyComponents folder. Inside the resources folder, the function generates a file named appDesigner.json. This file contains the metadata you provided in the dialog, in addition to other metadata MATLAB® needs to make your component available in App Designer.

Note

Do not modify the appDesigner.json file by hand. To change any custom UI component metadata, use the appdesigner.customcomponent.configureMetadata function.

View Configured UI Component in App Designer

After you configure your custom UI component class using the appdesigner.customcomponent.configureMetadata function, you can view and use it in App Designer. For the UI component to appear in the App Designer Component Library, you must add the folder containing the class file and generated resources folder to the MATLAB path.

For example, to use the ColorSelector UI component in App Designer, add the MyComponents folder to the MATLAB path by following the steps in Change Folders on Search Path. Then, open App Designer by entering appdesigner at the MATLAB command line. When it opens, select Blank App. The ColorSelector UI component appears at the bottom of the Component Library in the My Components section.

Drag an instance of the ColorSelector UI component onto the App Designer canvas. Notice that the Property Inspector lists the public property Value and the ValueChangedFcn callback created in the UI component class definition.

A ColorSelector UI component on the App Designer canvas. The UI component is selected and editable via the App Designer Component Browser.

Note

Avoid making changes to public properties and events in your UI component class definition while using your component in App Designer, as doing so might lead to errors or unexpected behavior.

Reconfigure UI Component

Reconfigure a previously configured UI component class when:

  • You want to change existing UI component metadata and update how the component is displayed in the App Designer Component Library.

  • You have made changes to the UI component position or layout in your class definition.

To reconfigure your UI component, call the appdesigner.customcomponent.configureMetadata function by passing it the path to your UI component class file. The function opens the App Designer Custom Component Metadata dialog with the existing metadata prepopulated.

appdesigner.customcomponent.configureMetadata('C:\MyComponents\ColorSelector.m');

Update the metadata by changing the category to Color and setting the author's name to MathWorks, then select OK.

App Designer Custom Component Metadata dialog for the ColorSelector component with the category and author's name fields edited.

Go back to App Designer. The component now appears in the Color section of the Component Library. Hover on the component. The author's name now appears.

App Designer Component Library with the ColorSelector UI component displayed under the category Color (Add-on). The mouse cursor is pointing to the component, which displays a message with the component name, version, description, author, and file location.

Remove UI Component From App Designer

To remove a custom UI component from App Designer, use the appdesigner.customcomponent.removeMetadata function.

Call the function by passing it the path to your component class file. The function removes the metadata for the UI component from the appDesigner.json file inside the resources folder, and removes the component from the App Designer Component Library.

appdesigner.customcomponent.removeMetadata('C:\MyComponents\ColorSelector.m');

After you remove the App Designer metadata for a custom UI component, any App Designer apps that use it do not load correctly. To continue editing apps that use the UI component, reconfigure it using the appdesigner.customcomponent.configureMetadata function.

Share Configured UI Component

After configuring a UI component, you can share the component for others to use in App Designer. You can either share the relevant files directly or package the component as a toolbox. In either case, you must also share the generated resources folder.

Share UI Component Files Directly

To share a configured UI component directly with a user, create and share a folder with these contents:

  • The UI component class file

  • The generated resources folder

Instruct the user you are sharing the UI component with to add the shared folder to the MATLAB path.

Package UI Component as a Toolbox

Package your UI component as a toolbox by following the steps in Create and Share Toolboxes. Make sure the folder you package as a toolbox has these contents:

  • The UI component class file

  • The generated resources folder

You can share the resulting .mltbx file directly with your users. To install it, they must double-click the .mltbx file in the MATLAB Current Folder browser.

Alternatively, you can share your UI component as an add-on by uploading the .mltbx file to MATLAB Central File Exchange. Your users can find and install your add-on from the MATLAB Toolstrip by performing these steps:

  1. In the MATLAB Toolstrip, on the Home tab, in the Environment section, select Add-Ons .

  2. Find the add-on by browsing through available categories on the left side of the Add-On Explorer window. Alternatively, use the search bar to search for an add-on using a keyword.

  3. Click the add-on to open its detailed information page.

  4. On the information page, click Add to install the add-on.

See Also

Functions

Classes

Related Topics