sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/desktop/protocols/drag_source.js

@@ -0,0 +1,81 @@
+// ========================================================================
+// SproutCore -- JavaScript Application Framework
+// Copyright ©2006-2008, Sprout Systems, Inc. and contributors.
+// Portions copyright ©2008 Apple, Inc.  All rights reserved.
+// ========================================================================
+
+require('system/drag') ;
+
+/**
+  @mixin
+
+  The DragSource protocol is used to dynamically generate multiple types of
+  data from a single object.  You must implement this protocol if you want to
+  provide the data for a drag event.
+
+*/
+SC.DragSource = {
+
+  /**
+    This method must be overridden for drag operations to be allowed. 
+    Return a bitwise OR'd mask of the drag operations allowed on the
+    specified target.  If you don't care about the target, just return a
+    constant value.
+  
+    @param {SC.View} dropTarget The proposed target of the drop.
+    @param {SC.Drag} drag The SC.Drag instance managing this drag.
+  
+  */
+  dragSourceOperationMaskFor: function(drag, dropTarget) { return SC.DRAG_NONE ; },
+  
+  /**
+    If this property is set to NO or is not implemented, then the user may
+    modify the drag operation by changing the modifier keys they have 
+    pressed.
+    
+    @returns {Boolean}
+  */
+  ignoreModifierKeysWhileDragging: NO,
+    
+  /**  
+    This method is called when the drag begins. You can use this to do any
+    visual highlighting to indicate that the receiver is the source of the 
+    drag.
+  
+    @param {SC.Drag} drag The Drag instance managing this drag.
+  
+    @param {Point} loc The point in *window* coordinates where the drag 
+      began.  You can use convertOffsetFromView() to convert this to local 
+      coordinates.
+  */
+  dragDidBegin: function(drag, loc) {},
+  
+  /**
+    This method is called whenever the drag image is moved.  This is
+    similar to the dragUpdated() method called on drop targets.
+
+    @param {SC.Drag} drag The Drag instance managing this drag.
+
+    @param {Point} loc  The point in *window* coordinates where the drag 
+      mouse is.  You can use convertOffsetFromView() to convert this to local 
+      coordinates.
+  */
+  dragDidMove: function(drag, loc) {},
+  
+  /**  
+    This method is called when the drag ended. You can use this to do any
+    cleanup.  The operation is the actual operation performed on the drag.
+  
+    @param {SC.Drag} drag The drag instance managing the drag.
+  
+    @param {Point} loc The point in WINDOW coordinates where the drag 
+      ended. 
+  
+    @param {DragOp} op The drag operation that was performed. One of 
+      SC.DRAG_COPY, SC.DRAG_MOVE, SC.DRAG_LINK, or SC.DRAG_NONE.
+  
+  */
+  dragDidEnd: function(drag, loc, op) {}
+  
+} ;
+

data/frameworks/sproutcore/frameworks/desktop/protocols/drop_target.js

