hotspot

The class of a hotspot object. Hotspots are invisible regions on a window that can receive and respond to mouse events just as actual windows do. They can be used to overlay images drawn on a window in order to make the images behave as graphical objects without using a separate child window that would obscure overlapping images on the main window.

The mouse-in, mouse-out, and various mouse click methods such as mouse-left-down are invoked for hotspot instances just as it is for windows. If you define mouse click methods for hotspots, the methods should return nil if you want the click to be further processed by the hotspot's parent window, or non-nil to prevent further processing of the click by the window.

General steps for using hotspots

• Define a subclass of basic-pane (or one of its subclasses) that has hotspot-mixin as another superclass. (It is best to specify hotspot-mixin as the first superclass, so that its methods will take precedence over those of the parent window class.) Instances of this window class may contain hotspots. For example: (defclass my-hotspot-window (hotspot-mixin frame-window)())
• Define a subclass of the hotspot class so that you can specialize methods for your hotspots only.
• Write methods that specialize on your hotspot subclass to control how your hotspots respond to the mouse. Methods may be added to mouse-in, mouse-out, mouse-left-down, mouse-left-up, mouse-middle-down, mouse-middle-up, mouse-right-down, mouse-right-up, and/or mouse-double-click. (There are built-in mouse-in and mouse-out methods specializing on hotspot that call highlight-hotspot, so do not override these methods unless you want to bypass highlight-hotspot.)
• Create a window for hotspots by calling make-window on your hotspot-mixin subclass. Create hotspot instances by calling make-instance on your hotspot subclass, and add the instances to the window by calling add-hotspot.

A hotspot's highlight-style may optionally be set to :invert or :outline to make the hotspot highlight itself whenever the mouse is inside its hotspot-region. If these two built-in highlight styles are not adequate, you can override the default highlight-hotspot method to highlight the hotspot however you like.

Other than highlighting themselves when under the mouse cursor, hotspots do not draw anything on their parent window. Typically a hotspot covers the same region where something is drawn, allowing the user to click on that thing. But since an application could draw any sort of graphic where the hotspot lies, the hotspot does not attempt to do this drawing itself; instead, the window's redisplay-window method should draw the "real" object that the hotspot is making active. For a polygon hotspot, for example, the redisplay-window method could pass the same vector of positions to draw-polygon to draw the "real" polygon as the corresponding hotspot uses to define its hotspot-region.

Here are some other properties that hotspots can be given, either by passing the keyword initarg such as :name to make-instance, or by calling the setf function such as (setf name) any time later.

• name - a symbol that allows you to identify a hotspot programmatically.
• color - the color in which to draw the hotspot's highlighting.
• cursor - the mouse cursor to use when the mouse is over the hotspot.
• available - whether the hotspot is currently active. (Or call remove-hotspot to remove the hotspot completely.)
• help-string: an arbitrary string to provide information about this hotspot to the user.
• show-help-string-under-mouse: whether to display the help-string automatically when the mouse cursor is over the hotspot.
• plist - a property list where arbitrary attributes of a hotspot could be hung.

The function hotspots returns a list of all of the hotspots that are currently on a window, and current-hotspot returns the one that is currently under the mouse, if any. Calling parent on a hotspot returns the window that it is on, if any.

The IDE's Navigator Dialog includes a complete example of using hotspots. Look for Hotspots: mouse-active highlighting regions.

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.