1 // ==========================================================================
  2 // Project:   SproutCore
  3 // Copyright: @2013 7x7 Software, Inc.
  4 // License:   Licensed under MIT license (see license.js)
  5 // ==========================================================================
  6 
  7 /** @namespace
  8   The `SC.ChildViewLayoutProtocol` protocol defines the properties and methods that you may
  9   implement in your custom child view layout plugins. The only required method for a plugin to
 10   implement is `layoutChildViews`.
 11 
 12   *Note: Do not mix `SC.ChildViewLayoutProtocol` into your classes. As a protocol, it exists only
 13   for reference sake. You only need define any of the properties or methods listed below in order to
 14   use this protocol.*
 15 */
 16 SC.ChildViewLayoutProtocol = {
 17 
 18   /**
 19     An *optional* array of properties that should be observed on the child views in order
 20     to re-lay out the child views when changes occur. For example, most child
 21     view layout plugins will want to adjust the layout of the views whenever
 22     any view is hidden or becomes visible. Therefore, the parent view should
 23     re-run the child view layout whenever any child view's `isVisible` property
 24     changes and thus, `childLayoutProperties` should include at least the
 25     `isVisible` property name.
 26 
 27     For another example, the included stack child layout plugins both have the
 28     same `childLayoutProperties` defined:
 29 
 30         childLayoutProperties: ['marginBefore', 'marginAfter', 'isVisible']
 31 
 32     @type Array
 33   */
 34   childLayoutProperties: null,
 35 
 36   /**
 37     This *optional* method will be called when the view initializes itself. By
 38     returning `true` from this call, we would be indicating that whenever the
 39     view's size changes, it should re-lay out the child views.
 40 
 41     For instance, if the layout of the child views depends on the parent view's
 42     size, we should return `true`. If the layout of the child views is
 43     independent of the parent view's size, we can return false to improve
 44     performance.
 45 
 46     @param {SC.View} view The view that is using this plugin.
 47     @returns {Boolean} `true` if the view's size should be observed in order to re-lay out the child views.
 48   */
 49   layoutDependsOnSize: function (view) {},
 50 
 51   /**
 52     This *required* method will be called by the view each time that it needs
 53     to re-lay out its child views. The plugin should then as efficiently as
 54     possible, calculate each child views' new layout and call adjust on the
 55     child views.
 56 
 57     For code examples, see SC.View.VERTICAL_STACK and SC.View.HORIZONTAL_STACK
 58     in the core foundation framework.
 59 
 60     @param {SC.View} view The view that is using this plugin.
 61   */
 62   layoutChildViews: function (view) {}
 63 
 64 };
 65