mouse-wheel

Arguments: window buttons delta-major delta-minor x y

This generic function is called when the user rotates the wheel of the mouse (if it has a wheel). The default behavior is to scroll the window if possible, but an application may add mouse-wheel methods that scroll in some alternate way or interpret the gesture in some arbitrary way unrelated to scrolling. An application should not call mouse-wheel.

mouse-wheel-present may be called to determine if the end user's mouse has a wheel, though mouse-wheel will simply not be called if the mouse does not have a wheel.

When defining a mouse-wheel method to do some arbitrary non-scrolling operation, the window should have no scrollbars. The reason is that if the operating system sees that the wheel message handler (the mouse-wheel function in Common Graphics) could have scrolled the window in the requested direction but did not, then the Operating System sends scroll messages to scroll the window. So there is no way to override the operating system's scrolling behavior for the wheel if either scrollbar is given to the window.

The default method passes the message back to the Operating System, which then scrolls the window vertically if it has a vertical scrollbar, or else horizontally if it has a horizontal scrollbar, and otherwise passes the wheel message to the parent window (if any), resulting in mouse-wheel being called on the parent window. The Operating System will scroll the window by calling user-scroll a number of times for each notch that the wheel was rotated, specifying a :char scroll to scroll by one line-height or character-width each time. The number of times that user-scroll will be called for each notch is equal to the value returned by mouse-wheel-scroll-lines. (If the user has set the mouse wheel to do page scrolls in Control Panel, then user-scroll will instead be called once to do a page scroll.)

The arguments are:

• buttons works as in mouse-left-down. In addition, certain mice such as the MicroSoft IntelliMouse that have extra buttons may pass the first-x-button or second-x-button bits when these buttons are down.
• delta-major is an integer denoting how many notches the user rotated the wheel. Positive values indicate pulling the wheel backward (equivalent to dragging a scrollbar downward or rightward) and negative values indicate pushing the wheel forward (equivalent to dragging a scrollbar upward or leftward).
• delta-minor will be a float denoting a fine rotation less than a single notch if the operating system and the particular mouse wheel support it, and otherwise will be zero (an integer for backward compatibility). On Windows with a capable mouse, delta-minor will be a float that's either between 0.0 and 1.0 or between 0.0 and -1.0 (inclusive), depending on the direction. On GTK, delta-minor will always be zero.
• x is an integer indicating the pixel distance from the left edge of the screen to the current mouse cursor position.
• y is an integer indicating the pixel distance from the top edge of the screen to the current mouse cursor position.

Example:

The following is a sample mouse-wheel method that emulates the default Operating System behavior except that it scrolls the set of lines for each wheel notch (the default is 3) or entire wheel "roll" all at once rather than line one at a time as the default OS behavior does. This will more quickly scroll a window but the scrolling motion will not look as smooth. This example illustrates the various considerations that must be made when writing custom mouse wheel behavior.

(defmethod mouse-wheel ((window my-window) buttons
                        delta-major delta-minor x y)
  (declare (ignore buttons delta-minor x y))
  
  ;; This method emulates the OS behavior for scrolling with the mouse
  ;; wheel, except that it scrolls more quickly (but less smoothly)
  ;; in one step rather than scrolling each line separately.
  (let* ((scroll-lines (mouse-wheel-scroll-lines))
         (scrollbars (scrollbars window))
         (horizontal (eq scrollbars :horizontal)))
    
    ;; Avoid handling this wheel message if the user has disabled
    ;; the wheel in Control Panel or if the wheel rotation is zero.
    (unless (or (eq scroll-lines 0)    ;; Wheel disabled
                (eq delta-major 0))    ;; No actual wheel rotation
      
      ;; If a scrollbar is turned on, then this method
      ;; interprets the mouse wheel to scroll the window.
      (if* scrollbars
              
              ;; If the user has set the mouse to scroll by pages
              ;; in the Control Panel, then scroll by a page for
              ;; a wheel "roll" of any number of notches.
         then (if* (eq scroll-lines t)
                 then (user-scroll window
                                   (if* (minusp delta-major)
                                      then (if horizontal :left :up)
                                      else (if horizontal :right :down))
                                   :page)
                      
                      ;; Otherwise scroll by the number of lines
                      ;; per notch specified in Control Panel (default 3).
                      ;; Do this in one jump for a quick scroll, unlike
                      ;; the OS which would call user-scroll once for each
                      ;; line to be scrolled.
                 else (with-positions (pos1)
                        (scroll
                         window
                         (if* horizontal
                            then (nmake-position
                                     pos1
                                   (* scroll-lines
                                      delta-major
                                      (space-width window))
                                   0)
                            else (nmake-position
                                     pos1 0
                                   (* scroll-lines
                                      delta-major
                                      (line-height window)))))))
              
              ;; This window has no scrollbars, so pass this message on.
              ;; The default method will pass the message to the parent.
         else (call-next-method)))))

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.