matlab.task.LiveTask - Base class for developing custom Live Editor tasks - MATLAB (original) (raw)
Namespace: matlab.task
Base class for developing custom Live Editor tasks
Since R2022a
Description
matlab.task.LiveTask
is a class you build on to make your own Live Editor tasks. When you define a subclass of this base class, you can use the LiveTask
properties and methods to build your Live Editor tasks. Specify this syntax on the first line of your class definition file to directly inherit from the LiveTask
class, where MyTask
is the name of your task:
classdef MyTask < matlab.task.LiveTask
The matlab.task.LiveTask
class is a handle class.
Class Attributes
Abstract | true |
---|---|
ConstructOnLoad | true |
HandleCompatible | true |
For information on class attributes, see Class Attributes.
Properties
Public Properties
Parent container of the task, specified as a Figure
object.
Attributes:
GetAccess | public |
---|---|
SetAccess | private |
Transient | true |
Dependent | true |
GetObservable | true |
SetObservable | true |
NonCopyable | true |
Current state of UI objects in the task, specified as a struct.
Define the get.State
and set.State
methods for your class to get and set the State
of the task. The Live Editor uses these methods to restore a task to a specified state during copy, paste, undo, and redo operations, as well as when the live script containing the task is closed and reopened. The current state of the task is stored in a struct. When the live script is closed, the Live Editor uses the jsonencode
function to convert the struct returned by get.State
to JSON format and saves the encoded state with the live script. When the live script is reopened, the Live Editor converts the encoded state back to a struct, which is then used to set the current state of the task using set.State
. Refer to the jsonencode function for more information about the data types it supports.
For more information about defining the get.State
andset.State
methods, see Live Editor Task Development Overview.
Attributes:
GetAccess | public |
---|---|
SetAccess | public |
Dependent | true |
Abstract | true |
Task summary, specified as a string scalar or character vector. The task summary displays at the top of the task and remains visible when the task is collapsed.
Define the get.Summary
method for your class to get theSummary
of the task. The Live Editor uses this method to dynamically generate the description of what the task does.
For more information about defining the get.Summary
method, seeLive Editor Task Development Overview.
Attributes:
GetAccess | public |
---|---|
SetAccess | protected |
Dependent | true |
Abstract | true |
Run task automatically on change, specified as a numeric or logical1
(true
) or 0
(false
). Set to 1
to have the task run automatically when a user modifies the task parameters.
Attributes:
GetAccess | public |
---|---|
SetAccess | public |
SetObservable | true |
AbortSet | true |
Protected Properties
Task grid layout manager, specified as a GridLayout
. Add all graphics and UI objects for the task to the grid layout manager. If an object is added to the task directly, MATLABĀ® throws an error.
Attributes:
GetAccess | protected |
---|---|
SetAccess | protected |
Methods
Abstract Methods
generateCode | Generate code for instance of Live Editor task subclass |
---|---|
reset | Reset instance of Live Editor task subclass |
Abstract Methods
setup | Set up instance of Live Editor task subclass |
---|
Examples
Define a class called DisplayImage
that creates a custom Live Editor task for displaying an image.
To define the class, create a file called DisplayImage.m
that contains the following class definition with these features:
State
andSummary
public properties that store the current state of the task and a dynamic summary of what the task does.- Private properties that store the edit field and button for selecting an image.
- A
setup
method that initializes the task. - A
generateCode
method that updates the generated code for the task when the selected image changes. get.Summary
,get.State
, andset.State
methods for getting and setting the summary and state of the task.- An
inputImageFile
method that prompts the user to select an image to display. - A
reset
method that resets the state of the task.
classdef DisplayImage < matlab.task.LiveTask properties(Access = private,Transient) FileNameEditField matlab.ui.control.EditField BrowseButton matlab.ui.control.Button end
properties(Dependent)
State
Summary
end
methods(Access = protected)
function setup(task)
createComponents(task);
setComponentsToDefault(task);
end
end
methods
function [code,outputs] = generateCode(task)
if isempty(task.FileNameEditField.Value)
% Return empty values if there is not enough
% information to generate code
code = "";
outputs = {};
return
end
outputs = {"im"};
code = ["% Get Image"
outputs{1} + " = imread(""" + ...
task.FileNameEditField.Value + """);"
""
"% Visualize results"
"figure"
"imshow(" + outputs{1} + ");"];
end
function summary = get.Summary(task)
if isempty(task.FileNameEditField.Value)
summary = "Display selected image";
else
[~,name,~] = fileparts(task.FileNameEditField.Value);
summary = "Display image '" + name + "'";
end
end
function state = get.State(task)
state = struct;
state.FileNameEditFieldValue = task.FileNameEditField.Value;
end
function set.State(task,state)
task.FileNameEditField.Value = state.FileNameEditFieldValue;
end
function reset(task)
setComponentsToDefault(task);
end
end
methods(Access = private)
function createComponents(task)
task.LayoutManager.RowHeight = ["fit" "fit" "fit"];
task.LayoutManager.ColumnWidth = "fit";
% Row 1: Select image section label
uilabel(task.LayoutManager,"Text","Select image", ...
"FontWeight","bold");
% Row 2: Select data section components
inputgrid = uigridlayout(task.LayoutManager,"RowHeight", ...
"fit","ColumnWidth",{"fit",200,"fit"},"Padding",0);
uilabel(inputgrid,"Text","Input image");
task.FileNameEditField = uieditfield(inputgrid, ...
"Editable",false);
task.BrowseButton = uibutton(inputgrid,"Text","Browse", ...
"ButtonPushedFcn",@task.inputImageFile);
% Row 3: Display results section label
uilabel(task.LayoutManager,"Text","Display results", ...
"FontWeight","bold");
end
function setComponentsToDefault(task)
task.FileNameEditField.Value = "";
end
function inputImageFile(task,~,~)
% Display uigetfile dialog box
filterspec = ["*.jpg;*.tif;*.png;*.gif","All Image Files"];
[f,p] = uigetfile(filterspec);
% Make sure user did not cancel uigetfile dialog box
if (ischar(p))
fileName = [p f];
task.FileNameEditField.Value = fileName;
end
notify(task,"StateChanged");
end
end
end
Next, configure the task metadata by calling the matlab.task.configureMetadata
function and selecting the DisplayImage.m
file. The Task Metadata dialog box opens with all of the required task metadata details prepopulated.
Select OK to use the prepopulated metadata details. MATLAB creates a folder named resources
inside the folder containing your task class definition file. Inside the resources
folder, MATLAB generates a file named liveTasks.json
.
Add the folder containing the task class definition file to the MATLAB path by calling the addpath
function or using the Add Folder button in the Set Path dialog box.
Add the task to a live script. On a code line, type display
. MATLAB shows a list of suggested matches.
Select Display Image from the list. MATLAB adds the Display Image task to the live script.
More About
The Live Editor listens for changes in a task and calls thegenerateCode
method to update the task's generated code when it detects a change. The Live Editor detects changes by monitoring the components in the task that fire these events:
ValueChanged
ButtonPushed
ImageClicked
SelectionChanged
To update the generated code for a task when changes occur outside of the events listed (for example, in a component that does not fire these events), you can call thenotify
method to fire the StateChanged
event and trigger a call to the generateCode
method for the task.
notify(task,"StateChanged");
Note
The Live Editor does not monitor events for components that are created dynamically at run time.
Version History
Introduced in R2022a