canvas.js

javascript 很酷的类库

	//			useful for event processing of peers (borders, decorators, etc.)
	//		@group	events
	//<

    //>	@attr	canvas.contents		(string : "&nbsp;" : IRWA)
    // The contents of a canvas or label widget. Any HTML string is acceptable.
    //
    // @see dynamicContents
    // @group contents
    // @visibility external
    //<
	contents:isc.nbsp,

    //> @attr canvas.dynamicContents (boolean : false : IRWA)
    //
    // Dynamic contents allows the contents string to be treated as a simple, but powerful
    // template.  When this attribute is set to true, expressions of the form \${arbitrary JS
    // here} are replaced by the result of the evaluation of the JS code inside the curly
    // brackets.  This evaluation happens at draw time.  If you want to trigger a re-evaluation
    // of the expressions in the contents string you can call markForRedraw() on the canvas.
    // <p>
    // You can use this feature to build some simple custom components. For example, let's say
    // you want to show the value of a Slider in a Canvas somewhere on the screen.  You can do
    // this by observing the valueChanged() method on the slider and calling setContents() on
    // your canvas with the new string or you can set the contents of the canvas to something
    // like:
    // <p><code>
    // "The slider value is \${sliderInstance.getValue()}."
    // </code><p>
    // Next you set dynamicContents: true on the canvas, observe valueChanged() on the slider
    // and call canvas.markForRedraw() in that observation.  This approach is cleaner than
    // setContents() when the Canvas is aggregating several values or dynamic expressions.
    // Like so:
    // <p>
    // <pre>
    // Slider.create({
    //     ID: "mySlider"
    // });
    //
    // Canvas.create({
    //     ID: "myCanvas",
    //     dynamicContents: true,
    //     contents: "The slider value is \${mySlider.getValue()}."
    // });
    //     
    // myCanvas.observe(mySlider, "valueChanged", 
    //                  "observer.markForRedraw()");
    // </pre>
    // You can embed an arbitrary number of dynamic expressions in the contents string.  The
    // search and replace is optimized for speed.
    // <p>
    // If an error occurs during the evaluation of one of the expressions, a warning is logged
    // to the ISC Developer Console and the error string is embedded in place of the expected
    // value in the Canvas.
    // <p>
    // The value of a function is its return value.  The value of any variable is the same as
    // that returned by its toString() representation.
    // <p>
    // Inside the evalution contentext, <code>this</code> points to the canvas instance that
    // has the dynamicContents string as its contents - in other words the canvas instance on
    // which the template is declared.
    //
    // @see contents
    // @see canvas.dynamicContentsVars
    // @example dynamicContents
    // @group contents
    // @visibility external
	//<

    //> @attr canvas.dynamicContentsVars (ValueMap : null : IRWA)
    //
    // An optional map of name:value parameters that will be evailable within the scope of the
    // dynamicContents evaluation.  For example - if you have e.g:
    // <pre>
    // Canvas.create({
    //   dynamicContents: true,
    //   dynamicContentsVars: {
    //       name: "Bob"
    //   },
    //   contents: "hello \${name}"
    // });
    // </pre>
    // The above will create a canvas with contents <code>hello Bob</code>.  You can add, remove, and
    // change values in the dynamicContentsVars object literal, just call
    // <code>markForRedraw()</code> on the canvas to have the dynamicContents template re-evaluated.
    // <p>
    // Note that <code>this</code> is always evailable inside a dynamic contents string and points to
    // the canvas instance containing the dynamic contents.
    // <p>
    // Used only if +link{attr:Canvas.dynamicContents} : true has been set.
    //
    // @see dynamicContents
    // @visibility external
    //<



    // Per-Canvas CSS overrides.  
	// --------------------------------------------------------------------------------------------
    // Consider defining a style for the individual Canvas instead of using these overrides, since
    // this makes that Canvas skinnable from CSS.

	//>	@attr	canvas.margin		(number : null : [IRW])
    // Set the CSS Margin, in pixels, for this component.  Margin provides blank space outside
    // of the border.
    // <P>
    // This property sets the same thickness of margin on every side.  Differing per-side
    // margins can be set in a CSS style and applied via +link{styleName}.
    // <P>
    // Note that the specified size of the widget will be the size <b>including</b> the margin
    // thickness on each side.
    //
    //  @visibility external
	//  @group  appearance
	//<

	//>	@attr	canvas.padding		(number : null : [IRW])
    // Set the CSS padding of this component, in pixels.  Padding provides space between the
    // border and the component's contents.
    // <P>
    // This property sets the same thickness of padding on every side.  Differing per-side
    // padding can be set in a CSS style and applied via +link{styleName}.
    // <P>
    // Note that CSS padding does not affect the placement of +link{canvas.children}.  To
    // provide a blank area around children, either use +link{canvas.margin,CSS margins} or use
    // a +link{Layout} as the parent instead, and use properties such as
    // +link{layout.layoutMargin} to create blank space.
    //
    //  @visibility external
	//  @group  appearance
	//<

    //>	@attr	canvas.border		(string : null : [IRW])
    // Set the CSS border of this component, as a CSS string including border-width,
    // border-style, and/or color (eg "2px solid blue").
    // <P>
    // This property applies the same border to all four sides of this component.  Different
    // per-side borders can be set in a CSS style and applied via +link{styleName}.
    //
    //  @visibility external
	//  @group  appearance
	//<

    //>	@attr	canvas.backgroundColor		(string : null : [IR])
	// The background color for this widget. It corresponds to the CSS background-color
    // attribute. You can set this property to an RGB value (e.g. #22AAFF) or a named color
    // (e.g. red) from a list of browser supported color names.
    //
    //  @visibility external
	//  @group	appearance
	//<

	//>	@attr	canvas.backgroundImage		(SCImgURL : null : [IR])
	// URL for a background image for this widget (corresponding to the CSS "background-image"
    // attribute).
    //  @visibility external
	//  @group	appearance
	//<

    //>	@attr	canvas.backgroundRepeat		(BkgndRepeat : isc.Canvas.REPEAT : [IRW])
    //      Specifies how the background image should be tiled if this widget
    //      is larger than the image. It corresponds to the CSS background-repeat attribute.
    //      See BkgndRepeat type for details.
    //  @visibility external
	//  @group	appearance
    //<
	backgroundRepeat:isc.Canvas.REPEAT,
    
    //>	@attr	canvas.mozOutlineOffset (string : "-1px": [IRA])
    // Only applies to Moz Firefox 1.5 and above.
    // When this widget recieves focus, how far should the dotted focus outline appear from
    // the edge of the canvas. A negative value will render the dotted outline inside the
    // canvas 
    // @visibility internal
    //<
    mozOutlineOffset:"-1px",

    //>	@attr	canvas.mozOutlineColor (string : null : [IRA])
    // Only applies to Moz Firefox 1.5 and above.
    // When this widget recieves focus, what color should the dotted focus outline appear.
    // Unspecified by default - gives us the native browser behavior.
    // @visibility internal
    //<    
    //mozOutlineColor:null,
    
    // Skinning
	// --------------------------------------------------------------------------------------------

    //>	@attr	canvas.appImgDir		(URL : "" : IRWA)
	// Default directory for app-specific images, relative to the Page-wide
    // +link{Page.getAppImgDir(),appImgDir}.
    // @group images
    // @visibility external
	//<
	appImgDir:"",						

    //>	@attr	canvas.skinImgDir		(URL : "images/" : IRWA)
	// Default directory for skin images (those defined by the class), relative to the
    // Page-wide +link{Page.getSkinDir(),skinDir}.
    // @group images
    // @visibility external
	//<
	skinImgDir:"images/",				

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

    //>	@attr	canvas.cursor		(Cursor : Canvas.DEFAULT : IRWA)
    //      Specifies the cursor image to display when the mouse pointer is
    //      over this widget. It corresponds to the CSS cursor attribute. See Cursor type for
    //      different cursors.
    //  @visibility external
    //  @group  cues
    //  @example dragCreate
    //  @example cursors
    //<
	cursor:isc.Canvas.DEFAULT,
    
    //>	@attr	canvas.disabledCursor       (Cursor : Canvas.DEFAULT : IRWA)
    //      Specifies the cursor image to display when the mouse pointer is
    //      over this widget if this widget is disabled. It corresponds to the CSS cursor 
    //      attribute. See Cursor type for different cursors.
    //  @visibility external
    //  @group  cues
    //<
    disabledCursor:isc.Canvas.DEFAULT,
    
	//>	@attr	canvas.noDropCursor       (Cursor : Canvas.NOT_ALLOWED : IRWA)
    //      Specifies the cursor image to display when the user drags something over this widget
    //      after +link{this.setNoDropIndicator()} has been called.<br>
    //      Default cursor type <code>"not-allowed"</code> is not supported in Safari browsers.
    //      We therefore also provide the alternative +link{canvas.shouldSetNoDropTracker}
    //      no-drop indicator functionality.
    //  @group  cues
    //<
    noDropCursor:isc.Canvas.NOT_ALLOWED,
    
    //>	@attr	canvas.opacity		(number : null : IRWA)
    //      Renders the widget to be partly transparent. A widget's opacity property may
    //      be set to any number between 0 (transparent) to 100 (opaque).
	//		Null means don't specify opacity directly, 100 is fully opaque.
	//		Note that heavy use of opacity may slow down your browser.
	//		See canvas.setOpacity() for details.
    //  @visibility external
    //  @setter setOpacity()
	//  @group	cues
	//<
    
    
    //> @attr canvas.smoothFade (boolean : null : [IRWA])
    // Avoids a visible flash (native browser repaint) for canvases when setting opacity 
    // to / from 100% in  Mozilla browsers.
    // @visibility internal
    //<

    //>	@attr	canvas.overflow		(Overflow : Canvas.VISIBLE : [IRW])
    //			Controls what happens when the drawn size of the content of a Canvas is either
    //			greater or smaller than the specified size of the Canvas.  Similar to the CSS
    //			property overflow, but consistent across browsers.  See Overflow type for
    //			details.
    //  @visibility external
    //  @setter setOverflow()
	//  @group  sizing
	//<
	overflow:isc.Canvas.VISIBLE,			
    
    //>	@attr canvas.alwaysShowVScrollbar (boolean : false : [IRWA])
    // If this canvas has <code>overflow</code> set to <code>"auto"</code>, and is showing 
    // custom scrollbars, settting this property to true will ensure that a custom vertical
    // scrollbar is shown even if the scrollHeight of the widget is less than the specified
    // height
    //  @visibility internal
	//  @group  sizing
	//<
    
	alwaysShowVScrollbar:false,

    // Scrolling
	// --------------------------------------------------------------------------------------------

    

	//>	@attr	canvas.showCustomScrollbars		(boolean : true : IRWA)
    // Whether to use the browser's native scrollbars or SmartClient-based scrollbars.
    // <P>
    // SmartClient-based scrollbars are skinnable, giving you complete control over look and
    // feel.  SmartClient-based scrollbars also enable some interactions not possible with
    // native scrollbars, such as +link{ListGrid.fixedRecordHeights,variable height records}
    // in grids in combination with +link{listGrid.dataPageSize,data paging}.
    // <P>
    // Native browser scrollbars are slightly faster simply because there are less SmartClient
    // components that need to be created, drawn and updated.  Each visible SmartClient-based
    // scrollbar on the screen has roughly the impact of two StretchImgButtons.
    // <P>
    // SmartClient is always aware of the size of the scrollbar, regardless of whether native
    // or custom scrollbars are used, and regardless of what operating system and/or operating
    // system "theme" or "skin" is in use.  This means SmartClient will correctly report the
    // +link{canvas.getViewportHeight(),viewport size}, that is, the interior area of the
    // widget excluding space taken by scrollbars, which is key for exactly filling a component
    // with content without creating unnecessary scrolling.
    // <P>
    // The <code>showCustomScrollbars</code> setting is typically overridden in load_skin.js in
    // order to change the default for all SmartClient components at once, like so:
    // <pre>
    //     isc.Canvas.addProperties({ showCustomScrollbars:false });
    // </pre>
    //
	// @group scrolling
    // @visibility external
	//<
    showCustomScrollbars : 
    // NOTE: leading logical NOT, so the rest of this conditional specifies the conditions in which
    // we use native scrollbars
    !(
        // use native scrollbars on IE5+
        (isc.Browser.isOpera || isc.Browser.isIE && isc.Browser.version > 4) ||
        
        (isc.Browser.isUnix && isc.Browser.isMoz && isc.Browser.geckoVersion >= 20020826 
                                                 && isc.Browser.geckoVersion <= 20031007)

    ),

    //>	@attr	canvas.scrollbarSize		(number : 16 : IRWA)
	//			How thick should we make the scrollbars for this canvas.<br>
	//			NOTE: has no effect if showCustomScrollbars is false.