sproutcore 1.6.0.beta.3-java → 1.6.0-java

data/lib/frameworks/sproutcore/frameworks/experimental/frameworks/select_view/views/popup_button.js

@@ -0,0 +1,264 @@
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+ * @class
+ * @extends SC.ButtonView
+ * @version 1.6
+ * @author Alex Iskander
+ */
+SC.PopupButtonView = SC.ButtonView.extend({
+  /** @scope SC.PopupButtonView.prototype */
+
+
+  /**
+    The render delegate to use to render and update the HTML for the PopupButton.
+    
+    @type String
+    @default 'popupButtonRenderDelegate'
+  */
+  renderDelegateName: 'popupButtonRenderDelegate',
+
+  /**
+    The menu that will pop up when this button is clicked. This can be a class or
+    an instance.
+    
+    @type {SC.MenuPane}
+    @default SC.MenuPane
+  */
+  menu: SC.MenuPane,
+
+  /**
+    If YES, a menu instantiation task will be placed in SproutCore's
+    `SC.backgroundTaskQueue` so the menu will be instantiated before 
+    the user taps the button, improving response time.
+
+    @type Boolean
+    @default NO
+    @property
+  */
+  shouldLoadInBackground: NO,
+
+  /**
+   * @private
+   * If YES, the menu has been instantiated; if NO, the 'menu' property
+   * still has a class instead of an instance.
+  */
+  _menuIsLoaded: NO,
+
+  /** @private
+    isActive is NO, but when the menu is instantiated, it is bound to the menu's isVisibleInWindow property.
+  */
+  isActive: NO,
+
+  acceptsFirstResponder: YES,
+  
+
+  /**
+    @private
+  */
+  init: function() {
+    sc_super();
+
+    // keep track of the current instantiated menu separately from
+    // our property. This allows us to destroy it when the property
+    // changes, and to track if the property change was initiated by
+    // us (since we set `menu` to the instantiated menu).
+    this._currentMenu = null;
+    this.invokeOnce('scheduleMenuSetupIfNeeded');
+  },
+
+  /**
+    Adds menu instantiation to the background task queue if the menu
+    is not already instantiated and if shouldLoadInBackground is YES.
+    
+    @method
+    @private
+   */
+  scheduleMenuSetupIfNeeded: function() {
+    var menu = this.get('menu');
+
+    if (menu && menu.isClass && this.get('shouldLoadInBackground')) {
+      SC.backgroundTaskQueue.push(SC.PopupButtonView.InstantiateMenuTask.create({ popupButton: this }));
+    }
+  },
+
+  /** @private if the menu changes, it must be set up again. */
+  menuDidChange: function() {
+    // first, check if we are the ones who changed the property
+    // by setting it to the instantiated menu
+    var menu = this.get('menu');
+    if (menu === this._currentMenu) { 
+      return;
+    }
+
+    this.invokeOnce('scheduleMenuSetupIfNeeded');
+  }.observes('menu'),
+
+  /**
+   Instantiates the menu if it exists and is not already instantiated.
+   If another menu is already instantiated, it will be destroyed.
+  */
+  setupMenu: function() {
+    var menu = this.get('menu');
+
+    // handle our existing menu, if any
+    if (menu === this._currentMenu) { return; }
+    if (this._currentMenu) {
+      this.isActiveBinding.disconnect();
+
+      this._currentMenu.destroy();
+      this._currentMenu = null;
+    }
+
+    // do not do anything if there is nothing to do.
+    if (menu && menu.isClass) {
+      menu = this.createMenu(menu);
+    }
+
+    this._currentMenu = menu;
+    this.set('menu', menu);
+
+    this.isActiveBinding = this.bind('isActive', menu, 'isVisibleInWindow');
+  },
+
+  /**
+    Called to instantiate a menu. You can override this to set properties
+    such as the menu's width or the currently selected item.
+    
+    @param {SC.MenuPane} menu The MenuPane class to instantiate.
+  */
+  createMenu: function(menu) {
+    return menu.create();
+  },
+
+
+  /**
+    Shows the PopupButton's menu. You can call this to show it manually.
+    
+    NOTE: The menu will not be shown until the end of the Run Loop.
+  */
+  showMenu: function() {
+    // problem: menu's bindings may not flush
+    this.setupMenu();
+
+    // solution: pop up the menu later. Ugly-ish, but not too bad:
+    this.invokeLast('_showMenu');
+  },
+
+  /**
+    Hides the PopupButton's menu if it is currently showing.
+  */
+  hideMenu: function() {
+    var menu = this.get('menu');
+    if (menu && !menu.isClass) {
+      menu.remove();
+    }
+  },
+
+  /**
+    The prefer matrix (positioning information) to use to pop up the new menu.
+    
+    @property
+    @type Array
+    @default [0, 0, 0]
+  */
+  menuPreferMatrix: [0, 0, 0],
+
+  /**
+    @private
+    The actual showing of the menu is delayed because bindings may need
+    to flush.
+  */
+  _showMenu: function() {
+    var menu = this.get('menu');
+
+    menu.popup(this, this.get('menuPreferMatrix'));
+  },
+
+  /** @private */
+  mouseDown: function(evt) {
+    // If disabled, handle mouse down but ignore it.
+    if (!this.get('isEnabled')) return YES ;
+
+    this.set('_mouseDown', YES);
+
+    this.showMenu();
+
+    this._mouseDownTimestamp = new Date().getTime();
+    this.becomeFirstResponder();
+
+    return YES;
+  },
+
+  /** @private */
+  mouseUp: function(evt) {
+    var menu = this.get('menu'), targetMenuItem, success;
+
+    if (menu && this.get('_mouseDown')) {
+      targetMenuItem = menu.getPath('rootMenu.targetMenuItem');
+
+      if (targetMenuItem && menu.get('mouseHasEntered')) {
+        // Have the menu item perform its action.
+        // If the menu returns NO, it had no action to
+        // perform, so we should close the menu immediately.
+        if (!targetMenuItem.performAction()) {
+          menu.remove();
+        }
+      } else {
+        // If the user waits more than 200ms between mouseDown and mouseUp,
+        // we can assume that they are clicking and dragging to the menu item,
+        // and we should close the menu if they mouseup anywhere not inside
+        // the menu.
+        if (this._mouseDownTimestamp && evt.timeStamp - this._mouseDownTimestamp > 400) {
+          menu.remove();
+        }
+      }
+    }
+
+    this._mouseDownTimestamp = undefined;
+    return YES;
+  },
+
+  /**
+    @private
+    
+    Shows the menu when the user presses Enter. Otherwise, hands it off to button
+    to decide what to do.
+  */
+  keyDown: function(event) {
+    if (event.which == 13) {
+      this.showMenu();
+      return YES;
+    }
+
+    return sc_super();
+  }
+});
+
+/**
+  @class
+  
+  An SC.Task that handles instantiating a PopupButtonView's menu. It is used
+  by SC.PopupButtonView to instantiate the menu in the backgroundTaskQueue.
+*/
+SC.PopupButtonView.InstantiateMenuTask = SC.Task.extend(
+  /**@scope SC.PopupButtonView.InstantiateMenuTask.prototype */ {
+    
+  /**
+    The popupButton whose menu should be instantiated.
+    
+    @property
+    @type {SC.PopupButtonView}
+    @default null
+  */
+  popupButton: null,
+  
+  /** Instantiates the menu. */
+  run: function(queue) {
+    this.popupButton.setupMenu();
+  }
+});
+

