canvas.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	Canvas
//
//		Canvas is the base abstraction for cross-browser DHTML drawing.
//		All DHTML widgets inherit from the Canvas class.
//
//  @treeLocation Client Reference/Foundation
//  @visibility external
//<

// declare the class itself
isc.ClassFactory.defineClass("Canvas");

// for speed, override the default isA function provided by ClassFactory.  The marker property
// "_isA_Canvas" is added below as both a class and instance property.
// Note that this approach could be extended to all classes via generating unique marker
// properties (so that iterating up the inheritance chain would not be required) but that would
// slow down init time, and isA.Canvas is 99% of the critical path usage anyway
isc.isA.Canvas = function (object) { return (object != null && object._isA_Canvas); }

// define groups for documentation purposes

	//>	@groupDef positioning
	//	Horizontal and vertical location on the page
	//<
	//>	@groupDef visibility
	//	Whether an object can be seen
	//<
	//>	@groupDef sizing
	// Width and height of an object
	//<
	//>	@groupDef appearance
	// Properties defining an object's apperance
	//<
	//>	@groupDef drawing
	// Rendering an object on the page
	//<
	//>	@groupDef zIndex
	// Object's "stacking order" above or below other objects
	//<
	//>	@groupDef scrolling
	// Scrolling and clipping of objects when part of the object is obscured
	//<
	//>	@groupDef events
	// Handling mouse and keyboard events generated by the user
	//<
	//>	@groupDef containment
	// Canvases containing other objects as children or peers
	//<
	//>	@groupDef cues
	// Visual hints for the user that something can be done to this object
	//<
	//>	@groupDef dragdrop
	// Dragging objects and dropping them onto other objects
	//<
	//>	@groupDef image
	// Utilities to render images
	//<
	//>	@groupDef images
	// Refering to and loading images.
    // <P>
	// The two main URL settings relevent to loading images are:<br>
	// * imgDir (where application-specific images live)<br>
	// * skinImgDir (where system supplied images live)<br>
	//<
    //> @groupDef skins
    // Properties used to manage to the the overall appearance of the application.
    // <P>
    // A "skin" consists of 
    // <ul>
    // <li><code>skin_styles.css</code>: a .css file defining the set of 
    //     classes to apply to SmartClient components' visual elements</li>
    // <li><code>images/</code>: a directory of image files used as part of visual 
    //     components</li>
    // <li><code>load_skin.js</code>: a .js file containing overrides for various 
    //     SmartClient component properties that affect the appearance of those components.</li>
    // </ul>
    // Skins are loaded via the <code>skin</code> attribute of the +link{group:loadISCTag} or 
    // by including the appropriate <code>load_skin.js</code> source file with a standard script
    // include tag.
    // <P>
    // To create a custom skin, we suggest making a complete copy of an existing skin, then
    // modifying the media, css class definitions and component property overrides you wish to
    // change.
    // <P>
    // Note that the <code>load_skin.js</code> file contains a +link{Page.setSkinDir()} 
    // directive to set up the skin dir (used to ensure media is retrieved from the appropriate
    // directory), and a +link{Page.loadStyleSheet()} directive to load the .css file.
    // <P>
    // See the +link{group:skinning,Skinning Overview} for more information. 
    //
    // @see group:appearance
    // @see group:images
    // @see group:files
    //<
	//>	@groupDef files
	// Refering to and loading other files.
    // <P>
	// The two main URL settings relevant to file loading are:<br>
	// * appDir  (where application-specific files live)<br>
	// * isomorphicDir (where system supplied files live)<br>
	//<

	//>	@groupDef utils
	// Misc utilities
    // @visibility internal
	//<
	//>	@groupDef form
	// Utilities to deal with forms and form elements.<P>
    //
    // Internal because DynamicForm exposes the functionality we support for forms - dealing with
    // forms directly is a minefield.
    // @visibility internal
	//<
	//>	@groupDef handles
	// Pointers to the DOM structures of objects that have been drawn
    // @visibility internal
	//<


//	Add class-level properties
//		You can access these properties on the static class object.
//		e.g.,	Canvas.myStaticProperty

