The tracking-pointer macro provides a general means for running code while following the position of a pointing device, and monitoring for other input events. The programmer supplies code (the clauses in body) to be run upon the occurrence of any of the following types of events: [annotate]

• Motion of the pointer [annotate]
• Motion of the pointer over a presentation [annotate]
• Clicking or releasing a pointer button [annotate]
• Clicking or releasing a pointer button while the pointer is over a presentation [annotate]
• Keyboard event (typing a character) [annotate]

The sheet argument is not evaluated, and must be a symbol that is bound to an input sheet or stream. If sheet is t, *standard-output* is used. body may have zero or more declarations as its first forms. [annotate]

The pointer argument specifies a pointer to track. It defaults to the primary pointer for the sheet, (port-pointer (port sheet)). [annotate]

When the boolean multiple-windows is true, then the pointer will be tracked across multiple windows, otherwise is will be tracked only in the window corresponding to sheet. [annotate]

When the boolean transformp is true, then the coordinates supplied to the :pointer-motion clause will be in the "user" coordinate system rather than in stream coordinates, that is, the medium's transformation will be applied to the coordinates. [annotate]

context-type is used to specify the presentation type of presentations that will be "visible" to the tracking code for purposes of highlighting and for the :presentation, :presentation-button-press, and :presentation-button-release clauses. Supplying context-type is only useful when sheet is an output recording stream. context-type defaults to t, meaning that all presentations are visible. [annotate]

When highlight is true, tracking-pointer will highlight applicable presentations as the pointer is positioned over them. highlight defaults to true when any of the :presentation, :presentation-button-press, or :presentation-button-release clauses is supplied, otherwise it defaults to false. See Chapter 16 for a complete discussion of presentations. [annotate]

The body of tracking-pointer consists of a list of clauses. Each clause is of the form
(clause-keyword arglist . clause-body)
and defines a local function to be run upon occurrence of each type of event. The possible values for clause-keyword and the associated arglist are: [annotate]

• :pointer-motion (&key window x y)
  Defines a clause to run whenever the pointer moves. In the clause, window is bound to the window in which the motion occurred, and x and y to the coordinates of the pointer. (See the keyword argument :transformp below for a description of the coordinate system in which x and y are expressed.) [annotate]

• :presentation (&key presentation window x y)
  Defines a clause to run whenever the pointer moves over a presentation of the desired type. (See the keyword argument :context-type above for a description of how to specify the desired type.) In the clause, presentation is bound to the presentation, window to the window in which the motion occurred, and x and y to the coordinates of the pointer. (See the keyword argument :transformp above for a description of the coordinate system in which x and y are expressed.) [annotate]

  When both :presentation and :pointer-motion clauses are provided, the two clauses are mutually exclusive. The :presentation clause will run only if the pointer is over an applicable presentation, otherwise the :pointer-motion clause will run. [annotate]

  [annotate]

• :pointer-button-press (&key event x y)
  Defines a clause to run whenever a pointer button is pressed. In the clause, event is bound to the pointer button press event. (The window and the coordinates of the pointer are part of event.) [annotate]

  x and y are the transformed x and y positions of the pointer. These will be different from pointer-event-x and pointer-event-y if the user transformation is not the identity transformation. [annotate]

  [annotate]

• :presentation-button-press (&key presentation event x y)
  Defines a clause to run whenever the pointer button is pressed while the pointer is over a presentation of the desired type. (See the keyword argument :context-type below for a description of how to specify the desired type.) In the clause, presentation is bound to the presentation, and event to the pointer button press event. (The window and the stream coordinates of the pointer are part of event.) x and y are as for the :pointer-button-press clause. [annotate]

  When both :presentation-button-press and :pointer-button-press clauses are provided, the two clauses are mutually exclusive. The :presentation-button-press clause will run only if the pointer is over an applicable presentation, otherwise the :pointer-button-press clause will run. [annotate]

  [annotate]

• :pointer-button-release (&key event x y)
  Defines a clause to run whenever a pointer button is released. In the clause, event is bound to the pointer button release event. (The window and the coordinates of the pointer are part of event.) [annotate]

  x and y are the transformed x and y positions of the pointer. These will be different from pointer-event-x and pointer-event-y if the user transformation is not the identity transformation.

  [annotate]

• :presentation-button-release (&key presentation event x y)
  Defines a clause to run whenever a pointer button is released while the pointer is over a presentation of the desired type. (See the keyword argument :context-type below for a description of how to specify the desired type.) In the clause, presentation is bound to the presentation, and event to the pointer button release event. (The window and the stream coordinates of the pointer are part of event.) x and y are as for the :pointer-button-release clause. [annotate]

  When both :presentation-button-release and :pointer-button-release clauses are provided, the two clauses are mutually exclusive. The :presentation-button-release clause will run only if the pointer is over an applicable presentation, otherwise the :pointer-button-release clause will run. [annotate]

  [annotate]
• :keyboard (&key gesture)
  Defines a clause to run whenever a character is typed on the keyboard. In the clause, gesture is bound to the keyboard gesture corresponding to the character typed. [annotate]

[annotate]

Enters an interaction mode in which the user moves the pointer and output-record "follows" the pointer by being dragged on the output recording stream stream. By default, the dragging is accomplished by erasing the output record from its previous position and redrawing at the new position. output-record remains in the output history of stream at its final position. [annotate]

The returned values are the final x and y position of the pointer. [annotate]

The boolean repaint allows the programmer to control the appearance of windows as the pointer is dragged. If repaint is true (the default), displayed contents of windows are not disturbed as the output record is dragged over them (that is, those regions of the screen are repainted). If it is false, then no repainting is done as the output record is dragged. [annotate]

erase allows the programmer to identify a function that will be called to erase the output record as it is dragged. It must be a function of two arguments, the output record to erase and the stream; it has dynamic extent. The default is erase-output-record. [annotate]

feedback allows the programmer to identify a "feedback" function. feedback must be a is a function of seven arguments: the output record, the stream, the initial x and y position of the pointer, the current x and y position of the pointer, and a drawing argument (either :erase or :draw). It has dynamic extent. The default is nil, meaning that the feedback behavior will be for the output record to track the pointer. (The feedback argument is used when the programmer desires more complex feedback behavior, such as drawing a "rubber band" line as the user moves the mouse.) Note that if feedback is supplied, erase is ignored. [annotate]

If the boolean finish-on-release is false (the default), drag-output-record is exited when the user presses a pointer button. When it is true, drag-output-record is exited when the user releases the pointer button currently being held down. [annotate]

multiple-window is as for tracking-pointer. [annotate]

[annotate]

Evaluates body inside of with-output-to-output-record to produce an output record for the stream stream, and then invokes drag-output-record on the record in order to drag the output. The output record is not inserted into stream's output history. [annotate]

The returned values are the final x and y position of the pointer. [annotate]

The stream argument is not evaluated, and must be a symbol that is bound to an output recording stream stream. If stream is t (the default), *standard-output* is used. body may have zero or more declarations as its first forms. [annotate]

repaint, finish-on-release, and multiple-window are as for drag-output-record. [annotate]

[annotate]