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

// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CHROME_BROWSER_UI_COCOA_PANELS_MOUSE_DRAG_CONTROLLER_H_
#define CHROME_BROWSER_UI_COCOA_PANELS_MOUSE_DRAG_CONTROLLER_H_

#import <Cocoa/Cocoa.h>

// When Drag is cancelled by hitting ESC key, we may still receive
// the mouseDragged events but should ignore them until the mouse button is
// released. Use these simple states to track this condition.
enum PanelDragState {
  PANEL_DRAG_CAN_START,  // Mouse key went down, drag may be started.
  PANEL_DRAG_IN_PROGRESS,
  PANEL_DRAG_SUPPRESSED  // Ignore drag events until PANEL_DRAG_CAN_START.
};

@class MouseDragController;

@protocol MouseDragControllerClient
// Called on initial mouseDown. Followed by dragStarted/dragProgress/dragEnded
// (which can be skipped if the drag didn't start) and then by cleanupAfterDrag.
- (void)prepareForDrag;

// Called wehen drag threshold was exceeded and actual drag should start.
// Note that the drag is processed using a local nested message loop.
// |initialMouseLocation| is in containing NSWindow's coordinates.
- (void)dragStarted:(NSPoint)initialMouseLocation;

// Called 0 to multiple times between dragStarted and dragEnded, to report
// current mouse location. |mouseLocation| is in window coordinates.
- (void)dragProgress:(NSPoint)mouseLocation;

- (void)dragEnded:(BOOL)cancelled;

// Always complements prepareForDrag. Clients which create a MouseDragController
// in their mouseDown may release it in this method.
- (void)cleanupAfterDrag;
@end

// This class encapsulates the mouse drag start/progress/termination logic,
// including having a threashold before actually starting a drag and termination
// of the drag on ESC, mouseUp and other operations. It also hosts the nested
// message loop that is used during the drag operation.
//
// The client of the controller should be a NSView implementing
// MouseDragControllerClient protocol. The client simply delegates mouse events
// to the controller, and controller invokes higher-level
// dragStarted/dragProgress/dragEnded callbacks on the client.
// The controller can be created in initial mouseDown and then released in the
// cleanupAfterDrag callback, or it can be preallocated and used across multiple
// drag operations.
//
// The pattern of usage:
// Lets say MyView is a NSView <MouseDragControllerClient>
//
// First, create an instance of MouseDragController and init it:
//     dragController_.reset([[MouseDragController alloc] initWithClient:self]);
// then delegate mouse messages to it:
//
// - (void)mouseDown:(NSEvent*)event {
//   if (needToStartADrag(event))
//     [dragController_ mouseDown:event];
// }
//
// - (void)mouseDragged:(NSEvent*)event {
//   [dragController_ mouseDragged:event];
// }
//
// - (void)mouseUp:(NSEvent*)event {
//   [dragController_ mouseUp:event];
// }
//
// That's it. When user starts a drag, the client's callbacks will be invoked.

@interface MouseDragController : NSObject {
 @private
   NSPoint initialMouseLocation_;  // In NSWindow's coordinate system.
   PanelDragState dragState_;
   NSView<MouseDragControllerClient>* client_;  // Weak, owns this object.
};

- (MouseDragController*)
    initWithClient:(NSView<MouseDragControllerClient>*)client;

// Accessors.
- (NSView<MouseDragControllerClient>*)client;
- (NSPoint)initialMouseLocation;

// These should be called from corresponding methods of hosting NSView.
- (void)mouseDown:(NSEvent*)event;
- (void)mouseDragged:(NSEvent*)event;
- (void)mouseUp:(NSEvent*)event;
@end

#endif  // CHROME_BROWSER_UI_COCOA_PANELS_MOUSE_DRAG_CONTROLLER_H_