set

Class: timer

Set property values for timer object

expand all in page

Syntax

set(t)
propStruct = set(t)
set(t,Name)
propCell = set(t,Name)
set(t,Name,Value)
set(t,S)
set(t,PN,PV)

Description

example

set(t) displays the property names and their possible values for all configurable properties of timer object t.

example

propStruct = set(t) returns the values in a struct.

example

set(t,Name) displays the possible values for the specified property, Name, of timer object, t.

example

propCell = set(t,Name) returns the values in a cell.

example

set(t,Name,Value) sets the properties specified by one or more Name,Value pair arguments. t can be a single timer object or a vector of timer objects, in which case set configures the property values for all timer objects, t.

example

set(t,S) configures the properties of t, with the values specified in S, where S is a structure whose field names are object property names.

example

set(t,PN,PV) configures the properties specified in the cell array of character vectors, PN, to the corresponding values in the cell array PV, for the timer object t.

Input Arguments

t

Object of class timer.

S

Structure whose field names are timer property names.

PN,PV

Cell array of character vectors, PN, and corresponding cell array of values, PV. The cell array of PN must be a 1-by-N or N-by-1 array. If t is an array of timer objects, PV can be an M-by-N cell array, where M is equal to the length of t and N is equal to the length of PN. In this case, each timer object is updated with a different set of values for the list of property names contained in PN.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'BusyMode'

Character vector or string scalar that indicates action taken when a timer has to execute TimerFcn before the completion of previous execution of the TimerFcn. When Running='on', BusyMode is read only. This table summarizes the busy modes.

BusyMode Values

Behavior if Queue Empty

Behavior if Queue Not Empty

Notes

'drop'

Adds task to queue

Drops task

Possible skipping of TimerFcn calls

'error'

Adds task to queue

Completes task; throws error specified by ErrorFcn; stops timer

Stops timer after completing task in execution queue

'queue'

Adds task to queue

Waits for queue to clear, and then enters task in queue

Adjusts Period property to manage tasks in execution queue

See Handling Timer Queuing Conflicts for more information.

Default: 'drop'

'ErrorFcn'

Character vector, string scalar, function handle, or cell array defining the function that the timer executes when an error occurs. If there is an error, this function executes, and then calls StopFcn.

  • If you specify this property using a character vector or string scalar, when MATLAB® executes the callback it evaluates the MATLAB code contained in the character vector.

  • If you specify this property using a function handle, when MATLAB executes the callback it passes the timer object and an event structure to the callback function. The event structure contains the type of event in the Type field and the time of the event in the Data field.

  • If your callback function accepts arguments in addition to the timer object and event data, specify this property as a cell array containing the function handle and the additional arguments.

For more information, see Timer Callback Functions.

'ExecutionMode'

Character vector or string scalar that defines how the timer object schedules timer events. When Running='on', ExecutionMode is read only. This table summarizes the execution modes.

Execution Mode

Time Period Start Point

'singleShot'

In this mode, the timer callback function is only executed once. Therefore, the Period property has no effect. This is the default execution mode.

'fixedRate'

Starts immediately after the timer callback function is added to the MATLAB execution queue

'fixedDelay'

Starts when the timer function callback restarts execution after a time lag due to delays in the MATLAB execution queue

'fixedSpacing'

Starts when the timer callback function finishes executing.

  • 'singleShot' is the single execution mode for the timer class, and is the default value.

  • 'fixedDelay', 'fixedRate', and 'fixedSpacing' are the three supported multiexecution modes. These modes define the starting point of the Period property. The Period property specifies the amount of time between executions, which remains the same. Only the point at which execution begins is different.

Default: 'singleShot'

'Name'

Character vector or string scalar representing the timer name.

Default: 'timer-i', where i is a number indicating the ith timer object created this session. To reset i to 1, execute the clear classes command.

'ObjectVisibility'

Character vector or string scalar with possible values of 'on' or 'off', that provides a way for you to discourage end-user access to the timer objects your application creates. The timerfind function does not return an object whose ObjectVisibility property is set to 'off'. Objects that are not visible are still valid. To retrieve a list of all the timer objects in memory, including the invisible ones, use the timerfindall function.