data/lib/frameworks/sproutcore/frameworks/experimental/frameworks/select_view/views/select.js

@@ -0,0 +1,450 @@
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('views/popup_button');
+sc_require('mixins/select_view_menu');
+
+/**
+ * @class
+ * @extends SC.PopupButtonView
+ * @version 2.0
+ * @author Alex Iskander
+ */
+SC.SelectView = SC.PopupButtonView.extend({
+  /** @scope SC.SelectView.prototype */
+
+  //
+  // Properties
+  //
+  theme: 'popup',
+  renderDelegateName: 'selectRenderDelegate',
+
+  /**
+    The array of items to populate the menu. This can be a simple array of strings,
+    objects or hashes. If you pass objects or hashes, you can also set the
+    various itemKey properties to tell the menu how to extract the information
+    it needs.
+
+    @property {Array}
+    @default []
+  */
+  items: null,
+
+  /**
+    Binding default for an array of items
+
+    @property
+    @default SC.Binding.multiple()
+  */
+  itemsBindingDefault: SC.Binding.multiple(),
+
+  /**
+    They key in the items which maps to the title.
+    This only applies for items that are hashes or SC.Objects.
+
+    @property
+    @type {String}
+    @default 'title'
+  */
+  itemTitleKey: 'title',
+
+  /**
+    If you set this to a non-null value, then the value of this key will
+    be used to sort the items.  If this is not set, then itemTitleKey will
+    be used.
+
+    @property
+    @type: {String}
+    @default null
+  */
+  itemSortKey: null,
+
+  /**
+    They key in the items which maps to the value.
+    This only applies for items that are hashes or SC.Objects.
+
+     @property
+     @type {String}
+     @default 'value'
+  */
+  itemValueKey: 'value',
+
+  /**
+     Key used to extract icons from the items array.
+     
+     @property
+     @type {String}
+     @default null
+  */
+  itemIconKey: null,
+  
+  /**
+    Key to use to identify separators.
+    
+    Items that have this property set to YES will be drawn as separators.
+    
+    @property
+    @type {String}
+    @default null
+  */
+  itemSeparatorKey: "separator",
+  
+  /**
+    Key used to indicate if the item is to be enabled.
+    
+    @property
+    @type {String}
+    @default null
+  */
+  itemIsEnabledKey: "isEnabled",
+
+
+  /**
+   The menu that will pop up when this button is clicked.
+   
+   The default menu has its properties bound to the SC.SelectView,
+   meaning that it will get all its items from the SelectView.
+   You may override the menu entirely with one of your own; if you
+   mix in SC.SelectViewMenu, it'll get the bindings and the extended
+   MenuItemView that draws its checkbox when it is the selected item.
+   
+   @property
+   @type {SC.MenuPane}
+   @default SC.MenuPane.extend(SC.SelectViewMenu)
+  */
+  menu: SC.MenuPane.extend(SC.SelectViewMenu),
+
+  /**
+    The currently selected item. If no item is selected, `null`.
+    
+    @private
+    @property {SC.Object}
+    @default null
+    @isReadOnly
+   */
+  selectedItem: null,
+  selectedItemBinding: '*menu.rootMenu.selectedItem',
+
+
+  /**
+    This is a property to enable/disable focus rings in buttons. 
+    For SelectView, it is a default.
+    
+    @property
+    @type {Boolean}
+    @default YES
+  */
+  supportsFocusRing: YES,
+
+
+  /**
+    * @private
+  */
+  init: function() {
+    sc_super();
+
+    // call valueDidChange to get the initial item, if any
+    this._scsv_valueDidChange();
+  },
+
+  /**
+    @private
+
+    This gets the value for a specific menu item. This function allows a few different
+    forms of input:
+
+    - A string: returns the string.
+    - A hash: returns hash[itemValueKey], using 'value' for the key if necessary.
+    - An SC.Object: returns object.get(itemValueKey), using 'value' for the key if needed.
+
+    This method therefore accepts both the menu items as created for the menupane's displayItems
+    AND the raw items provided by the developer in `items`.
+  */
+  _scsv_getValueForMenuItem: function(item) {
+    var valueKey = this.get('itemValueKey') || 'value';
+
+    if (SC.typeOf(item) === SC.T_STRING) {
+      return item;
+    } else if (item.get) {
+      return item.get(valueKey);
+    } else {
+      return item[valueKey];
+    }
+  },
+
+  /**
+    * When the selected item changes, we need to update our value.
+    * @private
+  */
+  _scsv_selectedItemDidChange: function() {
+    var sel = this.get('selectedItem'),
+        last = this._scsv_lastSelection,
+        titleKey = this.get('itemTitleKey') || 'title',
+        valueKey = this.get('itemValueKey') || 'value';
+
+    // selected item could be a menu item from SC.MenuPane's displayItems, or it could
+    // be a raw item. So, we have to use _scsv_getValueForMenuItem to resolve it.
+    if(sel) {
+      this.setIfChanged('value', this._scsv_getValueForMenuItem(sel));
+    }
+
+    // add/remove observers for the title and value so we can invalidate.
+    if (last && last.addObserver && sel !== last) {
+      last.removeObserver(titleKey, this, this._scsv_selectedItemPropertyDidChange);
+      last.removeObserver(valueKey, this, this._scsv_selectedItemPropertyDidChange);
+    }
+    
+    if (sel && sel.addObserver && sel !== last) {
+      sel.addObserver(titleKey, this, this._scsv_selectedItemPropertyDidChange);
+      sel.addObserver(valueKey, this, this._scsv_selectedItemPropertyDidChange);
+    }
+
+    this._scsv_lastSelection = sel;
+  }.observes('selectedItem'),
+
+  // called when either title or value changes on the selected item
+  _scsv_selectedItemPropertyDidChange: function(item) {
+    this.notifyPropertyChange('title');
+    this.set('value', item.get(this.get('itemValueKey') || 'value'));
+  },
+
+  /**
+    The title to show when no item is selected.
+
+    @property
+    @type String
+    @default ""
+  */
+  defaultTitle: "",
+
+  /**
+    The title of the button, derived from the selected item.
+  */
+  title: function() {
+    var sel = this.get('selectedItem');
+
+    if (!sel) {
+      return this.get('defaultTitle');
+    } else if (sel.get) {
+      return sel.get(this.get('itemTitleKey') || 'title');
+    } else if (SC.typeOf(sel) == SC.T_HASH) {
+      return sel[this.get('itemTitleKey') || 'title'];
+    } else {
+      return sel;
+    }
+  }.property('selectedItem').cacheable(),
+
+  /**
+    * When the value changes, we need to update selectedItem.
+    * @private
+  */
+  _scsv_valueDidChange: function() {
+    var value = this.get('value');
+
+    if (!this.get('items')) {
+      return;
+    }
+
+    var items = this.get('items'), len = items.length, idx;
+    for (idx = 0; idx < len; idx++) {
+      if (this._scsv_getValueForMenuItem(items[idx]) === value) {
+        this.setIfChanged('selectedItem', items[idx]);
+        return;
+      }
+    }
+
+    // if we got here, this means no item is selected
+    this.setIfChanged('selectedItem', null);
+  }.observes('value'),
+
+  /**
+    SelectView must set the selectView property on the menu so that the menu's
+    properties get bound to the SelectView's. The bindings get set up by 
+    the SelectViewMenu mixin, which should be mixed in to any SelectView menu.
+
+    In addition, the initial selected item and the initial minimum menu width are set.
+    @private
+  */
+  createMenu: function(klass) {
+    var attrs = {
+      selectView: this,
+      selectedItem: this.get('selectedItem'),
+      minimumMenuWidth: this.get('minimumMenuWidth')
+    };
+
+    return klass.create(attrs);
+  },
+
+  /**
+    The amount by which to offset the menu's left position when displaying it.
+    This can be used to make sure the selected menu item is directly on top of
+    the label in the SelectView.
+
+    By default, this comes from the render delegate's menuLeftOffset property. 
+    If you are writing a theme, you should set the value there.
+    
+    @property
+    @type Number
+    @default 'menuLeftOffset' from render delegate if present, or 0.
+  */
+  menuLeftOffset: SC.propertyFromRenderDelegate('menuLeftOffset', 0),
+
+  /**
+    The amount by which to offset the menu's top position when displaying it.
+    This is added to any amount calculated based on the 'top' of a menu item.
+
+    This can be used to make sure the selected menu item's label is directly on
+    top of the SelectView's label.
+
+    By default, this comes from the render delegate's menuTopOffset property.
+    If you are writing a theme, you should set the value there.
+
+    @property
+    @type Number
+    @default 'menuTopOffset' from render delegate if present, or 0.
+  */
+  menuTopOffset: SC.propertyFromRenderDelegate('menuTopOffset', 0),
+
+  /**
+    An amount to add to the menu's minimum width. For instance, this could be
+    set to a negative value to let arrows on the side of the SelectView be visible.
+
+    By default, this comes from the render delegate's menuMinimumWidthOffset property.
+    If you are writing a theme, you should set the value there.
+
+    @property
+    @type Number
+    @default 'menuWidthOffset' from render delegate if present, or 0.
+  */
+  menuMinimumWidthOffset: SC.propertyFromRenderDelegate('menuMinimumWidthOffset', 0),
+
+  /**
+    The prefer matrix for menu positioning. It is calculated so that the selected
+    menu item is positioned directly over the SelectView.
+    
+    @property
+    @type Array
+    @private
+  */
+  menuPreferMatrix: function() {
+    var menu = this.get('menu'),
+        leftPosition = this.get('menuLeftOffset'),
+        topPosition = this.get('menuTopOffset');
+
+    if (!menu) {
+      return [leftPosition, topPosition, 2];
+    }
+
+    var idx = this.get('_selectedItemIndex'), itemViews = menu.get('menuItemViews');
+    if (idx > -1) {
+      return [leftPosition, topPosition - itemViews[idx].get('layout').top, 2];
+    }
+
+    return [leftPosition, topPosition, 2];
+
+  }.property('value', 'menu').cacheable(),
+
+  /**
+    Used to calculate things like the menu's top position.
+
+    @private
+  */
+  _selectedItemIndex: function() {
+    var menu = this.get('menu');
+    if (!menu) {
+      return -1;
+    }
+
+    // We have to find the selected item, and then get its 'top' position so we
+    // can position the menu correctly.
+    var itemViews = menu.get('menuItemViews'), idx, len = itemViews.length, view;
+    for (idx = 0; idx < len; idx++) {
+      view = itemViews[idx];
+
+      // we have to compare via value
+      var value = view.get('content').get(this.get('itemValueKey'));
+      if (value === this.get('value')) {
+        break;
+      }
+    }
+
+    if (idx < len) {
+      return idx;
+    }
+
+    return -1;
+  }.property('value', 'menu').cacheable(),
+
+
+  /*
+    Documented in base class; supplying documentation here will break the argument list.
+  */
+  showMenu: function(orig) {
+    orig();
+
+    var menu = this.get('menu'), itemViews = menu.get('menuItemViews');
+  }.enhance(),
+
+  /**
+    The minimum width for the child menu. For instance, this property can make the
+    menu always cover the entire SelectView--or, alternatively, cover all but the
+    arrows on the side.
+
+    By default, it is calculated by adding the menuMinimumWidthOffset to the view's 
+    width. If you are writing a theme and want to change the width so the menu covers
+    a specific part of the select view, change your render delegate's menuMinimumWidthOffset
+    property.
+
+    @type Number
+    @property
+  */
+  minimumMenuWidth: function() {
+    return this.get('frame').width + this.get('menuMinimumWidthOffset');
+  }.property('frame', 'menuMinimumWidthOffset').cacheable(),
+
+  //
+  // KEY HANDLING
+  //
+  /**
+    @private
+
+    Handle Key event - Down arrow key
+  */
+  keyDown: function(event) {
+    if ( this.interpretKeyEvents(event) ) {
+      return YES;
+    }
+    else {
+      sc_super();
+    }
+  },
+
+  /**
+    @private
+
+    Pressing the Up or Down arrow key should display the menu pane
+  */
+  interpretKeyEvents: function(event) {
+    if (event) {
+      if ((event.keyCode === 38 || event.keyCode === 40)) {
+        this.showMenu();
+        return YES;
+      }
+      else if (event.keyCode === 27) {
+        this.resignFirstResponder() ;
+        return YES;
+      }
+    }
+    return sc_super();
+  },
+
+  /** @private
+   Function overridden - tied to the isEnabled state 
+  */
+  acceptsFirstResponder: function() {
+    return this.get('isEnabled');
+  }.property('isEnabled').cacheable()
+
+});