CHAPTER 8 TAMING THE MOUSE By Gipson Masayi With a few modifications by Jim Fawcett Summer 2003

A Mouse is: a pointing device with one or more buttons the object that sits on your desk. when you move the mouse, the Windows environment moves a small bitmap image called a mouse cursor on the screen The mouse cursor has a hot spot that corresponds to a precise pixel location on the screen

You can click, drag or double-click a mouse -For an action to qualify as a double-click, both clicks must occur within a set period of time and with the mouse cursor in approximately the same location on the screen. SystemInformation class contains two static read-only properties with this information. Type Property Accessibility Description int DoubleClickTime get Time in milliseconds Size DoubleClickSize get Area in pixels

Information About the Mouse A Windows Forms program may determine whether a mouse is present and, if so, how many buttons it has. SystemInformation class contains the information below: Type Property Accessibility Description bool MousePresent get Indicates whether a mouse is installed int MouseButtons get Indicates the number of buttons on the mouse bool MouseButtonsSwapped get Indicates whether buttons are swapped The left button is the primary button. The right mouse button is mainly used to invoke context menus.

The Mouse Wheel SystemInformation returns the following information about the mouse wheel: Type Property Accessibility Description bool MouseWheelPresent get Returns true if the wheel is present int MouseWheelScrollLines get Number of lines to scroll per turn bool NativeMouseWheelSupport get Not important to applications

The mouse wheel has a definite notched, or clicked feel when turned The mouse wheel has a definite notched, or clicked feel when turned. To ensure that application respond to the mouse wheel consistently, each notch (called detent in the .Net Framework documentation) is supposed to correspond to a certain number of text lines that the application scrolls through the document. MouseWheelScrollLines property indicates that number of lines. The property currently returns 3 for the Microsoft IntelliMouse.

Mouse Events Mouse activity is communicated to a Windows Forms application in the form of events. The Control class defines nine mouse events nine corresponding protected methods; Any class descended from Control also inherits these nine methods. Only one control receives any particular mouse event; when it is both enabled and visible, i.e., when both the Enabled and Visible properties are set to true. Usually, mouse events are received by the control directly underneath the mouse cursor. If a child control is enabled and visible, and you pass a mouse over it, it will receive the mouse events rather than the parent control

Any object derived or instantiated from Form receives mouse events only when the mouse is positioned over the form’s client area. The Form object does not receive mouse events when the cursor is positioned over the form’s border, caption bar, control box, minimize box, maximize box, close box, menu or scroll bars. The window does receive them, but the form control does not get them. Under some circumstances a control or form receives mouse events when the mouse cursor is not positioned over the control. This feature is called mouse capturing. It assists forms and controls in tracking mouse movement. We will look at it later.

Here are the four basic mouse events: Control Events Event Method Delegate Argument MouseDown OnMouseDown MouseEventHandler MouseEventArgs MouseUp OnMouseUp MouseEventHandler MouseEventArgs MouseMove OnMouseMove MouseEventHandler MouseEventArgs MouseWheel OnMouseWheel MouseEventHandler MouseEventArgs MouseDown and MouseUp events indicate a button being pressed or released. The MouseMove event signals mouse movement, and the MouseWheel event occurs when the user rolls the mouse wheel.

MouseEventArgs properties Type property Accessibility Description The four events are associated with objects of type MouseEvenArgs. The MouseEventArgs has five read-only properties: MouseEventArgs properties Type property Accessibility Description int X get The horizontal position of the mouse int Y get The vertical position of the mouse MouseButtons Button get The mouse button or buttons int Clicks get Returns 2 for a double-click int Delta get Mouse wheel movement

The Button property is a MouseButtons enumeration value: The Buttons property indicates the mouse button or buttons involved in the event. This property isn’t valid for MouseWheel events. The Button property is a MouseButtons enumeration value: MouseButtons Enumeration Member Value None 0x00000000 Left 0x00100000 Right 0x00200000 Middle 0x00400000 XButton1 0x00800000 XButton2 0x01000000

If the MouseEventArgs object is named mea XButton1 and XButton2 refer to buttons in the IntelliMouse Explorer, which has five buttons. For MouseDown and MouseUp events, the Button property indicates the particular button being pressed or released. For MouseMove events, the Button property indicates which button or buttons are currently pressed. Note that if both the left and right buttons are pressed, the Button property equals 0x00300000. If the MouseEventArgs object is named mea (mea.Button = = MouseButtons.Right) will return true iff the right mouse button is pressed. (mea.Button & MouseButtons.Right != 0) is true if the right mouse button is pressed, regardless of the other mouse buttons.

The Click property is valid only for MouseDown events and is normally set to 1. The property is set to 2 if the MouseDown follows a previous MouseDown event quickly enough to qualify for a double-click. The Delta property is valid for MouseWheel events. The property will equal 120 of you roll the wheel forward one click, and it will equal –120 if you roll the wheel back one click.

The Wheel When you get a MouseWheel event, you calculate the number of text lines to scroll like so: mea.Delta*SystemInformation.MouseWheelScrollLines / 120 Currently, this calculation yields 3 or -3. PoePoem.cs demonstrates how to use the mouse wheel by displaying (and scrolling) Edgar Allan Poe’s creepy poem “Annabel Lee”.

Mouse Movement Lets look at the MouseMove event. MouseWeb.cs overrides the OnMouseMove method to draw a web that connects the current mouse position with the corners and sides of the client area. The screen looks like this:

Tracking and Capturing the Mouse When a mouse needs to draw something or move something in response to mouse movement, it uses a technique called mouse tracking. Mouse tracking begins when a mouse button is pressed and ends when the button is released. MouseConnect.cs demonstrates some rudimentary mouse cursor tracking. Here is a screen view for the program:

