Main Content

Customize Properties of HTML UI Component

To extend your custom UI component using third-party visualizations or widgets, create a component class that contains an HTML UI component. Use the HTML UI component to customize the component appearance and to interface with third-party libraries, and use the component class to define component properties and callbacks that the user can set.

Class Construction Overview

To create a custom UI component class that uses an HTML UI component, there are two files that you must create.

  • UI component class file — In this file, you define your component class. You specify its properties, its property values, the events it listens for, and the callback functions it triggers. Its properties must include one that will contain the HTML UI component.

  • HTML source file — In this file, you configure and update the visual appearance of the UI component, listen for user interactions, and pass the information that an interaction has occurred to the UI component class.

Your code must communicate changes to property values and user interactions across these two files.

Enable Response to Property Updates

Since the UI component class file defines the properties that users can set, but the HTML source file controls the visual style of the component, these two files need to communicate about property updates.

In the UI component class file, configure the properties of your UI component. Specify the properties that users can set by defining them as public properties in a properties block. In the update method of your class, store the values of the public properties as fields in a struct in the Data property of your HTML UI component. This gives the HTML source file access to these property values.

In the HTML source file, use the property values to update the appearance of the HTML UI component. To do so, in the setup function inside of a <script> tag, access the values of the fields in Data and use them to modify the style properties of your HTML elements.

Enable Response to User Interactions

Users define component callback functions in MATLAB®, but these callbacks often listen for a response to an action performed on an HTML element defined in the HTML source file. So these two files also need to communicate about user interactions.

In the UI component class file, first create the callback properties of your UI component. Create an events block with the HasCallbackProperty. When you define an event in this block, MATLAB creates an associated public callback property for the UI component. For example, if you create an event named ButtonPushed, this will automatically create a public property for your class named ButtonPushedFcn.

To execute a user-defined callback function associated with a user interaction, your code must first recognize when the user interaction has occurred. In the UI component class file, give the HTML UI component a way to do this. In the setup method, set the Data property of the HTML UI component to a struct with a field to store information about whether the interaction has occurred. Because the class file and the HTML source file share this property and its value, the HTML source file can update the value to communicate the user interaction status to the UI component class. To accomplish this, in the HTML source file, in the setup function inside of a <script> tag, create an event listener that listens for the user interaction. When the listener detects the interaction, update the Data property of the HTML UI component.

After the UI component class file receives the information that a user interaction has occurred, it must then trigger the event associated with the interaction. Create a class method to do this. In the class method, first call the built-in notify method to trigger the event you defined. This executes the user-defined callback function associated with the event. Then, set the Data property of the HTML component to wait for another interaction. In the setup method of the UI component class file, set the DataChangedFcn property of the HTML component to the class method you defined. The HTML UI component executes this method automatically whenever the Data property changes. Therefore, after the HTML source file updates the Data property to communicate that the interaction has occurred, this method executes the appropriate callback.

RoundButton Class Implementation

This example demonstrates a typical structure for writing a custom UI component class that uses an HTML UI component. The class creates a button with a custom rounded style. It allows users to specify the button color, text, text color, and response on click.

To define your UI component class, create two files in the same folder on the MATLAB path:

  • RoundButton.m — UI component class definition

  • RoundButton.html — HTML source file

RoundButton.m Class Definition

RoundButton classDiscussion
classdef RoundButton < matlab.ui.componentcontainer.ComponentContainer
Create a custom UI component named RoundButton by defining a subclass of the matlab.ui.componentcontainer.ComponentContainer class.
    properties
        Color {mustBeMember(Color, ...
            {'white','blue','red','green','yellow'})} = 'white'
        FontColor {mustBeMember(FontColor, ...
            {'black','white'})} = 'black'
        Text (1,:) char = 'Button';
    end

Define the Color, FontColor, and Text public properties for your RoundButton class. These are properties that the user can set when creating a RoundButton instance.

For more information on defining properties, see Manage Properties of Custom UI Components.

    properties (Access = private, Transient, NonCopyable)
        HTMLComponent matlab.ui.control.HTML
    end

Define the HTMLComponent private property to hold the HTML UI component.

    events (HasCallbackProperty, NotifyAccess = protected)
        % Generate a ButtonPushedFcn callback property
        ButtonPushed
    end

Define a ButtonPushed event in an events block. Specify the HasCallbackProperty for the events block to automatically generate a ButtonPushedFcn public property for the class.

    methods (Access=protected)
