1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef CHROME_BROWSER_UI_COCOA_PANELS_MOUSE_DRAG_CONTROLLER_H_ 6 #define CHROME_BROWSER_UI_COCOA_PANELS_MOUSE_DRAG_CONTROLLER_H_ 7 8 #import <Cocoa/Cocoa.h> 9 10 // When Drag is cancelled by hitting ESC key, we may still receive 11 // the mouseDragged events but should ignore them until the mouse button is 12 // released. Use these simple states to track this condition. 13 enum PanelDragState { 14 PANEL_DRAG_CAN_START, // Mouse key went down, drag may be started. 15 PANEL_DRAG_IN_PROGRESS, 16 PANEL_DRAG_SUPPRESSED // Ignore drag events until PANEL_DRAG_CAN_START. 17 }; 18 19 @class MouseDragController; 20 21 @protocol MouseDragControllerClient 22 // Called on initial mouseDown. Followed by dragStarted/dragProgress/dragEnded 23 // (which can be skipped if the drag didn't start) and then by cleanupAfterDrag. 24 - (void)prepareForDrag; 25 26 // Called wehen drag threshold was exceeded and actual drag should start. 27 // Note that the drag is processed using a local nested message loop. 28 // |initialMouseLocation| is in containing NSWindow's coordinates. 29 - (void)dragStarted:(NSPoint)initialMouseLocation; 30 31 // Called 0 to multiple times between dragStarted and dragEnded, to report 32 // current mouse location. |mouseLocation| is in window coordinates. 33 - (void)dragProgress:(NSPoint)mouseLocation; 34 35 - (void)dragEnded:(BOOL)cancelled; 36 37 // Always complements prepareForDrag. Clients which create a MouseDragController 38 // in their mouseDown may release it in this method. 39 - (void)cleanupAfterDrag; 40 @end 41 42 // This class encapsulates the mouse drag start/progress/termination logic, 43 // including having a threashold before actually starting a drag and termination 44 // of the drag on ESC, mouseUp and other operations. It also hosts the nested 45 // message loop that is used during the drag operation. 46 // 47 // The client of the controller should be a NSView implementing 48 // MouseDragControllerClient protocol. The client simply delegates mouse events 49 // to the controller, and controller invokes higher-level 50 // dragStarted/dragProgress/dragEnded callbacks on the client. 51 // The controller can be created in initial mouseDown and then released in the 52 // cleanupAfterDrag callback, or it can be preallocated and used across multiple 53 // drag operations. 54 // 55 // The pattern of usage: 56 // Lets say MyView is a NSView <MouseDragControllerClient> 57 // 58 // First, create an instance of MouseDragController and init it: 59 // dragController_.reset([[MouseDragController alloc] initWithClient:self]); 60 // then delegate mouse messages to it: 61 // 62 // - (void)mouseDown:(NSEvent*)event { 63 // if (needToStartADrag(event)) 64 // [dragController_ mouseDown:event]; 65 // } 66 // 67 // - (void)mouseDragged:(NSEvent*)event { 68 // [dragController_ mouseDragged:event]; 69 // } 70 // 71 // - (void)mouseUp:(NSEvent*)event { 72 // [dragController_ mouseUp:event]; 73 // } 74 // 75 // That's it. When user starts a drag, the client's callbacks will be invoked. 76 77 @interface MouseDragController : NSObject { 78 @private 79 NSPoint initialMouseLocation_; // In NSWindow's coordinate system. 80 PanelDragState dragState_; 81 NSView<MouseDragControllerClient>* client_; // Weak, owns this object. 82 }; 83 84 - (MouseDragController*) 85 initWithClient:(NSView<MouseDragControllerClient>*)client; 86 87 // Accessors. 88 - (NSView<MouseDragControllerClient>*)client; 89 - (NSPoint)initialMouseLocation; 90 91 // These should be called from corresponding methods of hosting NSView. 92 - (void)mouseDown:(NSEvent*)event; 93 - (void)mouseDragged:(NSEvent*)event; 94 - (void)mouseUp:(NSEvent*)event; 95 @end 96 97 #endif // CHROME_BROWSER_UI_COCOA_PANELS_MOUSE_DRAG_CONTROLLER_H_ 98
