highlight-hotspot

Arguments: hotspot &key off

This generic function is called internally whenever a hotspot may need to be highlighted or unhighlighted. The default method will draw or erase highlighting if the hotspot's highlight-style is :invert or :outline (rather than nil).

hotspot is the hotspot that could be highlighted or unhighlighted. off will be nil when the hotspot should be highlighted, or true when it should be unhighlighted.

If the default highlighting styles are not adequate, an application could supply its own highlight-hotspot method to draw the highlighting in some arbitrary way. The default method sets the paint-operation to po-xor so that it can draw and erase the highlighting without any knowledge of what is drawn beneath the highlighting. A custom method could do likewise, or it could draw in the usual po-replace mode. In the latter case, erasing the highlight consists of drawing whatever is usually drawn in the window without redrawing the hotspot highlighting over it. So a custom method could simply call invalidate on the hotspot when the off argument is true (which will cause the window's redisplay-window method to redraw that area without the highlighting), and draw any sort of hotspot highlighting when the off argument is nil. The method can call hotspot-region on the hotspot to find the coordinates of the hotspot, and call region-box on that region to find the smallest box that contains the hotspot's coordinates.

Specifically, highlight-hotspot is called by the default mouse-in and mouse-out methods for hotspots. It is also called by a redisplay-window method for hotspot-mixin whenever there is a hotspot under the mouse while the window is being redisplayed for any reason. The off argument will be true if and only if the call is made by mouse-out.

Here is an example of a custom highlight-hotspot method. It is used by the Navigator's hotspots example when its Custom Opaque Highlighting check-box is checked. (See the Navigator Dialog and the hotspot example titled Hotspots: mouse-active highlighting regions.)

(defmethod highlight-hotspot ((hotspot my-hotspot) &key off)
  
  ;; This is an example of a custom highlight-hotspot method
  ;; that an application might define instead of using one of
  ;; the two built-in highlighting styles.
  ;; This draws opaque highlighting rather than xoring
  ;; screen colors as the built-in styles do.
  
  ;; If we are turning the highlight off, then just invalidate
  ;; the hotspot so that the window's redisplay-window method
  ;; will be called to redraw the hotspot's region without the
  ;; hotspot highlighting.
  (if* off
     then (invalidate hotspot)
          
          ;; Otherwise draw highlighting over the top of whatever
          ;; is usually drawn in the window.
     else (let* ((window (parent hotspot))
                 (region (hotspot-region hotspot)))
            (with-background-color (window yellow)
              (with-foreground-color (window black)
                
                ;; This interprets all four kinds of hotspot-region.
                
                ;; A simple orthogonal rectangle hotspot.
                (cond ((boxp region)
                       
                       ;; Defer to the built-in highlighting for
                       ;; box hotspots.
                       (call-next-method))
                      
                      ;; A polygon hotspot.
                      ((or (vectorp region)
                           (cddr region))
                       
                       ;; These "erase" functions really draw,
                       ;; but in the current background color.
                       ;; So fill with the background color.
                       (erase-contents-polygon window region)

                       ;; And outline in the foreground color.
                       (draw-polygon window region))
                      
                      ;; A circle hotspot.
                      ((integerp (second region))
                       (erase-contents-circle window (first region)
                                              (second region))
                       (draw-circle window (first region)
                                    (second region)))
                      
                      ;; A line hotspot.
                      ;; Use with-clipping-box here to prevent this
                      ;; thick line from extending outside the
                      ;; region-box that will be erased by a simple
                      ;; call to invalidate on the hotspot.
                      (t (with-clipping-box (window (region-box region))
                           (with-line-width (window 10)
                             (with-foreground-color (window blue)
                               (draw-line window (first region)
                                          (second region))))))))))))

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