Create Custom UI Component With HTML - MATLAB & Simulink (original) (raw)

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

Custom Component Overview

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

Custom UI component file — In this file, you define your custom component. You specify its properties, its property values, the events it listens for, and the callback functions it executes.
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 custom 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 custom UI component 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 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 theData 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 inData 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 theHasCallbackProperty. 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 namedButtonPushed, 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 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, inform MATLAB that the interaction has occurred by using thesendEventToMATLAB JavaScript® function.

After the UI component class file receives the information that a user interaction has occurred, it must then trigger the callback associated with the interaction. To do this, in the setup method of the custom UI component, create an HTMLEventReceivedFcn callback function for the HTML UI component. This function executes whenever the component receives an event from the HTML source. In the callback function, call thenotify function on the custom UI component event you defined. This executes the user-defined callback function associated with the event.

`RoundButton` Class Implementation

This example demonstrates a typical structure for writing a custom UI component that uses an HTML UI component. The example shows how to create a custom button component as a subclass of the ComponentContainer base class. For an example of a custom button component created in App Designer, see Create Custom Button with Hover Effect Using HTML.

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 class	Discussion
classdef RoundButton < matlab.ui.componentcontainer.ComponentContainer	Create a custom UI component namedRoundButton by defining a subclass of thematlab.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, andText public properties for yourRoundButton class. These are properties that the user can set when creating aRoundButton instance.For more information on defining properties, see Manage Properties of Custom UI Components Programmatically.
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 ButtonPushedFcn callback property ButtonPushed end	Define a ButtonPushed event in anevents block. Specify theHasCallbackProperty for theevents block to automatically generate a ButtonPushedFcn public property for the class.
methods (Access=protected)	Create a methods block.
function setup(comp) % Set the initial position of this component comp.Position = [100 100 80 40]; % Create the HTML component comp.HTMLComponent = uihtml(comp); comp.HTMLComponent.Position = [1 1 comp.Position(3:4)]; comp.HTMLComponent.HTMLSource = fullfile(pwd,"RoundButton.html"); comp.HTMLComponent.HTMLEventReceivedFcn = @(src,event) notify(comp,"ButtonPushed"); 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.HTMLEventReceivedFcn — An anonymous function that sends out a notification for the ButtonPushed event, which executes the user-definedButtonPushedFcn callback. TheHTMLEventReceivedFcn callback function runs when the component receives an event from the HTML source.
function update(comp) % Update the HTML component data comp.HTMLComponent.Data.Color = comp.Color; comp.HTMLComponent.Data.FontColor = comp.FontColor; comp.HTMLComponent.Data.Text = comp.Text; comp.HTMLComponent.Position = [1 1 comp.Position(3:4)]; end	Define the update method for your class. Within the method, store the values of theColor, FontColor, andText properties as fields in theData 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.
end end	Close the methods block and the class definition.

`RoundButton.html` Source Definition

HTML Source	Discussion
	Open the tag and the tag.
	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.
	Close the setup function and the