isc.Canvas.addClassProperties({
    

    _isA_Canvas : true,

	//	Class constants
	AUTO:"auto",				//=	@const	isc.Canvas.AUTO			The "use default" setting.
	ANYTHING:"**anything**",	//=	@const	isc.Canvas.ANYTHING		Generally means "any value is acceptible".


	//>	@type	Positioning
	//			@visibility external
	//			@group	positioning
	ABSOLUTE:"absolute",		//	@value	isc.Canvas.ABSOLUTE		The canvas is absolutely positioned with respect to its parentElement.
	RELATIVE:"relative",		//	@value	isc.Canvas.RELATIVE		The canvas is relatively positioned according to the document flow.
	//<
	
	//>	@type	Visibility
	//			@visibility external
	//			@group	visibility
	INHERIT:"inherit",			//	@value	isc.Canvas.INHERIT		The widget visibility will match that of its parent (usually visible).
	VISIBLE:"visible",			//	@value	isc.Canvas.VISIBLE		The widget will always be visible whether its parent is or not.
	HIDDEN:"hidden",			//	@value	isc.Canvas.HIDDEN		The widget will always be hidden even when its parent is visible.
	//<
    
	//>	@type	DrawnState
	//			@group	drawing
	COMPLETE:"complete",			
    //	@value	isc.Canvas.COMPLETE     the canvas is completely drawn, including children and peers, set up events, etc.
	DRAWN:"complete",			
    //	@value	isc.Canvas.DRAWN        the canvas is completely drawn (synonym for isc.Canvas.COMPLETE)
	DRAWING_HANDLE:"drawingHandle",			
    //	@value	isc.Canvas.DRAWING_HANDLE     the canvas is in the process of writing it's handle to the page / DOM
	HANDLE_DRAWN:"handleDrawn",			
    //	@value	isc.Canvas.HANDLE_DRAWN     the canvas has completely written its handle to DOM 
	UNDRAWN:"undrawn",			
    //	@value	isc.Canvas.UNDRAWN     the canvas has not been drawn
    //<
    
	//>	@type Overflow
	// @visibility external
	//			@group	sizing
	//	@value	Canvas.VISIBLE		Content that extends beyond the widget's width or height is
    //                              displayed.
    //                              Note: To have the content be sized only by the drawn size of 
    //                              the content set the overflow to be Canvas.VISIBLE and specify
    //                              a small size, allowing the size to expand to the size required
    //                              by the content.
    //                              Leaving the width / height for the widget undefined will use the
    //                              default value of 100, and setting the size to zero may cause the
    //                              widget not to draw.
	//	@value	Canvas.HIDDEN		Content that extends beyond the widget's width or height is
    //                              clipped (hidden).
	//	@value	Canvas.AUTO			Horizontal and/or vertical scrollbars are displayed only if
    //                              necessary. Content that extends beyond the remaining visible
    //                              area is clipped.
    //	@value	Canvas.SCROLL		Horizontal and vertical scrollbars are always drawn inside the
    //                              widget. Content that extends beyond the remaining visible area
    //                              is clipped, and can be accessed via scrolling.
	SCROLL:"scroll",			
    //	@value	Canvas.CLIP_H		Clip horizontally but extend the canvas's clip region
    //                              vertically if necessary.
	CLIP_H:"clip-h",			
    //	@value	Canvas.CLIP_V		Clip vertically but extend the canvas's clip region
    //                              horizontally if necessary. 
	CLIP_V:"clip-v",			
	//<

    

    //	@value	Canvas.IGNORE		Clipping is ignored by the ISC system. This setting may be used
    //                              for improved performance, with frequently-drawn widgets whose
    //                              dimensions always agree exactly with the size of their contents.
	IGNORE:"ignore",			

	//>	@type	ScrollMechanism
	//			@group	scrolling
	NATIVE:"native",
    //	@value	isc.Canvas.NATIVE   Scroll by "native" mechanism - assigning directly to scrollLeft
    //                              and scrollTop
	CLIP:"clip",				
    //	@value	isc.Canvas.CLIP     Scroll by repositioning / resizing handle and moving a clip
    //                              region as a viewport
	NESTED_DIV:"nestedDiv",				
    //	@value	isc.Canvas.NESTED_DIV   Scroll by moving a handle around within an outer handle.
    //<
    	
	//>	@type	Alignment
	CENTER:"center",			//	@value	isc.Canvas.CENTER		Center within container.
	LEFT:"left",				//	@value	isc.Canvas.LEFT			Stick to left side of container.
	RIGHT:"right",				//	@value	isc.Canvas.RIGHT		Stick to right side of container.
	// @group appearance
	// @visibility external
	//<
	
	//>	@type	VerticalAlignment
    //	@value	isc.Canvas.TOP			At the top of the container
	TOP:"top",
    //	@value	isc.Canvas.CENTER		Center within container.
    //	@value	isc.Canvas.BOTTOM       At the bottom of the container
	BOTTOM:"bottom",			
	// @group appearance
	// @visibility external
	//<

    //> @type Side
    // Side of a component.
	//	@value	isc.Canvas.LEFT			Left side
	//	@value	isc.Canvas.RIGHT		Right side
    //	@value	isc.Canvas.TOP			Top side
    //	@value	isc.Canvas.BOTTOM       Bottom side
	// @visibility external
    //<
	

	//>	@type	Direction
	//			@visibility external
	//			@group	appearance
    //	@value	isc.Canvas.UP           above
	UP:"up",

    //	@value	isc.Canvas.DOWN         below
	DOWN:"down",				
    //	@value	Canvas.LEFT			to the left of
    //	@value	Canvas.RIGHT		to the right of
	//<

    // other generic constants
    BOTH:"both",
    NONE:"none",
    VERTICAL:"vertical",
    HORIZONTAL:"horizontal",

	//>	@type	Cursor
    // 
    // You can use whatever cursors are valid for your deployment platforms, but keep in mind that
    // visual representation may vary by browser and OS.
    //
    //	@value	Canvas.DEFAULT		Use the default arrow cursor for this browser/OS.  
    //  @value  Canvas.AUTO         Use the default cursor for this element type in this browser/OS
    //	@value	Canvas.WAIT         Use the wait cursor.
    //	@value	Canvas.HAND			Use the hand cursor.
    //	@value	Canvas.MOVE			Use the "move" (crosshairs) cursor.
    //	@value	Canvas.HELP			Use the 'help' cursor.
    //	@value	Canvas.TEXT			Use the 'text' (i-beam) cursor.	
    //	@value	Canvas.CROSSHAIR	Use the 'crosshair' ( + ) cursor.	
    //	@value	"col-resize" 	    Use the column resize cursor (horizontal double-tipped arrow)
    //	@value	"row-resize" 	    Use the row resize cursor (vertical double-tipped arrow)
    //	@value	"e-resize" 	        Use the "east resize" cursor.
    //	@value	"w-resize" 	        Use the "west resize" cursor.
    //	@value	"n-resize" 	        Use the "north resize" cursor.
    //	@value	"s-resize" 	        Use the "south resize" cursor.
    //	@value	"se-resize" 	    Use the "south-east resize" cursor.
    //	@value	"ne-resize" 	    Use the "north-east resize" cursor.
    //	@value	"nw-resize" 	    Use the "north-west resize" cursor.
    //	@value	"sw-resize" 	    Use the "south-west resize" cursor.
    //  @value  "not-allowed"       Use the "not-allowed" cursor.
    //
	//  @group	cues
	//	@see	attr:Canvas.cursor
    //
	//  @visibility external
    //  @example cursors
    //<
    //	@value	Canvas.ARROW		Synonym for "default"
    // NOTE: there is a difference between Canvas.DEFAULT and Canvas.AUTO - auto is as if there
    // was no cursor specified - if the element has text in it, the I-Beam text selection cursor
    // will show up when the user rolls over it. If the cursor is set to 'default' however the
    // cursor will show the standard default cursor (arrow) over the entire element.
	DEFAULT:"default",
	ARROW:"default",

	WAIT:"wait",				
	HAND:(isc.Browser.isMoz ? "pointer" : "hand"),	
	MOVE:"move",				
	HELP:"help",				
	TEXT:"text",				
	CROSSHAIR:"crosshair",	
    // Used for no-drop indication - not supported on Safari
    
    NOT_ALLOWED:"not-allowed",	

    // NOTE: e-resize means "east resize".  On Windows, there's no distinction between east and west
    // resize (it's just horizontal resize), but on some OS' it may look directional, so we may need
    // to add a conditional to fall back to the "move" cursor on non-Windows platforms.