toolbar.js

javascript 很酷的类库

/*
 * Isomorphic SmartClient
 * Version 6.5 (2008-04-30)
 * Copyright(c) 1998-2007 Isomorphic Software, Inc. All rights reserved.
 * "SmartClient" is a trademark of Isomorphic Software, Inc.
 *
 * [e-mail]
 *
 * http://smartclient.com/license
 */

 





//>	@class	Toolbar
//
// A Toolbar creates a vertical or horizontal strip of similar components (typically Buttons)
// and provides managed resizing and reordering behavior over those components.
// <p>
// If you are creating a bar with a mixture of different elements (eg some MenuButtons, some
// Labels, some Buttons, some custom components), you want to use a +link{ToolStrip}.  A
// Toolbar is better suited for managing a set of highly similar, interchangeable components,
// such as ListGrid headers.
//
// @treeLocation Client Reference/Layout
// @visibility external
//<

// declare the class itself
isc.ClassFactory.defineClass("Toolbar", "Layout");

// add default properties to the class
isc.Toolbar.addProperties( {
	//>	@attr	toolbar.buttons		(array : null : [IRW])
    // An array of button object initializers. See the Button Widget Class for standard
    // button properties. The following additional properties can also be specified for
    // button sizing and positioning on the toolbar itself:<br><br>
    // <ul><li>width--Specifies the width of this button as an absolute number of pixels, a
    // named property of the toolbar that specifies an absolute number of pixels, a
    // percentage of the remaining space (e.g. '60%'), or "*" (default) to allocate an
    // equal portion of the remaining space.
    // <li>height--Specifies the height of this button.
    // <li>extraSpace--Specifies an optional amount of extra space, in pixels, to separate
    // this button from the next button in the toolbar.</ul>
    //      @visibility external
    //      @see class:Button
    //<

	//>	@attr	toolbar.vertical		(boolean : false : [IRW])
	// Indicates whether the buttons are drawn horizontally from left to right (false), or
    // vertically from top to bottom (true).
	//		@group	appearance
    //      @visibility external
	//<
	vertical:false,

	//>	@attr	toolbar.overflow		(Overflow : Canvas.HIDDEN : IRWA)
	// Clip stuff that doesn't fit
	//		@group	clipping
	//<
	overflow:isc.Canvas.HIDDEN,
	
	//>	@attr	toolbar.height		(number : 20 : IRW)
	// Default to a reasonable height
	//		@group	sizing
	//<
	height:20,					

    //>	@attr	toolbar.buttonConstructor		(Class : Button : IRWA)
	// Default constructor for toolbar items.
	//		@group	appearance
    //	@visibility external
	//<
	buttonConstructor:"Button",

    //>	@attr	toolbar.canReorderItems		(boolean : false : IRWA)
	//		If true, items can be reordered by dragging on them.
	//		@group	dragndrop
    //	@visibility external
	//<
	canReorderItems:false,

    //>	@attr	toolbar.canResizeItems		(boolean : false : IRWA)
	//		If true, items (buttons) can be resized by dragging on them.
	//		@group	dragndrop
    //	@visibility external
	//<
	canResizeItems:false,

    //>	@attr	toolbar.canRemoveItems      (boolean : false : IRWA)
	// If true, items (buttons) can be dragged out of this toolbar to be dropped somewhere else
	//		@group	dragndrop
	//<
	canRemoveItems:false,

    //>	@attr	toolbar.canAcceptDrop (boolean : false : IRWA)
	// If true, items (buttons) can be dropped into this toolbar, and the toolbar will
    // show a drop line at the drop location.  Override drop() to decide what happens when the
    // item is dropped.
    //
	//		@group	dragndrop
    //	@visibility external
	//<

    

    //>	@attr	toolbar.reorderOnDrop       (boolean : true : IRWA)
    //     On drop, should the Toolbar rearrange the buttons array?  Set to false by advanced
    //     classes that want to manage reordering themselves.
	//		@group	dragndrop
	//<
    reorderOnDrop:true,

    //>	@attr	toolbar.tabWithinToolbar   (boolean : true : IRWA)
    //      Should each button in the toolbar be included in the tab-order for the page, or
    //      should only one button in the toolbar show up in the tab-order, and arrow-keys be
    //      used to switch focus within the toolbar?
	//<
    tabWithinToolbar:true,
    

    

	//>	@attr	toolbar.buttonDefaults		(object : varies : [IRWA])
    // Settings to apply to all buttons of a toolbar. Properties that can be applied to
    // button objects can be applied to all buttons of a toolbar by specifying them in
    // buttonDefaults using the following syntax:<br>
    // <code>buttonDefaults:{property1:value1, property2:value2, ...}</code><br>
    // See the Button Widget Class for standard button properties.
	//		@group	appearance
	//      @see class:Button
    //      @visibility external
	//<
	//	The following are defaults for all toolbar buttons.
	//	To add properties to all buttons of ALL toolbars, change the below.
	//	To add properties to all buttons of a particular toolbar you're creating,
	//		add a "button" property to the toolbar constructor with the defaults
	//		you want applied to the buttons.  This will automatically be added to each button.
	buttonDefaults: {
		click : function() {
            this.Super("click", arguments);
			this.parentElement.itemClick(this, this.parentElement.getButtonNumber(this))
		},
        setSelected : function() {
            var oldState = this.isSelected();
            this.Super("setSelected", arguments);
            if (oldState != this.isSelected()) {
                if (this.isSelected()) this.parentElement.buttonSelected(this);
                else this.parentElement.buttonDeselected(this);
            }
        },
        dragAppearance:isc.EventHandler.NONE,

        // Toolbars typically manipulate the tabIndex of their buttons.
        // If the user specifies a tabIndex on a toolbar button directly, assume they are
        // managing the tabIndex for the button - clear the flag that marks the button as having 
        // it's tabIndex managed by the toolbar
        setTabIndex : function (index) {
            this.Super("setTabIndex", arguments);
            this._toolbarManagedTabIndex = null;
        },
        
        // Override setAccessKey to take a second parameter, indicating that the accessKey is
        // being set by the toolbar
        // If this parameter is not passed in, assume the user / developer is setting the
        // accessKey and clear the flag that marks the button's accessKey as being managed by
        // the toolbar
        setAccessKey : function (accessKey, managedByToolbar) {
            if (!managedByToolbar) this._toolbarManagedAccessKey = null;
            this.Super("setAccessKey", [accessKey]);
        },
        
        // When focus goes to a button, set the tabIndex of the button to the toolbars tabIndex.
        // This means when tabbing out of the button, the focus will go to the appropriate next
        // element - use the _updateFocusButton() method on the toolbar to achieve this.        
        focusChanged : function (hasFocus) {
            if (this.hasFocus) this.parentElement._updateFocusButton(this)
        },
            
        _focusInNextTabElement : function (forward, mask) {
            this.parentElement._focusInNextTabElement(forward, mask, this); 
        }
	}
});