@@ -0,0 +1,175 @@
+// ========================================================================
+// SproutCore -- JavaScript Application Framework
+// Copyright ©2006-2008, Sprout Systems, Inc. and contributors.
+// Portions copyright ©2008 Apple, Inc.  All rights reserved.
+// ========================================================================
+
+require('system/drag');
+
+/**
+  @mixin
+  
+  Add the DropTarget mixin to your view to be able to accept drop events. You 
+  should also override the methods below as needed to handle accepting of events.
+  
+  See the method descriptions for more information on what you need to implement.
+  
+  The general call sequence for all drop targets is (in pseudo-Ragel, regex
+  format):
+  
+  dragStarted
+  (
+    computeDragOperations+
+    (
+      dragEntered
+      dragUpdated
+      ( computeDragOperations | dragUpdated )*
+      ( acceptDragOperation performDragOperation? )? // mouseUp
+      dragExited
+    )*
+  )*
+  dragEnded
+  
+  Thus, every drop target will have its dragStarted and dragEnded methods called 
+  once during every drag session. computeDragOperations, if called at all, may be 
+  called more than once before the dragEntered method is called. Once dragEntered 
+  is called, you are at guaranteed that both dragUpdated and dragExited will be 
+  called at some point, followed by either dragEnded or additonal 
+  computeDragOperation calls.
+*/
+SC.DropTarget = {
+  
+  /**
+    Must be true when your view is instantiated.
+    
+    Drop targets must be specially registered in order to receive drop
+    events.  SproutCore knows to register your view when this property
+    is true on view creation.
+  */  
+  isDropTarget: true,
+  
+  /**
+    Called when the drag is started, regardless of where or not your drop
+    target is current. You can use this to highlight your drop target
+    as "eligible".
+    
+    The default implementation does nothing.
+    
+    @param {SC.Drag} drag The current drag object.
+    @param {SC.Event}   evt  The most recent mouse move event.  Use to get location 
+  */
+  dragStarted: function(drag, evt) {},
+  
+  /**
+    Called when the drag first enters the droppable area, if it returns a
+    drag operations other than SC.DRAG_NONE.
+    
+    The default implementation does nothing.
+    
+    @param drag {SC.Drag} The current drag object.
+    @param evt {SC.Event} The most recent mouse move event.  Use to get location
+  */
+  dragEntered: function(drag, evt) {},
+  
+  /**
+    Called periodically when a drag is over your droppable area.
+    
+    Override this method this to update various elements of the drag state, 
+    including the location of ghost view.  You should  use this method to 
+    implement snapping.
+    
+    This method will be called periodically, even if the user is not moving
+    the drag.  If you perform expensive operations, be sure to check the
+    mouseLocation property of the drag to determine if you actually need to
+    update anything before doing your expensive work.
+    
+    The default implementation does nothing.
+    
+    @param {SC.Drag} drag The current drag object.
+    @param {SC.Event} evt The most recent mouse move event. Use to get location
+  */
+  dragUpdated: function(drag, evt) {},
+  
+  /**
+    Called when the user exists your droppable area or the drag ends
+    and you were the last targeted droppable area.
+    
+    Override this method to perform any clean up on your UI such as hiding 
+    a special highlight state or removing insertion points.
+    
+    The default implementation does nothing.
+    
+    @param {SC.Drag} drag The current drag object
+    @param {SC.Event}   evt  The most recent mouse move event. Use to get location.
+  */
+  dragExited: function(drag, evt) {},
+  
+  /**
+    Called on all drop targets when the drag ends.  
+    
+    For example, the user might have dragged the view off the screen and let go
+    or they might have hit escape.  Override this method to perform any final
+    cleanup.  This will be called instead of dragExited.
+    
+    The default implementation does nothing.
+    
+    @param {SC.Drag} drag The current drag object
+    @param {SC.Event}   evt  The most recent mouse move event. Use to get location.
+  */
+  dragEnded: function(drag, evt) {},
+  
+  /**
+    Called when the drag needs to determine which drag operations are
+    valid in a given area.
+    
+    Override this method to return an OR'd mask of the allowed drag 
+    operations.  If the user drags over a droppable area within another 
+    droppable area, the drag will latch onto the deepest view that returns one 
+    or more available operations.
+    
+    The default implementation returns SC.DRAG_NONE
+    
+    @param {SC.Drag} drag The current drag object
+    @param {SC.Event} evt The most recent mouse move event.  Use to get 
+      location 
+    @returns {DragOps} A mask of all the drag operations allowed or 
+      SC.DRAG_NONE
+  */
+  computeDragOperations: function(drag, evt) { return SC.DRAG_NONE; },
+  
+  /**
+    Called when the user releases the mouse.
+    
+    This method gives your drop target one last opportunity to choose to 
+    accept the proposed drop operation.  You might use this method to
+    perform fine-grained checks on the drop location, for example.
+    Return true to accept the drop operation.
+    
+    The default implementation returns YES.
+    
+    @param {SC.Drag} drag The drag instance managing this drag
+    @param {DragOp} op The proposed drag operation. A drag constant
+    
+    @return {Boolean} YES if operation is OK, NO to cancel.
+  */  
+  acceptDragOperation: function(drag, op) { return YES; },
+  
+  /**
+    Called to actually perform the drag operation.
+    
+    Overide this method to actually perform the drag operation.  This method
+    is only called if you returned YES in acceptDragOperation(). 
+    
+    Return the operation that was actually performed or SC.DRAG_NONE if the 
+    operation was aborted.
+    
+    The default implementation returns SC.DRAG_NONE
+    
+    @param {SC.Drag} drag The drag instance managing this drag
+    @param {DragOp} op The proposed drag operation. A drag constant.
+    
+    @return {DragOp} Drag Operation actually performed
+  */
+  performDragOperation: function(drag, op) { return SC.DRAG_NONE; }
+  
+};

data/frameworks/sproutcore/frameworks/desktop/protocols/responder.js

