About the Common Graphics timer facility

A timer can be used to cause an arbitrary piece of application code to be asynchronously invoked after a specified amount of time has elapsed. A timer can then be stopped in order to run its code a single time only, or it can be allowed to continue running in order to run its code an indefinite number of times at a regular time interval.

Common Graphics has a timer class, which can be instantiated to create a timer object. A single timer can be started and stopped a number of times, using various time intervals, to time a number of different activities. If multiple activities need to be timed simultaneously, then multiple timers can be created and run alongside each other. It is also convenient to create a separate timer for each piece of code that is to be invoked by timers, even when they do not need to run simultaneously.

A timer is an instance of the timer class, which has the following properties. All of these except for id may be set by an application. See the page for the timer class or for the individual properties for more detailed information.

• name: an arbitrary symbol that is used to find a timer (by calling find-timer), or to distinguish an individual timer during development and debugging.
• active: a boolean value indicating whether a timer is currently running. An active timer "fires" each time its interval passes, while an inactive timer does nothing. This property of a timer will be non-nil if start-timer has been called on the timer more recently than stop-timer has. If the active property is explicitly modified by an application from nil to non-nil, then start-timer is called internally, and if the active property is explicitly modified from non-nil to nil, then stop-timer is called internally. Therefore, in order to wrap all starting and stopping of timers, it is sufficient to add start-timer and stop-timer methods.
• id: a positive integer that is assigned and used by the operating system to uniquely identify a particular timer. Use of id is deprecated. An application should never modify this property. Any given timer object will always use the same id, and no other timer object will use that id.
• interval a positive integer indicating the number of milliseconds after a timer is started that it will "fire" by calling the generic function timer. The default timer method calls the timer's individual on-timer function (if it has one), which is where timer messages are usually handled by an application. If the interval property is modified while a timer is active, then the timer is stopped and immediately restarted using the new interval. The interval default-initarg for the timer class is 1000, which will fire the timer once a second.
• on-timer: the name of a function that is invoked after the timer's interval has elapsed (assuming that the default timer method has not been overridden). The function should take a single argument, which is the timer itself. Its returned values are not used. The default value is nil, and so a timer will not "do anything" unless it is given a custom on-timer function (or a timer method is added for it).

  An on-timer function may call stop-timer on the timer (or set the timer's active property to nil) if the on-timer function should be invoked only a single time after the timer is started. Otherwise the on-timer function will be called each time the timer's interval has elapsed until stop-timer is called on the timer (or its active property is set to nil).

• timer-count: a non-negative integer indicating the number of times that a timer's interval has elapsed since it was most recently started. This value is supplied for general information, and is not used internally by Common Graphics. An application could modify this value if desired, though there is probably no reason to do so.

  When a timer is started, this property is set to zero. Each time a timer's interval has elapsed, the default timer method increments the timer's timer-count by one and then calls its on-timer function. If a timer count reaches 50 million, it is reset to zero to prevent the consing of bignums.

• timer-info: a place for an application to store arbitrary information about its current use of a timer. Typically, when an application starts a timer, it will store an object here to which the timer's on-timer function may (or may not) apply its functionality when it is invoked. The value of this property can be any Lisp object.

  (The timer class can of course be subclassed in order to add custom slots for this or any other purpose, but this single timer-info slot is provided since such a handy place is often needed due to the asynchronous nature of timers, and a single slot is often sufficient.)

Functions that apply to all timers

find-timer
start-timer
stop-timer
timer

Functions apply to particular built-in timers

• cg-timer (returns a built-in timer that is used internally by common graphics for a variety of purposes and which normally is always active).
• handle-cg-timer (a generic function that is called whenever the built-in timer returned by cg-timer fires).
• cg-timer-interval
• tooltip-delay
• menu-tooltip-delay
• multi-picture-button-scroll-interval

A trivial timer example

On the GTK platform you might need to adjust the value of *cg-timer-resolution*.

;; Define an on-timer event handler 
(defun my-on-timer (timer)
   ;; Show a status bar message each time the timer fires.
   (lisp-message "Timer event ~a for ~s"
     (timer-count timer)(name timer)))

;; Create a timer that uses the above on-timer event-handler.
(setq tim (make-instance 'timer :on-timer 'my-on-timer))

(active tim) ==> nil        ;; the new timer is not active yet

;; Start the timer, telling it to fire every half second
(start-timer tim :interval 500)

(active tim) ==> t          ;; now it's active

(stop-timer tim)            ;; stop it for a while

(setf (active tim) t)       ;; this is another way to start it back up

(setf (interval tim) 800)   ;; slow it down even while it's running

(setf (active tim) nil)     ;; another way to stop it

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.