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.SwapTransitionProtocol` protocol defines the properties and methods that you may
 10   implement in your custom swap transition plugins. All methods are optional, but a plugin is
 11   expected to use at least one of the methods.
 12 
 13   SC.ContainerView uses transition plugins to setup, execute and cleanup the swapping between views
 14   and expects the given transition plugin object to implement the methods in this protocol.
 15 
 16   *Note: Do not mix `SC.SwapTransitionProtocol` 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.SwapTransitionProtocol = {
 21 
 22   /**
 23     This optional method is called to set up the entrance transition.
 24 
 25     Use this method to adjust the layout of the container and new content so
 26     that it may be properly animated.  For example, you may need to adjust the
 27     content from a flexible layout (i.e. { left: 0, top: 0, right: 0, bottom: 0 })
 28     to a fixed layout (i.e. { left: 0, top: 0, width: 100, height: 200 })
 29     so that it can be moved.
 30 
 31     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
 32     @param {SC.View} content The new view added to the container.
 33     @param {SC.View} previousStatechart The current content statechart in the container.
 34     @param {Object} options Options to modify the transition.
 35   */
 36   willBuildInToView: function (container, content, previousStatechart, options) {},
 37 
 38   /**
 39     This optional method is called to transition the new content in.
 40 
 41     When the transition completes, the function must call the entered()
 42     method on the statechart.
 43 
 44     @param {SC.ContainerContentStatechart} statechart The statechart for the content view.
 45     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
 46     @param {SC.View} content The new view added to the container.
 47     @param {SC.View} previousStatechart The current content statechart in the container.
 48     @param {Object} options Options to modify the transition.
 49   */
 50   buildInToView: function (statechart, container, content, previousStatechart, options) {},
 51 
 52   /**
 53     This optional method is called to cancel an active entrance transition.
 54 
 55     Use this method to stop the animation and immediately clean up the views.
 56 
 57     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
 58     @param {SC.View} content The new view in the container, which is still transitioning in.
 59     @param {Object} options Options to modify the transition.
 60   */
 61   buildInDidCancel:  function (container, content, options) {},
 62 
 63   /**
 64     This optional method is called to clean up the entrance the transition.
 65 
 66     Use this method to adjust the layout of the container and new content after
 67     the transition completes.  For example, you may need to adjust the layout
 68     from a fixed layout (i.e. { left: 0, top: 0, width: 100, height: 200 })
 69     to a flexible layout (i.e. { left: 0, top: 0, right: 0, bottom: 0 }).
 70 
 71     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
 72     @param {SC.View} content The new view added to the container.
 73     @param {Object} options Options that were used to modify the transition.
 74   */
 75   didBuildInToView: function (container, content, options) {},
 76 
 77   /**
 78     This optional method is called to set up the exit transition.
 79 
 80     Use this method to adjust the layout of the container and new content so
 81     that it may be properly animated.  For example, you may need to adjust the
 82     content from a flexible layout (i.e. { left: 0, top: 0, right: 0, bottom: 0 })
 83     to a fixed layout (i.e. { left: 0, top: 0, width: 100, height: 200 })
 84     so that it can be moved.
 85 
 86     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
 87     @param {SC.View} content The old view being removed from the container.
 88     @param {Object} options Options to modify the transition.
 89   */
 90   willBuildOutFromView: function (container, content, options) {},
 91 
 92   /**
 93     This optional method is called to transition the old content out.
 94 
 95     When the transition completes, the function must call the exited()
 96     method on the statechart.
 97 
 98     Note that a view may be repeatedly built out before it has completed.  In
 99     order to accelerate the build out transition, the exitCount parameter will
100     be incremented each time buildOutFromView is called.  The initial value
101     will always be 1.
102 
103     @param {SC.ContainerContentStatechart} statechart The statechart for the content view.
104     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
105     @param {SC.View} content The old view being removed from the container.
106     @param {Object} options Options to modify the transition.
107     @param {Number} exitCount The number of times the content is being built out.
108   */
109   buildOutFromView: function (statechart, container, content, options, exitCount) {},
110 
111   /**
112     This optional method is called to cancel an active exit transition.
113 
114     Use this method to stop the animation and immediately clean up the views.
115 
116     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
117     @param {SC.View} content The old view being removed from the container, which is still transitioning out.
118     @param {Object} options Options to modify the transition.
119   */
120   buildOutDidCancel: function (container, content, options) {},
121 
122   /**
123     This optional method is called to clean up the entrance the transition.
124 
125     Use this method to adjust the layout of the container and new content after
126     the transition completes.  For example, you may need to adjust the layout
127     from a fixed layout (i.e. { left: 0, top: 0, width: 100, height: 200 })
128     to a flexible layout (i.e. { left: 0, top: 0, right: 0, bottom: 0 }).
129 
130     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
131     @param {SC.View} content The new view added to the container.
132     @param {Object} options Options that were used to modify the transition.
133   */
134   didBuildOutFromView: function (container, content, options) {},
135 
136   /**
137     This optional method is called to adjust the clippingFrame during the
138     transition.
139 
140     Because some childViews are altered by the clippingFrame of their parent
141     views (notably collection views), we may need to provide a modified
142     clipping frame while the transition is in process.
143 
144     For example, a push transition should double the regular clippingFrame
145     of the container to fit both the new and current content while the
146     transition is in progress.
147 
148     @param {SC.ContainerView} container The SC.ContainerView using this plugin.
149     @param {Object} clippingFrame The current clippingFrame of the container.
150     @param {Object} options Options used to modify the transition.
151     @returns clippingFrame
152   */
153   transitionClippingFrame: function (container, clippingFrame, options) {}
154 
155 };
156