statefulcanvas.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	StatefulCanvas
// A component that has a set of possible states, and which presents itself differently according to
// which state it is in.  An example is a button, which can be "up", "down", "over" or "disabled".
// 
// @treeLocation Client Reference/Foundation
// @visibility external
//<
isc.ClassFactory.defineClass("StatefulCanvas", "Canvas");

	//>	@groupDef	state
	// Change of state and it's consequences for presentation.
	//<
isc.StatefulCanvas.addClassProperties({

	//>	@type	State
    // Constants for the standard states for a StatefulCanvas.  
	//			@group	state
	STATE_UP:"",				//	@value	StatefulCanvas.STATE_UP         state when mouse is not acting on this StatefulCanvas
	STATE_DOWN:"Down",			//	@value	StatefulCanvas.STATE_DOWN       state when mouse is down
    STATE_OVER:"Over",			//	@value	StatefulCanvas.STATE_OVER		state when mouse is over
    STATE_DISABLED:"Disabled",	//	@value	StatefulCanvas.STATE_DISABLED	disabled
    // @visibility external
	//<
	
	//>	@type	SelectionType	
    // Controls how an object changes state when clicked
	// @group	state
	// @group	event handling
    //	@value	StatefulCanvas.BUTTON	object moves to "down" state temporarily (normal button) 
    //	@value	StatefulCanvas.CHECKBOX object remains in "down" state until clicked again (checkbox)
    //	@value	StatefulCanvas.RADIO	object moves to "down" state, causing another object to go up (radio)
	BUTTON:"button",	
	CHECKBOX:"checkbox",
	RADIO:"radio",		
    // @visibility external
	//<	
	
	//>	@type	Selected
	//			@group	state
    FOCUSED:"Focused",          //  @value  StatefulCanvas.FOCUSED  StatefulCanvas should show
                                // focused state  
	SELECTED:"Selected",		//	@value	StatefulCanvas.SELECTED		StatefulCanvas is selected
	UNSELECTED:"",				//	@value	StatefulCanvas.UNSELECTED   StatefulCanvas is not selected
	// @visibility external
	//<	
    
    // Internal map of radioGroup ID's to arrays of widgets
    _radioGroups:{}
});


