canvas.js

javascript 很酷的类库

    // consistent cross-browser layout and positioning semantics, use Canvas parents
    // (especially Layouts) and use absolute positioning at top level.
    // <P>
    // NOTE: persistence of drawContext: if a Canvas is clear()d and then draw()n again, it will
    // keep the same drawContext unless the <code>drawContext.position</code> was "replace".<P> 
    // If a Canvas is added as a child to Canvas parent, its drawContext will be dropped.
    // @group drawContext
    // @visibility drawContext
    //<

    
    
    // HTMLElement
    //> @attr canvas.htmlElement (HTML Element : null : IRWA) 
    // If specified as a pointer to an HTML element present in the DOM, this canvas will be
    // rendered inside that element on +link{Canvas.draw(), draw()}.
    // <P>
    // <i>NOTES:</i><br>
    // This feature is intended for temporary integration with legacy page architectures only;
    // the native browser's reaction to DOM insertion is unspecified and unsupported. For
    // consistent cross-browser layout and positioning semantics, use Canvas parents
    // (especially Layouts) and use absolute positioning at top level.
    // <P>
    // Persistence of htmlElement: If +link{canvas.htmlPosition} is set to <code>"replace"</code>
    // the htmlElement will be removed from the DOM when the canvas is drawn - therefore the
    // htmlElement attribute will be cleared at this time.
    // Otherwise if a Canvas is clear()d and then draw()n again it will 
    // be rendered inside the same htmlElement.<br>
    // If a Canvas is added as a child to Canvas parent, its htmlElement will be dropped.
    // <P>
    // +link{canvas.position} should typically be set to <code>"relative"</code> if the widget 
    // is to be rendered inline within a standard page. 
    // @group htmlElement, positioning
    // @visibility external
    //<
    
    
    //> @attr canvas.htmlPosition (DrawPosition : "afterBegin" : [IRWA])
    // If +link{canvas.htmlElement} is specified, this attribute specifies the position where 
    // the canvas should be inserted relative to the <code>htmlElement</code> in the DOM.
    // @group htmlElement, positioning
    // @visibility external
    //<
    htmlPosition:"afterBegin",
    
    //> @attr canvas.matchElement (boolean : null : [IRWA])
    // If +link{canvas.htmlElement} is specified, should this canvas initially be drawn
    // at the same dimensions as the htmlElement?<br>
    // Note: setting this property will not force the canvas to resize if the element
    // subsequently resizes (for example due to page reflow).
    // @visibility external
    //<
    
    // Positioning
	// --------------------------------------------------------------------------------------------

    //>	@attr	canvas.position		(Positioning : null : IRWA)
    // Absolute or relative, corresponding to the "absolute" (with respect to parent) or
    // "relative" (with respect to document flow) values for the CSS position attribute. 
    // <P>
    // Defaults to "absolute" unless +link{canvas.htmlElement} has been set, in which case
    // "relative" is used.
    // <P>
    // For best consistency and flexibility across browsers, all SmartClient layout managers
    // use absolute positioning.  Relative positioning should be used only as a short-term
    // integration scenario while incrementally upgrading existing applications.  
    // <P>
    // When relative positioning is used, only the outermost SmartClient component should have
    // position:"relative" set, none of it's children should.
    //
    // @visibility external
    // @group positioning
    // @example inlineComponents
    //<
	position:null,

    //>	@attr	canvas.left		(number : 0 : IRW)
    // Number of pixels the left side of the widget is offset to the right from its default
    // drawing context (either its parent's topleft corner, or the document flow, depending on
    // the value of the +link{position} property).
    //
    // @visibility external
    // @group  positioning
    //<
	left:0,

    //>	@attr	canvas.top		(number : 0 : IRW)
    // Number of pixels the top of the widget is offset down from its default drawing context
    // (either its parent's top-left corner, or the document flow, depending on the value of
    // the +link{position} property).
    //
    // @visibility external
    // @group  positioning
    //<
	top:0,

    // Sizing
	// --------------------------------------------------------------------------------------------

    // Notes on width/height vs defaultWidth/defaultHeight:
    //
    // Layouts will resize widgets that don't have their height/width explicitly set.
    // Important to use defaultHeight/defaultWidth to set defaults for a widget, otherwise the
    // defaults will be taken to be the "fixed" size of the widget, and its size will not be
    // managed by layouts
    // In some cases, we WANT certain dimensions to be regarded as fixed by a Layout (they may
    // still be overriden by the user) so we set the height/width properties

    //>	@attr	canvas.width		(Number or String : null : [IRW])
    // Size for this component's horizontal dimension.
    // <P>
    // Can be a number of pixels, or a percentage like "50%". Percentage sizes are resolved to
    // pixel values as follows:
    // <UL>
    // <LI>If a canvas has a specified +link{canvas.percentSource,percentSource}, sizing will be
    //     a percentage of the size of that widget (see also +link{canvas.percentBox}).</LI>
    // <LI>Otherwise, if a canvas has a +link{canvas.masterElement,masterElement}, and
    //     +link{Canvas.snapTo,snapTo} is set for the widget, sizing will be a percentage of
    //     the size of that widget (see also +link{canvas.percentBox}).</LI>
    // <LI>Otherwise if this is a child of some other canvas, percentages will be based on the 
    //     inner size of the +link{canvas.parentElement,parentElement}'s viewport.</LI>
    // <LI>Otherwise, for top level widgets, sizing is calculated as a percentage of page size.</LI>
    // </UL>
    // <P>
    // +link{Layout,Layouts} may specially interpret percentage sizes on their children,
    // and also allow "*" as a size.
    // <P>
    // Note that if +link{Canvas.overflow,overflow} is set to "visible", this size is a
    // minimum, and the component may overflow to show all content and/or children.
    // <P>
    // If trying to establish a default width for a custom component, set
    // +link{Canvas.defaultWidth,defaultWidth} instead.
    //
    //  @visibility external
    //  @group	sizing
    //  @setter setWidth
    //  @getter getWidth
    //<

    //>	@attr	canvas.height		(Number or String : null : [IRW])
    // Size for this component's vertical dimension.
    // <P>
    // Can be a number of pixels, or a percentage like "50%". See documentation for
    // +link{canvas.width} for details on who percentage values are resolved actual size.
    // <P>
    // Note that if +link{Canvas.overflow,overflow} is set to "visible", this size is a
    // minimum, and the component may overflow to show all content and/or children.
    // <P>
    // If trying to establish a default height for a custom component, set
    // +link{Canvas.defaultHeight,defaultHeight} instead.
    //
    //  @visibility external
    //  @group	sizing
    //  @setter setHeight
    //  @getter getHeight
    //<
    
    
    //>	@attr canvas.defaultWidth (Number : 100 : IRWA)
    // For custom components, establishes a default width for the component.
    // <P>
    // For a component that should potentially be sized automatically by a Layout, set this
    // property rather than +link{width} directly, because Layouts regard a width setting as
    // an explicit size that shouldn't be changed.
    //
    //  @visibility external
	//  @group	sizing
	//<
    defaultWidth:100,

    //>	@attr canvas.defaultHeight (Number : 100 : IRWA)
    // For custom components, establishes a default height for the component.
    // <P>
    // For a component that should potentially be sized automatically by a Layout, set this
    // property rather than +link{height} directly, because Layouts regard a height setting as
    // an explicit size that shouldn't be changed.
    //
    //  @visibility external
	//  @group	sizing
	//<
    defaultHeight:100,

    //>	@attr	canvas.minWidth		(number : 10 : IRWA)
    // Minimum width that this Canvas can be resized to.
    // <P>
    // Note that a Canvas with overflow:"visible" has an implicit minimize size based on it's
    // contents.
    //
    //  @visibility external
	//  @group	sizing
	//<
	minWidth:10,

    //>	@attr	canvas.maxWidth		(number : 10000 : IRWA)
    // Maximum width that this Canvas can be resized to.
    //
    //  @visibility external
	//  @group	sizing
	//<
	maxWidth:10000,

    //>	@attr	canvas.minHeight		(number : 10 : IRWA)
    // Minimum height that this Canvas can be resized to.
    // <P>
    // Note that a Canvas with overflow:"visible" has an implicit minimize size based on it's
    // contents.
    //
    //  @visibility external
	//  @group	sizing
	//<
	minHeight:10,

    //>	@attr	canvas.maxHeight		(number : 10000 : IRWA)
    // Maximum height that this Canvas can be resized to.
    //
    //  @visibility external
	//  @group	sizing
	//<
	maxHeight:10000,

	// --------------------------------------------------------------------------------------------

	//>	@attr	canvas.allowNativeContentPositioning    (boolean : false : IRW)
    //  Allow HTML content which includes native elements that use relative or absolute positioning.
    //<
    

	//>	@attr	canvas.zIndex		(number : Canvas.AUTO | Canvas.AUTO : IRWA)
    //
    // Stacking order of this Canvas with respect to other content and components on the page.
    //
    // The default zIndex of "auto" means that a zIndex will be decided at draw time,
    // so that if many Canvii are draw with zIndex "auto", the last Canvas drawn is on top.
    // <p>
    // If you want native HTML content to appear in front of this canvas, set zIndex to zero.
    //
	// @group	zIndex
	// @value	(number)
	// @value	Canvas.AUTO
	//<
	zIndex:isc.Canvas.AUTO,

    //>	@attr	canvas.autoShowParent		(boolean : false : IRWA)
    //      If set to true, the widget's parent (if any) will automatically be shown whenever the
    //      widget is shown.
    //  @visibility external
    //  @group appearance
    //<
	autoShowParent:false,

    //>	@attr	canvas.visibility		(Visibility : isc.Canvas.INHERIT : IRW)
    //      Controls widget visibility when the widget is initialized. See Visibility type for
    //      details.
    //  @getter isVisible
    //  @setter show, hide
    //  @visibility external
    //  @group appearance
    //<
	visibility:isc.Canvas.INHERIT,

    //>	@attr	canvas.canSelectText		(boolean : false : IRWA)
	// Whether native drag selection of contained text is allowed within this Canvas.
    // <P>
    // Note that setting this property to <code>false</code> will not avoid text selection
    // which is initiated outside this Canvas from continuing into this Canvas, even if text
    // selection began in another Canvas.
    //
	//		@group	events
    // @visibility external
	//<

	//>	@type	CSSStyleName
    // CSS class name to apply to some HTML element on this page. This is a string that should
    // match the css class defined for the page in an external stylesheet or in inline 
    // html &lt;STYLE&gt; tags.
    // <P>
    // As a general rule, wherever it is possible to provide a CSS styleName (such as
    // +link{Canvas.styleName} or +link{Button.baseStyle}, your CSS style can specify border,
    // margins, padding, and any CSS attributes controlling background or text styling.  You
    // should not specify any CSS properties related to positioning, clipping, sizing or
    // visibility (such as "overflow", "position", "display", "visibility" and "float"), using
    // the SmartClient APIs for this kind of control.
    // <P>
    // Because text wrapping cannot be consistently controlled cross-browser from CSS alone,
    // you should use SmartClient properties such as +link{Button.wrap} instead of the
    // corresponding CSS properties, when provided.
    // <P>
    // Content contained within SmartClient components can use arbitrary CSS, with the 
    // caveat that the content should be tested on all supported browsers, just as content
    // outside of SmartClient must be.
    // 
	//	@group	appearance
	//	@visibility external
    //  @example consistentSizing
    //<
    
    //>	@attr	canvas.className		(CSSStyleName : "normal" : [IRW])
    //      The CSS class applied to this widget as a whole.
    //  @visibility external
    //  @group appearance
    // @deprecated In favor or +link{canvas.styleName} as of SmartClient release 5.5
    //<
    
    //>	@attr	canvas.styleName    (CSSStyleName : "normal" : [IRW])
    //      The CSS class applied to this widget as a whole.
    //  @group appearance
    //  @setter canvas.setStyleName()
    //  @visibility external
    //  @example styles
    //<
	styleName:"normal",

	//>	@attr	canvas.textDirection	(TextDirection : null : IRW)
	//			Use this to specify a text direction for the canvas: 
	//					Canvas.LTR (left to right, eg English)
	//					Canvas.RTL (right to left, eg Arabic)
	//			Leave as null to pick up the text direction automatically
	//			 from that set at the Page level, set to one of the above to override.
	//		@group	textDirection
	//		@platformNotes	IE only.
	//<

	//>	@attr	canvas.eventProxy		(canvas object : null : IRWA)
	//			set to another canvas to have that process events for us