1 // ==========================================================================
  2 // Project:   SproutCore
  3 // Copyright: @2013 7x7 Software, Inc.
  4 // License:   Licensed under MIT license (see license.js)
  5 // ==========================================================================
  6 
  7 
  8 /** @namespace
  9   The `SC.ViewTransitionProtocol` protocol defines the properties and methods that you may
 10   implement in your custom transition plugins. The only required method for a plugin to
 11   implement is `run`.
 12 
 13   SC.View uses transition plugins to setup, execute and cleanup the swapping between views and
 14   expects the given transition plugin object to implement this protocol.
 15 
 16   *Note: Do not mix `SC.ViewTransitionProtocol` into your classes. As a protocol, it exists only
 17   for reference sake. You only need define any of the properties or methods listed below in order to
 18   use this protocol.*
 19 */
 20 SC.ViewTransitionProtocol = {
 21 
 22   /**
 23     This optional method is called to set up the entrance transition (i.e.
 24     transitionIn or transitionShow).
 25 
 26     Use this method to adjust the layout of the view so that it may be properly
 27     animated.  For example, you may need to adjust the content from a flexible
 28     layout (i.e. { left: 0, top: 0, right: 0, bottom: 0 }) to a fixed layout
 29     (i.e. { left: 0, top: 0, width: 100, height: 200 }) so that it can be
 30     moved.
 31 
 32     @param {SC.View} view The view being transitioned.
 33     @param {Object} options Options to modify the transition.  As set by transitionShowOptions or transitionInOptions.
 34     @param {Boolean} inPlace Whether the transition should start with the current layout of the view, because a previous transition was cancelled in place.
 35   */
 36   setup: function (view, options, inPlace) {},
 37 
 38   /**
 39     This method is called to transition the view in or visible (i.e. transitionIn or
 40     transitionShow).
 41 
 42     When the transition completes, this function *must* call `didTransitionIn()`
 43     on the view, passing this object and the original options as
 44     arguments.
 45 
 46     @param {SC.View} view The view being transitioned.
 47     @param {Object} options Options to modify the transition.  As set by transitionShowOptions or transitionInOptions.
 48     @param {Object} finalLayout The final layout of the view, which may be different than the starting layout of the view if a previous transition was cancelled in place.
 49     @param {Object} finalFrame The final frame of the view, which may be different than the starting frame of the view if a previous transition was cancelled in place.
 50   */
 51   run: function (view, options, finalLayout, finalFrame) {},
 52 
 53 
 54   /**
 55     This optional property exposes a list of layout properties involved in the
 56     transition. This allows the view to more intelligently reset its layout when
 57     the transition is complete.
 58 
 59     If unspecified, the transition will cache and reset the entire layout hash. This
 60     can cause problems when spearately adjusting or animating those properties during
 61     a transition. (Note that you should not adjust or animate the layout properties
 62     that are involved in a transition while the transition is under way.)
 63 
 64     @field
 65     @type Array
 66     @default All layout properties
 67   */
 68   layoutProperties: []
 69 
 70 };
 71