@@ -0,0 +1,280 @@
+// ========================================================================
+// SproutCore -- JavaScript Application Framework
+// Copyright ©2006-2008, Sprout Systems, Inc. and contributors.
+// Portions copyright ©2008 Apple, Inc.  All rights reserved.
+// ========================================================================
+
+/** @static
+
+  This protocol defines the allowable responder methods. To implement a 
+  specific responder method, and a method with the correct signature to your
+  class.
+  
+  DO NOT INCLUDE THIS MIXIN.
+  
+  If you try and include this mixin, an error will be raised on startup.
+  
+  @author Erich Ocean
+  @since SproutCore 1.0
+*/
+SC.ResponderProtocol = {
+  
+  // .......................................................................
+  // Mouse Event Handlers
+  //
+  
+  /**
+    Called when the mouse is pressed. You must return YES to recieve 
+    mouseDragged and mouseUp in the future.
+    
+    @param evt {SC.Event} the mousedown event
+    @returns {Boolean} YES to receive additional mouse events, NO otherwise
+  */
+  mouseDown: function(evt) {},
+  
+  /**
+    Called when the mouse is released.
+    
+    @param evt {SC.Event} the mouseup event
+    @returns {Boolean} YES to handle the mouseUp, NO to allow click() and doubleClick() to be called
+  */
+  mouseUp: function(evt) {},
+  
+  /**
+    Called when the mouse is dragged, after responding YES to a previous mouseDown:
+    call.
+    
+    @param evt {SC.Event} the mousemove event
+    @returns {void}
+  */
+  mouseDragged: function(evt) {},
+  
+  /**
+    Called when the mouse exits the view and the root responder is not in a
+    drag session.
+    
+    @param evt {SC.Event} the mousemove event
+    @returns {void}
+  */
+  mouseOut: function(evt) {},
+  
+  /**
+    Called when the mouse enters the view and the root responder is not in a
+    drag session.
+    
+    @param evt {SC.Event} the mousemove event
+    @returns {void}
+  */
+  mouseOver: function(evt) {},
+  
+  /**
+    Called when the mouse moves within the view and the root responder is not in a
+    drag session.
+    
+    @param evt {SC.Event} the mousemove event
+    @returns {void}
+  */
+  mouseMoved: function(evt) {},
+  
+  // .......................................................................
+  // Event Handlers
+  //
+  // These methods are called by the input manager in response to keyboard
+  // events.  Most of these methods are defined here for you, but not actually
+  // implemented in code.
+  
+  /**
+    Insert the text or act on the key.
+    
+    @param {String} the text to insert or respond to
+    @returns {Boolean} YES if you handled the method; NO otherwise
+  */
+  insertText: function(text) {},
+  
+  /**
+    When the user presses a key-combination event, this will be called so you
+    can run the command.
+    
+    @param charCode {String} the character code
+    @param evt {SC.Event} the keydown event
+    @returns {Boolean} YES if you handled th emethod; NO otherwise
+  */
+  performKeyEquivalent: function(charCode, evt) { return false; },
+  
+  /**
+    This method is called if no other view in the current view hierarchy is
+    bound to the escape or command-. key equivalent.  You can use this to 
+    cancel whatever operation is running.
+    
+    @param sender {Object} the object that triggered; may be null
+    @param evt {SC.Event} the event that triggered the method
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  cancel: function(sender, evt) {},
+  
+  /**
+    Delete the current selection or delete one element backward from the
+    current selection.
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  deleteBackward: function(sender, evt) {},
+  
+  /**
+    Delete the current selection or delete one element forward from the
+    current selection.
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  deleteForward: function(sender, evt) {},
+  
+  /**
+    A field editor might respond by selecting the field before it.
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  insertBacktab: function(sender, evt) {},
+  
+  /**
+    Insert a newline character or end editing of the receiver.
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  insertNewline: function(sender, evt) {},
+  
+  /**
+    Insert a tab or move forward to the next field.
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  insertTab: function(sender, evt) {},
+  
+  /**
+    Move insertion point/selection backward one. (i.e. left arrow key)
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveLeft: function(sender, evt) {},
+  
+  /**
+    Move the insertion point/selection forward one (i.e. right arrow key)
+    in left-to-right text, this could be the left arrow key.
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveRight: function(sender, evt) {},
+  
+  /**
+    Move the insertion point/selection up one (i.e. up arrow key)
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveUp: function(sender, evt) {},
+  
+  /**
+    Move the insertion point/selection down one (i.e. down arrow key)
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveDown: function(sender, evt) {},
+  
+  /**
+    Move left, extending the selection. - shift || alt
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveLeftAndModifySelection: function(sender, evt) {},
+  
+  /**
+    Move right, extending the seleciton - shift || alt
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveRightAndModifySelection: function(sender, evt) {},
+  
+  /**
+    Move up, extending the selection - shift || alt
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveUpAndModifySelection: function(sender, evt) {},
+  
+  /**
+    Move down, extending selection - shift || alt
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveDownAndModifySelection: function(sender, evt) {},
+  
+  /**
+    Move insertion point/selection to beginning of document.
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveToBeginningOfDocument: function(sender, evt) {},
+  
+  /**
+    Move insertion point/selection to end of document.
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  moveToEndOfDocument: function(sender, evt) {},
+  
+  /**
+    Page down
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  pageDown: function(sender, evt) {},
+  
+  /**
+    Page up
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  pageUp: function(sender, evt) {},
+  
+  /**
+    Select all
+    
+    @param sender {Object} the object that triggered the method; may be null
+    @param evt {SC.Event} the event that triggered the method; may be null
+    @returns {Boolean} YES if you handle the event; NO otherwise
+  */
+  selectAll: function(sender, evt) {}
+  
+};