The capture ends when the user releases the mouse button. When you press any mouse button on a control, or in a form’s client area, the control or form captures the mouse and forces each subsequent mouse event to be sent to itself. The capture ends when the user releases the mouse button. Mouse capture is a prerequisite for tracking the mouse, and it is automatically provided for you. A bool property for the Control class indicates when the mouse is captured: Control Properties Type property Accessibility bool Capture get/set

Tracking For more adventures in mouse tracking, check out the following files, and read the book too: BlockOut.cs lets you drag the mouse and to draw a rectangle. BetterBlockOut.cs is a better version of BlockOut.cs. CaptureLoss.cs demonstrates how to use the the NativeWindow class to implement a handler that sends a message to the form when the form loses it’s mouse capture. CaptureLossNotifyWindow.cs demonstrates how implement the general form of the handler using an interface and EvenBetterBlockOut.cs uses the interface to do the same job as CaptureLoss.cs

Clicks and Double-Clicks Below are the two highest-level mouse events: Control Events Event Method Delegate Argument Click OnClick EventHandler EventArgs DoubleClick OnDoubleClick EventHandler EventArgs EventArgs argument doesn’t give you any information specific to the mouse. Here is a typical sequence of events of a double-click. - MouseDown (Clicks property set to 1) - Click - MouseUp - MouseMove - MouseDown (Clicks property set to 2) - DoubleClick

Mouse Related Properties The Control class supports two read-only static properties that indicate the position of the mouse and which button is currently pressed: Control Static Properties Type Property Accessibility Description Point MousePosition get Returns the position of the mouse in screen coordinates MouseButtons MouseButtons get Returns which buttons are currently pressed Note that the Control.MousePosition property gives position in screen coordinates. You can use PointToClient to convert screen coordinates to client area coordinates

Entering, Leaving, Hovering Here are the final three mouse events: Control Events Event Method Delegate Argument MouseEnter OnMouseEnter EventHandler EventArgs MouseLeave OnMouseLeave EventHandler EventArgs MouseHover OnMouseHover EventHandler EventArgs The MouseHover event occurs after the mouse has entered the control and has stopped moving. The event occurs at most once between MouseEnter and MouseLeave events. EnterLeave.cs provides a visual indication of these three events.

Mouse Cursor The mouse cursor is an object of type Cursor, a class defined in System.Windows.Forms namespace. You can get a cursor by using the Cursors Class. The Cursors class consists of 28 static read-only properties that return predefined objects of type Cursor: Cursor Static Read-Only Properties AppStarting PanNorth NoMoveVert Arrow PanNW NoMoveHoriz Cross PanSE PanEast Default PanSouth PanNE Hand PanSW UpArrow Help PanWest VSplit HSplit SizeAll WaitCursor IBeam SizeNESW SizeWE No SizeNS NoMove2D SizeNWSE

Cursor Static Properties Three other useful static properties of the Cursor class are: Cursor Static Properties Type Property Accessibility Cursor Current get/set Point Position get/set Rectangle Clip get/set You can set the current mouse cursor by using Cursor.Current property, e.g., Cursor.Current = Cursors.WaitCursor If the user is running Windows without a mouse installed, the cursor won’t be visible. To display the mouse cursor all the time, a program can make use of the two static methods of Cursor class: Cursor Static Methods Void Show() Void Hide()

MouseCursors. cs uses a call to Cursor MouseCursors.cs uses a call to Cursor.Current during the OnMouseMove call to let you see what all 28 predefined cursors look like. If your form does not set Cursor.Current during during the MouseMove event, the cursor will be set to the normal cursor associated with the form during that event. You cannot set Cursor.Current during the constructor or an OnMouseDown event or some other event because as soon as the program gets a call to OnMouseMove, the cursor will be reset. You can however assign a cursor to a control once by using the Cursor property defined in the Control class. Control Property Type Property Accessibility Cursor Cursor get/set For example, in the form’s constructor, you can call: Cursor = Cursors.Hand; and the cursor will be a hand whenever you pass the mouse over the form’s client area.

Hit-Testing When you draw graphic figures or text on your form, you determine the coordinates of each item and call the appropriate method to draw it. Often, however, a program uses a mouse interface to allow a user to point to and manipulate these items. That is, the program uses pointer coordinates to determine which graphical item the mouse is pointing to. This process is called hit-testing. Checker.cs draws an array of boxes covering its client area. If you click one of these boxes, it is filled with an X. If you click it again, the X disappears. Here is the program display:

Adding a Keyboard Interface CheckerWithKeyboard.cs lets the user move the mouse cursor around the client area using arrow keys and other cursor movement keys. Mouse clicks are simulated by Enter key and the space bar. The CheckerWithKeyboard class subclasses Checker and provides a keyboard interface.

Scribbling with the Mouse Scribble.cs is a simple program that allows the user to scribble on the client area. Below is a snapshot: The program does not retain the mouse positions it used to draw the lines. If the client needs repainting, its out of luck.

ScribbleWithSave.cs takes care of the problem. It uses the ArrayList class defined in the Systems.Collections namespace which also includes Queue, Stack, SortedList, and Hashtable to save all the points. ArrayList is like a single-dimension array that expands itself when necessary. You create a new ArrayList object like so: ArrayList arrlst = new ArrayList(); //default capacity is 16 You can also specify the capacity as follows: ArrayList arrlst = new ArrayList(16); You can add any object to ArrayList, e.g., to add a point; arrlst.Add(pt) You can also insert of remove items using similar methods. You can retrieve objects using an indexer like so: Point pt = (point) arrlst[3]; The cast is needed because the indexer returns an object of type Object.