toolbar.js

javascript 很酷的类库

    // update the tabIndex of any buttons who have no user-specified tab index, and 
    // for which we haven't yet managed the tabIndex    
    var buttons = this.getButtons();
    for (var i = 0; i < buttons.length; i++) {
        var button = buttons[i];
        if (button != focusButton &&
            (button.tabIndex == null || button._autoTabIndex)) 
        {
            //this.logWarn("updating tab index of: " + button + " to " + defaultTabIndex);
            this._setButtonTabIndex(button, defaultTabIndex)
        }
    }        
},


_updateFocusButton : function (newFocusButton) {

    // Bail if the current focus button was passed in
    if (this._currentFocusButton == newFocusButton) return;
    
    // Update the accessKey for the current focus button unless it has / had an explicitly
    // specified accessKey
    if (newFocusButton.accessKey != this.accessKey &&
        (newFocusButton.accessKey == null || newFocusButton._toolbarManagedAccessKey)) 
    {
        this._setButtonAccessKey(newFocusButton, this.accessKey)
    }
    
    // Update focus button tab index (if allocated by us)
    if (newFocusButton.tabIndex == null || newFocusButton._autoTabIndex || 
        newFocusButton._toolbarManagedTabIndex) 
    {
        
        // set the newly focused button to the tabIndex of the Toolbar
        this._setButtonTabIndex(newFocusButton, this.getTabIndex());
    }
    
    var oldFocusButton = this._currentFocusButton;
    // If appropriate, remove the previous focus button from the tab order
    if (oldFocusButton != null && 
        (oldFocusButton.tabIndex == null || oldFocusButton._autoTabIndex || 
         oldFocusButton._toolbarManagedTabIndex)) 
    {
        // Remove from tab order if we are not tabbing between buttons
        if (!this.tabWithinToolbar) this._setButtonTabIndex(oldFocusButton, -1);
        
        // Clear the accessKey property if it was added by the toolbar
        if (oldFocusButton.accessKey != null && 
            oldFocusButton._toolbarManagedAccessKey) 
        {
            this._setButtonAccessKey(oldFocusButton, null)
        }
    }

    this._currentFocusButton = newFocusButton;
},

// Override _setTabIndex() to set also update the tab index of the buttons
_setTabIndex : function (a,b,c,d) {
    this.invokeSuper(isc.Toolbar, "_setTabIndex", a,b,c,d);

    // if this.tabWithinToolbar is true, update each of the buttons' tab index to match the
    // toolbars new tab index
    if (this.tabWithinToolbar) {
        var buttons = this.getButtons();
        for (var i = 0; i < buttons.length; i++) {
            if (buttons[i].tabIndex == null || buttons[i]._autoTabIndex) 
                this._setButtonTabIndex(buttons[i], this.getTabIndex())
        }
    // otherwise use _updateFocusButton to update the tab index of the focus button only (other
    // buttons' tab index will already be -1 -- no need to change)        
    } else {
        var button = this._currentFocusButton;
        if (button != null) {
            this._currentFocusButton = null;
            this._updateFocusButton(button);
        }
    }
},

// Override setAccessKey() to alo set the accessKey for the toolbar
setAccessKey : function (accessKey) {
    this.Super("setAccessKey", arguments);
    
    // use updateFocusButton to update the accessKey for the focus button
    var button = this._currentFocusButton;
    if (button != null) {
        this._currentFocusButton = null;
        this._updateFocusButton(button);
    }
    
},

getLength : function (a,b,c,d) {
	// the Toolbar allows overriding the area allocated to layout members, so that it may be
    // larger or smaller than the Layout's area.
    if (this.innerWidth != null) return this.innerWidth;
    return this.invokeSuper(isc.Toolbar, "getLength", a,b,c,d);
},