Default: 'on'

'Period'

Number greater than 0.001 that specifies the delay, in seconds, between executions of TimerFcn. For the timer to use Period, you must set ExecutionMode and TasksToExecute to schedule multiple timer object callback events.

Default: 1.0

'StartDelay'

Number greater than or equal to 0 that specifies the delay, in seconds, between the start of the timer and the first execution of the function specified in TimerFcn. When Running = 'on', StartDelay is read only.

Default: 0

'StartFcn'

Character vector, string scalar, function handle, or cell array defining the function that executes when the timer starts.

  • If you specify this property using a character vector or string scalar, when MATLAB executes the callback it evaluates the MATLAB code contained in the character vector.

  • If you specify this property using a function handle, when MATLAB executes the callback it passes the timer object and an event structure to the callback function. The event structure contains the type of event in the Type field and the time of the event in the Data field.

  • If your callback function accepts arguments in addition to the timer object and event data, specify this property as a cell array containing the function handle and the additional arguments.

For more information, see Timer Callback Functions.

'StopFcn'

Character vector, string scalar, function handle, or cell array defining the function that executes when the timer stops.

  • If you specify this property using a character vector or string scalar, when MATLAB executes the callback it evaluates the MATLAB code contained in the character vector.

  • If you specify this property using a function handle, when MATLAB executes the callback it passes the timer object and an event structure to the callback function. The event structure contains the type of event in the Type field and the time of the event in the Data field.

  • If your callback function accepts arguments in addition to the timer object and event data, specify this property as a cell array containing the function handle and the additional arguments.

For more information, see Timer Callback Functions.

The timer stops when

  • You call the timer stop method.

  • The timer finishes executing TimerFcn. In other words, the value of TasksExecuted reaches the limit set by TasksToExecute.

  • An error occurs. The ErrorFcn callback is called first, followed by the StopFcn callback.

You can use StopFcn to define clean up actions, such as deleting the timer object from memory.

'Tag'

Character vector or string scalar that represents a label for the object.

'TasksToExecute'

Number greater than 0, indicating the number of times the timer object is to execute the TimerFcn callback. Use the TasksToExecute property to set the number of executions. To use TasksToExecute, you must set ExecutionMode to schedule multiple timer callback events.

Default: Inf

'TimerFcn'

Character vector, string scalar, function handle, or cell array defining the timer callback function. You must define this property before you can start the timer.

  • If you specify this property using a character vector or string scalar, when MATLAB executes the callback it evaluates the MATLAB code contained in the character vector.

  • If you specify this property using a function handle, when MATLAB executes the callback it passes the timer object and an event structure to the callback function. The event structure contains the type of event in the Type field and the time of the event in the Data field.

  • If your callback function accepts arguments in addition to the timer object and event data, specify this property as a cell array containing the function handle and the additional arguments.

For more information, see Timer Callback Functions.

'UserData'

Generic field for data that you want to add to the object.

Output Arguments

propStruct

Configurable properties of t, returned as a structure. The field names of propStruct are the property names of t, and the associated values of propStruct are cell arrays of the possible property values. If the property in t does not have a finite set of possible values, the property value in propStruct is an empty cell array.

propCell

Possible values of a given property name, returned as cell array of character vectors. If the property does not have a finite set of possible values, set returns an empty cell array.

Examples

expand all

Open Live Script

Instantiate a timer object and call the set method. 

t = timer;
set(t)
                Name: {}
                 Tag: {}
    ObjectVisibility: {2x1 cell}
      TasksToExecute: {}
            StartFcn: {}
             StopFcn: {}
            ErrorFcn: {}
            TimerFcn: {}
          StartDelay: {}
              Period: {}
            BusyMode: {3x1 cell}
       ExecutionMode: {4x1 cell}
            UserData: {}

Some of the timer properties, such as Running, are not displayed because they are read only.

Use the set method to output a structure. 

out = set(t)
out = struct with fields:
                Name: {}
                 Tag: {}
    ObjectVisibility: {2x1 cell}
      TasksToExecute: {}
            StartFcn: {}
             StopFcn: {}
            ErrorFcn: {}
            TimerFcn: {}
          StartDelay: {}
              Period: {}
            BusyMode: {3x1 cell}
       ExecutionMode: {4x1 cell}
            UserData: {}

