chrome/browser/ui/cocoa/panels/mouse_drag_controller.h

   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_