//>	@method	toolbar.setButtons()
//	Set up the toolbar buttons, including their sizes if not explicitly specified
//	@group	drawing
//
//	@param	[newButtons]	(object[])	
//            list of button objects (objects with 'title', 'width', etc properties)
//<
setButtons : function (newButtons) {

    // one time flag - allows us to set up our buttons on initial draw only.
    // If 'setButtons' is called before draw we won't unnecessarily remove and re-add them all.
    this._buttonsInitialized = true;
    
	//this.logWarn("setButtons at\n" + this.getStackTrace());

	// if buttons are passed in, use those 
    // Otherwise we'll just make actual button instances from the current items in this.buttons
	if (newButtons) this.buttons = newButtons;

    if (this.members == null) this.members = [];
    
    // destroy any existing members, and create new buttons from scratch
    var _buttons = this.members.duplicate();        
    for (var i = 0; i < _buttons.length ; i++) {
        var oldButton = _buttons[i];
        // destroy any members we automatically created from the buttons array
        if (!this.buttons.contains(oldButton)) {
            //this.logWarn("destroying old button " + i);
            // destroying it will automagically remove it from this as a member, so no
            // need to call this.removeMembers()
            _buttons[i].destroy();
        }
    }

	// now create actual button widgets
    if (this.buttons == null) this.buttons = [];
	for (var i = 0; i < this.buttons.length; i++) {
        var button = this.buttons[i];

        // allow widgets to be placed directly in the buttons array, which we simply add as
        // members and ignore.  These members will not have pick up buttonDefaults, hence won't
        // fire itemClick, have associated panes, allow managed resize, etc.
        if (!isc.isA.Canvas(button)) button = this.makeButton(button);
                
        // NOTE: use explicit position so that an existing member will be moved
        this.addMember(button, i);

        if (isc.isA.StatefulCanvas(button)) {
            var actionType = button.getActionType();

            if (actionType == isc.StatefulCanvas.RADIO) {
                            
                // For actionType:radio buttons, remember initial selected button.  
                // We update this on selection change.
                // This property will be returned on 'Toolbar.getSelectedButton()'
                // Note - no error checking for multiple selection within a toolbar
                // If each 'actionType' RADIO button has no specified radiogroup, the default
                // toolbar behavior is to put them into the same radioGroup. In this case default 
                // radiogroup selection behavior inherited from StatefulCanvas will prevent
                // multiple selection within a toolbar.
                // If the user has specified a radiogroup for any actionType:RADIO buttons, we
                // can't guarantee there won't be multiple selection within a toolbar.
                // In this case 'getSelectedButton()' will return the most recently selected RADIO
                // button within this toolbar, rather than the only selected radio button.
                if (button.selected) this.lastSelectedButton = button;
            }
        }
    }

    if (this.canResizeItems) this.setResizeRules();
    // Set up the tab indexes for the buttons, and the accessKey for the focus button
    this.setupButtonFocusProperties();

},

// shouldHiliteAccessKey implementation for buttons in this toolbar
buttonShouldHiliteAccessKey : function () {
    // If the accessKey comes from the toolbar itself, don't hilite
    // otherwise we will end up with underlining of the title on multiple buttons which
    // is likely to look odd.
    if (this._toolbarManagedAccessKey) return false;
    return this.hiliteAccessKey;
},

makeButton : function (button) {
    // the default sizing behavior we want:
    // - horizontal toolbars autoSize button heights to the Toolbar's height and autoSize
    //   button widths to the button text.  
    // - vertical toolbars autoSize button width to the Toolbar's width and autoSize button
    //   heights to the (wrapped) button text.

    
    button.width = button.width || null;
    button.height = button.height || null;

    // set button properties to enable/disable dragging and dropping, so that dragging will
    // be allowed on members and will bubble to the Toolbar
    
    button.canDrag = this.canReorderItems || this.canDragSelectItems || this.canRemoveItems;
    button.canDragResize = this.canResizeItems;
    // toolbar allows things to be dropped on it (currently no default behavior for what happens
    // on drop)
    button.canAcceptDrop = this.canAcceptDrop;
    // if you can drag items out of the toolbar, make the buttons droppable
    button.canDrop = this.canRemoveItems;
    
    button.shouldHiliteAccessKey = this.buttonShouldHiliteAccessKey;

    // create a new button widget
    //this.logWarn("creating new button " + i);
    return this._makeItem(button, null);
},

//>	@method	toolbar._makeItem()
// Creates and returns a widget for the toolbar
//		@group	drawing
//
//		@param	[buttonProperties]	(object)	the button properties
//		@param	[rect]		(object)	the rectangle for this widget, e.g. {top:50, left:100, ...}
//
//		@return	(object)	the created widget
//<
_makeItem : function (buttonProperties, rect) {
	var cons = (buttonProperties.buttonConstructor
						? buttonProperties.buttonConstructor
						: this.buttonConstructor
					  )
	;
	cons = this.ns.ClassFactory.getClass(cons);
	
	var item = cons.newInstance(
				{autoDraw:false},
				this.buttonDefaults,	// isc.Toolbar class defaults
				this.buttonProperties,	// isc.Toolbar instance defaults
				buttonProperties,       // properties for this button
				rect					// rectangle for the button
			);

    if (!isc.isA.StatefulCanvas(item)) return item;

    // if the button is of actionType 'radio' and the developer has not specified a
    // radioGroup, set radioGroup to the ID of this toolbar
    // Developer can override by setting 'radioGroup' property explicitly on the
    // item's properties.
    var unset;        
    if ((item.getActionType() == isc.StatefulCanvas.RADIO && item.radioGroup === unset)
        || item.defaultRadioGroup != null) {
        var rg = item.defaultRadioGroup != null ? item.defaultRadioGroup : this.getID();
        item.addToRadioGroup(rg);
    }
    
    return item;
},