Delete the timer object from memory. 

delete(t)
Open Live Script

Instantiate a timer object and display possible values for the BusyMode property. 

t = timer;
set(t,'BusyMode')
  3x1 cell array

    {'drop' }
    {'queue'}
    {'error'}

The output shows the three possible values for BusyMode. The default value, drop, is indicated by curly braces.

Display the possible values for ErrorFcn. 

set(t,'ErrorFcn')
  0x0 empty cell array

A description of the possible values is displayed since ErrorFcn does not have a set list of possible values.

Output the possible property values. 

out1 = set(t,'BusyMode')
out1 = 3x1 cell
    {'drop' }
    {'queue'}
    {'error'}


out2 = set(t,'ErrorFcn')
out2 =

  0x0 empty cell array

While set(t,'ErrorFcn') displays a description of the possible values, out2 = set(t,'ErrorFcn') returns an empty cell.

Delete the timer from memory. 

delete(t)
Open Live Script

Instantiate a timer object and make the object invisible. Display the object's visibility and delete the object. 

t = timer;
set(t,'ObjectVisibility','off')
get(t,'ObjectVisibility')
ans = 
'off'

delete(t)
Open Live Script

Construct a structure to modify several timer object properties. 

s.BusyMode = 'queue';
s.ExecutionMode = 'fixedDelay';
s.ObjectVisibility = 'off'
s = struct with fields:
            BusyMode: 'queue'
       ExecutionMode: 'fixedDelay'
    ObjectVisibility: 'off'

Create a timer, display the properties in s, modify the timer, display the new values of the properties, and delete the timer. 

t = timer;
get(t,{'BusyMode','ExecutionMode','ObjectVisibility'})
ans=1×3 cell array
    {[drop]}    {[singleShot]}    {'on'}


set(t,s)
get(t,{'BusyMode','ExecutionMode','ObjectVisibility'})
ans=1×3 cell array
    {[queue]}    {[fixedDelay]}    {'off'}


delete(t)
Open Live Script

Create a cell array of properties to modify, and a cell array of the values of the corresponding properties. Instantiate a timer, and display the initial values of the properties in the property name cell array, nameArr. 

nameArr = {'BusyMode','ExecutionMode','Period'};
valArr = {'queue','fixedDelay',3};
t = timer;
get(t,nameArr)
ans=1×3 cell array
    {[drop]}    {[singleShot]}    {[1]}

Modify the timer object and display the new property values. Delete the timer. 

set(t,nameArr,valArr)
get(t,nameArr)
ans=1×3 cell array
    {[queue]}    {[fixedDelay]}    {[3]}


delete(t)

Instantiate an array of three timers. Create a new property name cell array to modify the BusyMode, ExecutionMode, and UserData properties. Display the initial values of the properties for each timer. 

tArr = [timer timer timer];
nameArr = {'BusyMode','ExecutionMode','UserData'};
get(tArr,nameArr)
ans=3×3 cell array
    {[drop]}    {[singleShot]}    {0x0 double}
    {[drop]}    {[singleShot]}    {0x0 double}
    {[drop]}    {[singleShot]}    {0x0 double}

Assign each property a different value in each timer. Create a cell array containing the new values. Each row indicates the values for the properties in the corresponding timer. 

valArr = {'queue','fixedDelay',3;...
            'error','fixedSpacing',42;...
            'drop','fixedRate','hello'};

Modify the timer object properties and display the updated values. 

set(tArr,nameArr,valArr)
get(tArr,nameArr)
ans=3×3 cell array
    {[queue]}    {[fixedDelay  ]}    {[    3]}
    {[error]}    {[fixedSpacing]}    {[   42]}
    {[drop ]}    {[fixedRate   ]}    {'hello'}

Delete the timers from memory. 

delete(tArr)

Alternatives

You can also use dot notation to set timer object properties. For example, t.ObjectVisibility = 'off' sets the property to the same value as set(t,'ObjectVisibility','off').

See Also

|

Introduced before R2006a

MATLAB Documentation

Support