isc.Toolbar.addMethods({

//>	@method	toolbar.draw()	(A)
//	Override the draw method to set up the buttons first
//		@group	drawing
//<
draw : function (a,b,c,d) {
    if (isc._traceMarkers) arguments.__this = this;

	if (!this.readyToDraw()) return this;

    // If we've never init'd our buttons, do so now by calling setButtons with no parameters
	if (!this._buttonsInitialized) this.setButtons();
    
	this.invokeSuper(isc.Toolbar, "draw", a,b,c,d);
},


//>	@method	toolbar.keyPress()
// Override keypress to allow navigation between the buttons on the toolbar
//		@group	events
//<
// Note - this is typically going to be bubbled up from the menu bar buttons
keyPress : function () {
    var keyName = this.ns.EH.lastEvent.keyName;
    // note - if we're allowing the user to tab between the buttons on the toolbar, we don't need
    // to give them the navigation via arrow keys.
    if (!this.tabWithinToolbar) {
        if ((this.vertical && keyName == "Arrow_Up") || 
            (!this.vertical && keyName == "Arrow_Left")) {
            
            this._focusInNextButton(false);
            return false;

        } else if ((this.vertical && keyName == "Arrow_Down") || 
                   (!this.vertical && keyName == "Arrow_Right")){
            this._focusInNextButton();
            return false;
        }
    }
    
    return this.Super("keyPress", arguments);
},

_focusInNextButton : function (forward, startingIndex) {
    
    // Note - this.buttons is the list of button init objects.  The live widgets are available
    // via this.getMembers()
    forward = (forward != false);
    var focusIndex = (startingIndex != null ? startingIndex : this.getFocusButtonIndex());
    if (focusIndex == null) focusIndex = (forward ?  -1 : this.buttons.length);

    // find the next focusable member in this direction, if any
    focusIndex += forward ? 1 : -1;
    while (focusIndex >=0 && focusIndex < this.buttons.length) {
        var button = this.getMembers()[focusIndex]; 
        if (button._canFocus()) {
            button.focus();
            // Returning true will indicate successful shift of focus
            return true;
        }
        focusIndex += forward ? 1 : -1;
    }
    return false;
},

//> @method toolbar.getFocusButtonIndex()  (A)
//  @return (number)    Index of whichever button currently has focus for keyboard input
//                      [On a mouse click, this will typically match the value returned by
//                      toolbar.getMouseOverButtonIndex(), but is likely to differ if the button
//                      was activated by keyboard interaction]
//<
getFocusButtonIndex : function () {
    
    var buttons = this.getButtons(),
        focusItemNum;
    for (var i = 0; i < buttons.length; i++) {
        if (buttons[i].hasFocus) {
            focusItemNum = i;
            break;
        }
    }
    return focusItemNum;
},

// _focusInNextTabElement() - used when we're managing synthetic focus due to showing a 
// clickMask.
// Since we do custom management of our buttons' tabIndices, we need to also explicitly 
// manage synthetic tabbing to them

_focusInNextTabElement : function (forward, mask, button) {
    if (!isc.EH.targetIsMasked(this, mask)) {
        var focusButton = button ? this.members.indexOf(button) : null;
        
        if (!this.tabWithinToolbar) {
            if (forward && focusButton == null) { 
                var fb = this._currentFocusButton;
                if (fb != null) return this.fb.focus();
            }

        } else if (this._focusInNextButton(forward, focusButton)) return;
    }
    return this.Super("_focusInNextTabElement", arguments);   
},

// Widget level _canFocus
// Override this to return true. This will ensure that if a hard mask is showing, and we're 
// doing synthetic tab index management, the toolbar doesn't get skipped.
_canFocus : function (a,b,c,d) {
    var members = this.members;
    if (members && members.length > 0) {
        for (var i = 0; i < members.length; i++) {
            if (members[i]._canFocus()) return true;
        }
    }
    return this.invokeSuper(isc.Toolbar, "_canFocus", a,b ,c,d);
},

// Override focus() to put focus into the button(s) in the toolbar

// Override 'setFocus()' to update button focus only.

setFocus : function (hasFocus) {
    
    if (!this._readyToSetFocus()) return;
    var buttonIndex = this.getFocusButtonIndex();
            
    if (!hasFocus) {
        if (buttonIndex != null && this.members) this.members[buttonIndex].setFocus(false);
    } else {
        // If one of our buttons already has focus, just no op.
        if (buttonIndex != null) return;
        
        if (this._currentFocusButton) this._currentFocusButton.setFocus(true);
        else this._focusInNextButton();
    }
},

// Override focusAtEnd() so we can put focus into the first / last button if appropriate
focusAtEnd : function (start) {
    // typecast start to a boolean before passing it to 'focusInNextButton' as the 'forward' 
    // param.
    start = !!start;
    var focusIndex = (start ?  -1 : this.buttons.length);
    this._focusInNextButton(start, focusIndex);
},

// An internal method to set the tab index of a button, and flag the button as having it's tab index
// managed by the toolbar.
_setButtonTabIndex : function (button, newTabIndex) {

    
    if (!button._toolbarManagedTabIndex && 
        (button._getNextTabWidget() != null || button._getPreviousTabWidget() != null)) 
    {
         button._removeFromAutoTabOrder();
    }         
    
    // Note that the toolbar is managing the tab index of the button
    button._toolbarManagedTabIndex = true;
    
    // update the tab index of the button.
    
    if (button.tabIndex != newTabIndex) button._setTabIndex(newTabIndex, false);
},

// Override updateMemberTabIndex (inherited from Layout)
// to be a No-Op, since we manage our members' (buttons') tabindices

updateMemberTabIndex : function () {
},


_slotChildrenIntoTabOrder : function () {
},

// _setButtonAccessKey()
// Internal method to set the accessKey for a button within this toolbar.
// Also sets the flag '_toolbarManagedAccessKey' on the button
_setButtonAccessKey : function (button, key) {
    button._toolbarManagedAccessKey = true;
    // see comment in the override for setAccessKey for why we're passing in this 2nd parameter
    button.setAccessKey(key, true);
},

    

// setupButtonFocusProperties()
// An internal method to set the tab indexes of any buttons in the toolbar without existing 
// user-specified tab indexes
setupButtonFocusProperties : function () {

    // first update the 'currentFocusButton' if its out of date.
    // This will set the tabIndex and accessKey for the button (unless that would override an
    // explicitly specified property for the button).
    
    // Note - this.buttons is the list of button init objects.
    // The actual button objects are available via this.getButtons()

    var focusButton = this._currentFocusButton; 
   
    if ( (!focusButton || !isc.isA.Canvas(focusButton) || 
          !focusButton.isVisible() ) && this.buttons.length > 0) 
    {
        this._updateFocusButton(this.members[0])
    }

    
    var defaultTabIndex;
    if (this.tabWithinToolbar) {
        defaultTabIndex = this.getTabIndex();
    } else {
        defaultTabIndex = -1;
    }