//>	@method	toolbar.addButtons()
//			Add a list of buttons to the toolbar
//		@group	drawing
//
//		@param	[buttons]	(object[])	list of button objects (object literal with 'title', 'width', etc)
//		@param	[position]		(number)	position to add the new buttons at
//<
addButtons : function (buttons, position) {

    if (buttons == null) return;
    if (!isc.isAn.Array(buttons)) buttons = [buttons];

    if (!this._buttonsInitialized) this.setButtons();
    buttons.removeEvery(null);

    // Update this.buttons to include the new buttons:
    this.buttons.addListAt(buttons, position);

    var buttonWidgets = [];
    for (var i = 0; i < buttons.length; i++) {
       	var button = buttons[i],
        // call makeButton() to convert the init block to a widget with the appropriate
        // propoerties (canDrag, buttonDefaults, etc)
        // Note that canvases are just integrated into the buttons block without
        // attempting to modify properties, as with setButtons()
        buttonWidget = isc.isA.Canvas(button) ? button : this.makeButton(button);
        buttonWidgets[i] = buttonWidget;
    }
    
    // Add as members to the right position, and let layout handle spacing and stuff
    this.addMembers(buttonWidgets, position)

    // setResizeRules to update dragResizing, etc.
    if (this.canResizeItems) this.setResizeRules();

    buttonWidgets.map("show");  // auto-show the new members
},


//>	@method	toolbar.removeButtons()
//	Remove a list of buttons from the toolbar
//		@group	drawing
//
//		@param	[buttons]	(object[])	list of button objects (object literal with 'title', 'width', etc)
//<
removeButtons : function (buttons) {
    if (buttons == null) return;
    if (!isc.isAn.Array(buttons)) buttons = [buttons];
    
    // We're going to manipulate the this.buttons array (button description objects), and
    // the actual buttons in this.members - so will need pointers to both the 
    // button descriptor objects and the button instances.
    var buttonWidgets = [];
    
    // The buttons to remove can be specified as:
    // a) Index in this.buttons
    // b) Button widget
    // c) Button instantiation block
    // d) ID of button
    for (var i =0; i < buttons.length; i ++) {

        // resolve whatever object was passed in to a button instantiation block
        buttons[i] = this.buttons[this.getButtonNumber(buttons[i])];        
        
        if (buttons[i] == null)  {
            this.logWarn("removeButtons(): unable to find button for item number " + i + 
                        " in the array passed in.  Skipping this item.");
            buttons.removeItem(i);
            i -= 1;
            continue;
        }
        // get a pointer to the Canvas as well
        buttonWidgets[i] = this.getButton(this.buttons.indexOf(buttons[i]))
    }
    
    var completeButtons = this.buttons;
    // if (any of) the buttons aren't in this.buttons, this has no effect
    completeButtons.removeList(buttons);
  
    this.removeMembers(buttonWidgets);
// should we destroy them?
    
},

//>	@method	toolbar.getButton() ([])
//          Retrieves a button widget instance (within this toolbar) from the ID / index / 
//          descriptor object for the button (as with the getButtonNumber() method)
//          This provides a way to access a toolbar button's properties and methods directly.
//      @see    getButtonNumber()
//      @visibility external
//		@group	buttons
//		@param	index		(number | string | object)    identifier for the button to retrieve
//
//      @return (Button)    the button, or null if the button wasn't found
//<
getButton : function (index) {
    index = this.getButtonNumber(index);
	return this.getMember(index);
},

//>	@method	toolbar.getButtonNumber()	(A)
//			get the index of a button in the buttons array<p>
//          The button can be specified as - 
//          <ul>
//          <li>an index within this.buttons (just returned)
//          <li>the ID property of a button
//          <li>a pointer to the button descriptor object in this.buttons
//          <li>the actual button widget in this.members
//          </ul><p>
//			returns -1 if not found
//
//		@param	button		(number | string  | button object | button widget)
//
//		@return	(number)	index of the button in question
// @visibility external
//<
getButtonNumber : function (button) {
	// if we're passed an Object that isn't a Canvas, it might be a button configuration object
    if (isc.isAn.Object(button) && !isc.isA.Canvas(button)) return this.buttons.indexOf(button);
    // otherwise use normal member lookup
    return this.getMemberNumber(button);
},

//>	@method	toolbar.getButtons()
//		@group	buttons
//		@return (array) array of all buttons in the Toolbar
//<
getButtons : function () {
	return this.members;
},

// update which edges a button can be resized from.
//
// When you dragResize buttons, it always effects the button on the left (or top), regardless
// of which side of the boundary between the buttons you click on (this is pulled off by
// switching the dragTarget on the fly).  This means the sides that each button can be resized
// from is affected by whether the adjacent buttons can be resized.  setResizeRules updates
// this; it needs to be called on any reorder, addition or removal of buttons.
setResizeRules : function () {
    if (!this.members) return;

    var rtl = this.isRTL();

    // buttons can resize along the long axis of the toolbar. 
    var edgeCursorMap, resizeFrom, resizeFromOneSide;
    if (this.vertical) {
        edgeCursorMap = {"T":isc.Canvas.ROW_RESIZE, "B":isc.Canvas.ROW_RESIZE };
        resizeFrom = ["T","B"];