Documentation Center

  • Trial Software
  • Product Updates

set

Class: timer

Set property values for timer object

Syntax

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 strings, 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 strings, 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 single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'BusyMode'

String 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'

String, 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.

'ExecutionMode'

String 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'

String 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'

String 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'

String, function handle, or cell array defining the function that executes when the timer starts.

'StopFcn'

String, function handle, or cell array defining the function that executes when the timer stops. 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'

String 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'

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

'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 strings. If the property does not have a finite set of possible string values, set returns an empty cell array.

Examples

expand all

Display Configurable Timer Object Properties

Instantiate a timer object and call the set method.

t = timer;
set(t)
    BusyMode: [ {drop} | queue | error ]
    ErrorFcn: string -or- function handle -or- cell array
    ExecutionMode: [ {singleShot} | fixedSpacing | fixedDelay | fixedRate ]
    Name
    ObjectVisibility: [ {on} | off ]
    Period
    StartDelay
    StartFcn: string -or- function handle -or- cell array
    StopFcn: string -or- function handle -or- cell array
    Tag
    TasksToExecute
    TimerFcn: string -or- function handle -or- cell array
    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 = 

            BusyMode: {3x1 cell}
            ErrorFcn: {}
       ExecutionMode: {4x1 cell}
                Name: {}
    ObjectVisibility: {2x1 cell}
              Period: {}
          StartDelay: {}
            StartFcn: {}
             StopFcn: {}
                 Tag: {}
      TasksToExecute: {}
            TimerFcn: {}
            UserData: {}

Delete the timer object from memory.

delete(t)

Display Possible Property Values

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

t = timer;
set(t,'BusyMode')
[ {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')
string -or- function handle -or- 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')
out2 = set(t,'ErrorFcn')
out1 = 

    'drop'
    'queue'
    'error'


out2 = 

     {}

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)

Set Timer Object Property

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

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

off

Set Timer Object Properties Using Structure

Construct a structure to modify several timer object properties.

s.BusyMode = 'queue';
s.ExecutionMode = 'fixedDelay';
s.ObjectVisibility = 'off'
s = 

            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'})
set(t,s);
get(t,{'BusyMode','ExecutionMode','ObjectVisibility'})
delete(t)
ans = 

    'drop'    'singleShot'    'on'


ans = 

    'queue'    'fixedDelay'    'off'

Set Timer Objects Using Cell Arrays

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 = 

    'drop'    'singleShot'    [1]

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

set(t,nameArr,valArr)
get(t,nameArr)
delete(t)
ans = 

    'queue'    'fixedDelay'    [3]

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 = 

    'drop'    'singleShot'    []
    'drop'    'singleShot'    []
    'drop'    'singleShot'    []

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 = 

    '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

|

Was this topic helpful?