Create a methods block.
        function setup(obj)
            % Set the initial position of this component
            obj.Position = [100 100 80 40];

            % Create the HTML component
            obj.HTMLComponent = uihtml(obj);
            obj.HTMLComponent.Position = [1 1 obj.Position(3:4)];
            obj.HTMLComponent.HTMLSource = fullfile(pwd,'RoundButton.html');
            obj.HTMLComponent.Data = struct('Clicked',false);
            obj.HTMLComponent.DataChangedFcn = @(s,e)notifyClick(obj);
        end

Define the setup method for your class. Within the method, set the initial position of your component relative to its parent container.

Then, create an HTML component by calling the uihtml function. Set the following properties for your HTML component:

  • Position — the position of the HTML component relative to the position of the custom UI component.

  • HTMLSource — the source file that contains the HTML markup for the HTML component.

  • Data — a struct with a Clicked field with value false. Code in the HTML source file sets this field to true when the user clicks the HTML component.

  • DataChangedFcn — an anonymous function that calls a class method named notifyClick. This function runs when the Data property of the HTML component changes.

        function update(obj)
            % Update the HTML component data
            obj.HTMLComponent.Data.Color = obj.Color;
            obj.HTMLComponent.Data.FontColor = obj.FontColor;
            obj.HTMLComponent.Data.Text = obj.Text;
            obj.HTMLComponent.Position = [1 1 obj.Position(3:4)];
        end
Define the update method for your class. Within the method, store the values of the Color, FontColor, and Text properties as fields in the Data property of the HTML component. This enables you to update the attributes of the HTML button element, and lets the HTML component listen for when these properties are changed.
        function notifyClick(obj)
            if obj.HTMLComponent.Data.Clicked
                obj.HTMLComponent.Data.Clicked = false;
                drawnow
                notify(obj,'ButtonPushed');
            end
        end
Define the function that runs when the Data property changes, which is called notifyClick. The function first checks to see if the Clicked field of the HTML component data is true. If so, the function sets the Clicked data field to false to await the next button click. The function also fires the ButtonPushed event, which in turn executes the user-defined ButtonPushedFcn property.
    end
end

Close the methods block and the class definition.

RoundButton.html Source Definition

HTML SourceDiscussion
<!DOCTYPE html>
<html>
<head>

Open the <html> tag and the <head> tag.

<style>
html, body {
  height: 100%;
  text-align: center;
}

button {
  width: 100%;
  height: 100%;
  border-radius: 2em;
  font-size: 1em;
  cursor: pointer;
  border: none;
}

button:focus {
  outline: 0;
}
</style>

Define the style for the HTML content using CSS markup:

  • Set the height of the HTML body to scale to fill the entire container in which it is displayed.

  • Define the relative size of the button within the document body, the radius of the button edges, the font size, the cursor style when pointing to the button, and the button border style.

  <script type="text/javascript">
    function setup(htmlComponent) {
Write a setup function inside of a <script> tag to connect your JavaScript® object, called htmlComponent, to the HTML UI component you created in MATLAB.
    htmlComponent.addEventListener("DataChanged", function(event) {
      buttonElement = document.getElementById("roundButton");
      buttonElement.style.backgroundColor = htmlComponent.Data.Color;
      buttonElement.innerHTML = htmlComponent.Data.Text;
      buttonElement.style.color = htmlComponent.Data.FontColor;
    });

Add an event listener to the htmlComponent JavaScript object. This event listener listens for any change in the Data property of the HTMLComponent MATLAB object, and then updates the attributes of the HTML button element in accordance with the RoundButton property values.

    button = document.getElementById("roundButton");  
    button.addEventListener("click", function(event) {
      htmlComponent.Data.Clicked = true;
      htmlComponent.Data = htmlComponent.Data;
    });

Add an event listener to the HTML button. This event listener listens for the button element to be clicked. When a user clicks the button, the function:

  • Updates the Clicked field of the HTML component data to true

  • Explicitly set the Data property of the HTML component. This notifies the MATLAB HTML component object to execute the DataChangedFcn callback.

    }
  </script>
</head>
Close the setup function and the <script> and <head> tags.
  <body>
    <button id="roundButton"></button><br/> 
  </body>
Create a button element in the body of the HTML document.
</html>
Close the <html> tag.

Create a RoundButton Instance

After creating and saving RoundButton.m and RoundButton.html, create an instance of the RoundButton class in a UI figure.

Specify the Color, FontColor, and the ButtonPushedFcn callback properties as name-value arguments.

fig = uifigure('Position',[200 200 300 300]);
btn = RoundButton(fig, ...
    'Color','red', ...
    'FontColor','white', ...
    'ButtonPushedFcn',@(o,e)disp('Clicked'));

Click the button. The Command Window displays Clicked.

See Also

Classes

Functions

Related Topics