isc.StatefulCanvas.addProperties({

    //>	@attr	statefulCanvas.title		(string : varies : [IRW])
    // The text title to display in this button.
    // @group basics
    // @visibility external
    //<
    
    //>@attr StatefulCanvas.hiliteAccessKey (boolean : null : [IRWA])
    // If set to true, if the +link{statefulCanvas.title, title} of this button contains the
    // specified +link{canvas.accessKey, accessKey}, when the title is displayed to the user
    // it will be modified to include HTML to underline the accessKey.<br>
    // Note that this property may cause titles that include HTML (rather than simple strings)
    // to be inappropriately modified, so should be disabled if your title string includes
    // HTML characters.
    // @visibility internal
    //<
								
    // State-related properties
    // -----------------------------------------------------------------------------------------------

    //>	@attr	statefulCanvas.redrawOnStateChange		(boolean : false : IRWA)
	// Whether this widget needs to redraw to reflect state change
	// @group	state
    // @visibility external
	//<

    //>	@attr	statefulCanvas.selected		(boolean : false : IRW)
	// Whether this component is selected.  For some components, selection affects appearance.
	// @group	state
    // @visibility external
	//<

    //>	@attr	statefulCanvas.state		(State : "" : IRWA)
	// Current "state" of this widget. StatefulCanvases will have a different appearance based
    // on their current state. By default this is handled by changing the css className applied to
    // the StatefulCanvas - see +link{StatefulCanvas.baseStyle} for a description of how this is
    // done.<P>
    // For +link{class:Img} or +link{class:StretchImg} based subclasses of StatefulCanvas, the 
    // appearance may also be updated by changing the src of the rendered image. See
    // +link{Img.src} and +link{StretchImgButton.src} for a description of how the URL 
    // is modified to reflect the state of the widget in this case.
    // 
    // @see type:State
    // @see group:state
	// @group	state
    // @visibility external
	//<
	state:"",

    //>	@attr	statefulCanvas.showRollOver		(boolean : false : IRW)
	// Should we visibly change state when the mouse goes over this object?
	// @group	state
    // @visibility external
	//<	

    //>	@attr	statefulCanvas.showFocus        (boolean : false : IRW)
	// Should we visibly change state when the canvas recieves focus?  Note that by default the
    // <code>over</code> state is used to indicate focus.
	// @group	state
    // @deprecated as of SmartClient version 6.1 in favor of +link{statefulCanvas.showFocused}
    // @visibility external
	//<	

    //>	@attr	statefulCanvas.showFocused        (boolean : false : IRW)
	// Should we visibly change state when the canvas recieves focus?  If
    // +link{statefulCanvas.showFocusedAsOver} is <code>true</code>, the <b><code>"over"</code></b>
    // will be used to indicate focus. Otherwise a separate <b><code>"focused"</code></b> state
    // will be used.
	// @group	state
    // @visibility external
	//<

    //> @attr statefulCanvas.showFocusedAsOver (boolean : true : IRW) 
    // If +link{StatefulCanvas.showFocused,showFocused} is true for this widget, should the 
    // <code>"over"</code> state be used to indicate the widget as focused. If set to false,
    // a separate <code>"focused"</code> state will be used.
    // @group state
    // @visibility external
    //<
    showFocusedAsOver: true,
    
    
    
	//>	@attr	statefulCanvas.showDown		(boolean : false : IRW)
	// Should we visibly change state when the mouse goes down in this object?
	//		@group	state
    // @visibility external
	//<	

	//>	@attr	statefulCanvas.showDisabled  (boolean : true : IRW)
	// Should we visibly change state when disabled?
	//		@group	state
    // @visibility external
	//<	
    showDisabled:true,

	//>	@attr	statefulCanvas.actionType		(SelectionType : "button": IRW)
	// Behavior on state changes -- BUTTON, RADIO or CHECKBOX
	//		@group	state
	//		@group	event handling
    //      @setter setActionType()
    //      @getter getActionType()
    // @visibility external
	//<
    actionType:"button",
    
	//>	@attr	statefulCanvas.radioGroup   (string : null : IRWA)
	// String identifier for this canvas's mutually exclusive selection group.
	//		@group	state
	//		@group	event handling
    // @visibility external
	//<

	//>	@attr	statefulCanvas.baseStyle		(CSSStyleName : null : IRW)
	// Base CSS style.  As the component changes state and/or is selected, suffixes will be
    // added to the base style.
    // <P>
    // When the component changes state (eg becomes disabled), a suffix will be appended to this
    // style name, reflecting the following states: "Over", "Down", or "Disabled".
    // <P>
    // If the widget is selected, the suffixes will be "Selected", "SelectedOver", etc.
    // <P>
    // If the widget has focus and +link{StatefulCanvas.showFocused} is true, and
    // +link{StatefulCanvas.showFocusedAsOver} is false, the suffixes will be "Focused",
    // "FocusedOver", etc, or if the widget is both selected and focused, "SelectedFocused",
    // "SelectedFocusedOver", etc.
    // <P>
    // For example, if <code>baseStyle</code> is set to "button", this component is
    // +link{isSelected,selected} and the mouse cursor is over this component, the style
    // "buttonSelectedOver" will be used. 
    // 
    // @visibility external
	//<							
			
    // don't set className on the widget's handle, because we apply styling to another element
    suppressClassName:true,
	
	//>	@attr	statefulCanvas.cursor		(Cursor : Canvas.ARROW : IRW)
	//			Specifies the cursor to show when over this canvas.
	//			See Cursor type for different cursors.
	//		@group	cues
	//		@platformNotes	Nav4	Cursor changes are not available in Nav4
	//<
	cursor:isc.Canvas.ARROW,

    //>	@attr	statefulCanvas._savedCursor		(Cursor : null : IRWA)
	//			Any special cursor for this canvas is deactivated when this
	//			canvas is disable()'d. So, we keep that cursor setting here
	//			so that if and when the canvas is enabled() once again, it
	//			will have the proper cursor.
	//		@group	state, event handling
	//<		
	//_savedCursor:null,

    // Image-based subclasses
    // ---------------------------------------------------------------------------------------
    capSize:0,

    //> @attr statefulCanvas.showTitle (boolean : false : [IRWA])
    // Determines whether any specified +link{statefulCanvas.getTitle(), title} will be 
    // displayed for this component.<br>
    // Applies to Image-based components only, where the title will be rendered out in a label
    // floating over the component
    // @visibility internal
    //<
    // Really governs whether a label canvas is created to contain the title.
    // Exposed on img based subclasses only as some statefulCanvas subclasses will support
    // displaying the title without a label canvas
    //showTitle:false,

    //>	@attr	statefulCanvas.align		(Alignment : isc.Canvas.CENTER : [IRW])
    // Horizontal alignment of this component's title.
    // @group appearance
    // @visibility external
    //<
	align:isc.Canvas.CENTER,

    //>	@attr	statefulCanvas.valign		(VerticalAlignment : isc.Canvas.CENTER : [IRW])
    // Vertical alignment of this component's title.
    // @group appearance
    // @visibility external
    //<
	valign:isc.Canvas.CENTER,

    //> @attr StatefulCanvas.autoFit  (boolean : null : IRW)
    // If true, ignore the specified size of this widget and always size just large
    // enough to accomodate the title.  If <code>setWidth()</code> is explicitly called on an
    // autoFit:true button, autoFit will be reset to <code>false</code>.
    // <P>
    // Note that for StretchImgButton instances, autoFit will occur horizontally only, as 
    // unpredictable vertical sizing is likely to distort the media. If you do want vertical 
    // auto-fit, this can be achieved by simply setting a small height, and having 
    // overflow:"visible"
    // @setter StatefulCanvas.setAutoFit()
    // @group sizing
    // @visibility external
    //<
    //autoFit:null
    
    // autoFitDirection: Undocumented property determining whether we should auto-fit
    // horizontally, vertically or in both directions
    // Options are "both", "horizontal", "vertical"
    autoFitDirection:isc.Canvas.BOTH,

    //        
    // Button properties - managed here and @included from Button, ImgButton and
    // StatefulImgBuggon
	// =================================================================================
    
    // Icon (optional)
	// ---------------

    //> @attr statefulCanvas.icon           (SCImgURL : null : [IR])
    // Optional icon to be shown with the button title text.  
    // <P>
    // Specify as the partial URL to an image, relative to the imgDir of this component.
    // @group buttonIcon
    // @visibility external
    //<

    //> @attr statefulCanvas.iconSize       (integer : 16 : [IR])
    // Size in pixels of the icon image.
    // <P>
    // The <code>iconWidth</code> and <code>iconHeight</code> properties can be used to
    // configure width and height separately.
    //
    // @group buttonIcon
    // @visibility external
    //<
    iconSize:16,
    
    //> @attr statefulCanvas.iconWidth      (integer : null : [IR])
    // Width in pixels of the icon image.
    // <P>
    // If unset, defaults to <code>iconSize</code>
    //
    // @group buttonIcon
    // @visibility external
    //<

    //> @attr statefulCanvas.iconHeight     (integer : null : [IR])
    // Height in pixels of the icon image.
    // <P>
    // If unset, defaults to <code>iconSize</code>
    //
    // @group buttonIcon
    // @visibility external
    //<

    //> @attr statefulCanvas.iconOrientation     (string : "left" : [IR])
    // If this button is showing an icon should it appear to the left or right of the title?
    // valid options are <code>"left"</code> and <code>"right"</code>.
    //
    // @group buttonIcon
    // @visibility external
    //<
    iconOrientation:"left",

    //> @attr statefulCanvas.iconAlign     (string : null : [IR])
    // If this button is showing an icon should it be right or left aligned?
    //
    // @group buttonIcon
    // @visibility internal
    //<
    // Behavior is as follows - if iconOrientation and iconAlign are both left or both right we
    // write the icon out at the extreme right or left of the button, and allow the title to 
    // aligned independantly of it. (otherwise the icon and the text will be adjacent, and 
    // aligned together based on the button's "align" property.
    

    //> @attr statefulCanvas.iconSpacing   (integer : 6 : [IR])
    // Pixels between icon and title text.
    //
    // @group buttonIcon
    // @visibility external
    //<
    iconSpacing:6,

    // internal: controls whether we apply any state to the icon at all 
    showIconState: true,

    //> @attr statefulCanvas.showDisabledIcon   (boolean : true : [IR])
    // If using an icon for this button, whether to switch the icon image if the button becomes
    // disabled.
    //
    // @group buttonIcon
    // @visibility external
    //<
    showDisabledIcon:true,

    //> @attr statefulCanvas.showRollOverIcon   (boolean : false : [IR])
    // If using an icon for this button, whether to switch the icon image on mouse rollover.
    //
    // @group buttonIcon
    // @visibility external
    //<
    
    //> @attr statefulCanvas.showDownIcon       (boolean : false : [IR])
    // If using an icon for this button, whether to switch the icon image when the mouse goes
    // down on the button.
    //
    // @group buttonIcon
    // @visibility external
    //<

    //> @attr statefulCanvas.showSelectedIcon   (boolean : false : [IR])
    // If using an icon for this button, whether to switch the icon image when the button
    // becomes selected.
    //
    // @group buttonIcon
    // @visibility external
    //<
    
    //> @attr StatefulCanvas.showFocusedIcon (boolean : false : [IR])
    // If using an icon for this button, whether to switch the icon image when the button
    // recieves focus.
    // <P>
    // If +link{statefulCanvas.showFocusedAsOver} is true, the <code>"Over"</code> icon will be
    // displayed when the canvas has focus, otherwise a seperate <code>"Focused"</code> icon
    // will be displayed
    // @group buttonIcon
    // @visibility external
    //<