Clear Up
SharpKit Reference

Surface Class

A Surface is an interface to render methods inside Ext.draw.Component.

Most of the Surface methods are abstract and they have a concrete implementation in VML or SVG engines.

A Surface contains methods to render sprites, get bounding boxes of sprites, add sprites to the canvas, initialize other graphic components, etc.

Adding sprites to surface

One of the most used methods for this class is the add method, to add Sprites to the surface. For example:

  
drawComponent.surface.add({
            type: 'circle',
            fill: '#ffc',
            radius: 100,
            x: 100,
            y: 100
            });
            

The configuration object passed in the add method is the same as described in the Ext.draw.Sprite class documentation.

Sprites can also be added to surface by setting their surface config at creation time:

  
var sprite = Ext.create('Ext.draw.Sprite', {
            type: 'circle',
            fill: '#ff0',
            surface: drawComponent.surface,
            radius: 5
            });
            

In order to properly apply properties and render the sprite we have to show the sprite setting the option redraw to true:

  
sprite.show(true);
            

Namespace: Ext.draw

Base Types

Base Interfaces

Constructors

Name Description
Surface(object) Creates new Surface.
Surface(SurfaceConfig)
Surface(Object[])

Methods

Name Description
add(object) Adds a Sprite to the surface. See Ext.draw.Sprite for the configuration object to be passed into this method. For example:
drawComponent.surface.add({
            type: 'circle',
            fill: '#ffc',
            radius: 100,
            x: 100,
            y: 100
            });
            
addCls(object, object) Adds one or more CSS classes to the element. Duplicate classes are automatically filtered out. For example:
drawComponent.surface.addCls(sprite, 'x-visible');
            
addEvents(object) Adds the specified events to the list of events which this Observable may fire.
addGradient(object) Adds a gradient definition to the Surface. Note that in some surface engines, adding a gradient via this method will not take effect if the surface has already been rendered. Therefore, it is preferred to pass the gradients as an item to the surface config, rather than calling this method, especially if the surface is rendered immediately (e.g. due to 'renderTo' in its config). For more information on how to create gradients in the Chart configuration object please refer to Ext.chart.Chart. The gradient object to be passed into this method is composed by:
  • id - string - The unique name of the gradient.
  • angle - number, optional - The angle of the gradient in degrees.
  • stops - object - An object with numbers as keys (from 0 to 100) and style objects as values.
  • For example: drawComponent.surface.addGradient({
    id: 'gradientId',
             angle: 45,
             stops: {
             0: {
             color: '#555'
             },
             100: {
             color: '#ddd'
             }
             }
                
    });
    addListener(object, Delegate, object, object) Appends an event handler to this object. For example:
    myGridPanel.on("mouseover", this.onMouseOver, this);
                
    The method also allows for a single argument to be passed which is a config object containing properties which specify multiple events. For example:
    myGridPanel.on({
                cellClick: this.onCellClick,
                mouseover: this.onMouseOver,
                mouseout: this.onMouseOut,
                scope: this // Important. Ensure "this" is correct during handler execution
                });
                
    One can also specify options for each event handler separately:
    myGridPanel.on({
                cellClick: {fn: this.onCellClick, scope: this, single: true},
                mouseover: {fn: panel.onMouseOver, scope: panel}
                });
                
    Names of methods in a specified scope may also be used. Note that scope MUST be specified to use this option:
    myGridPanel.on({
                cellClick: {fn: 'onCellClick', scope: this, single: true},
                mouseover: {fn: 'onMouseOver', scope: panel}
                });
                
    addManagedListener(object, object, Delegate, object, object) Adds listeners to any Observable object (or Ext.Element) which are automatically removed when this Component is destroyed.
    clearListeners() Removes all listeners for this object including the managed listeners
    clearManagedListeners() Removes all managed listeners for this object.
    continueFireEvent(JsString, object, object) Continue to fire event.
    create(object, object) Creates and returns a new concrete Surface instance appropriate for the current environment.
    createRelayer(object, object) Creates an event handling function which refires the event from this object as the passed event name.
    enableBubble(object) Enables events fired by this Observable to bubble up an owner hierarchy by calling this.getBubbleTarget() if present. There is no implementation in the Observable base class. This is commonly used by Ext.Components to bubble events to owner Containers. See Ext.Component.getBubbleTarget. The default implementation in Ext.Component returns the Component's immediate owner. But if a known target is required, this can be overridden to access the required target more quickly. Example:
      Ext.override(Ext.form.field.Base, {
                //  Add functionality to Field's initComponent to enable the change event to bubble
                initComponent : Ext.Function.createSequence(Ext.form.field.Base.prototype.initComponent, function() {
                this.enableBubble('change');
                }),
                //  We know that we want Field's events to bubble directly to the FormPanel.
                getBubbleTarget : function() {
                if (!this.formPanel) {
                this.formPanel = this.findParentByType('form');
                }
                return this.formPanel;
                }
                });
                var myForm = new Ext.formPanel({
                title: 'User Details',
                items: [{
                ...
                }],
                listeners: {
                change: function() {
                // Title goes red if form has been modified.
                myForm.header.setStyle('color', 'red');
                }
                }
                });
                
    fireEvent(JsString, Object[]) Fires the specified event with the passed parameters (minus the event name, plus the options object passed to addListener). An event may be set to bubble up an Observable parent hierarchy (See Ext.Component.getBubbleTarget) by calling enableBubble.
    getBubbleParent() Gets the bubbling parent for an Observable
    getGroup(JsString) Returns a new group or an existent group associated with the current surface. The group returned is a Ext.draw.CompositeSprite group. For example:
    var spriteGroup = drawComponent.surface.getGroup('someGroupId');
                
    getId() Retrieves the id of this component. Will autogenerate an id if one has not already been set.
    hasListener(JsString) Checks to see if this object has any listeners for a specified event, or whether the event bubbles. The answer indicates whether the event needs firing or not.
    mon(object, object, Delegate, object, object) Shorthand for addManagedListener. Adds listeners to any Observable object (or Ext.Element) which are automatically removed when this Component is destroyed.
    mun(object, object, Delegate, object) Shorthand for removeManagedListener. Removes listeners that were added by the mon method.
    on(object, Delegate, object, object) Shorthand for addListener. Appends an event handler to this object. For example:
    myGridPanel.on("mouseover", this.onMouseOver, this);
                
    The method also allows for a single argument to be passed which is a config object containing properties which specify multiple events. For example:
    myGridPanel.on({
                cellClick: this.onCellClick,
                mouseover: this.onMouseOver,
                mouseout: this.onMouseOut,
                scope: this // Important. Ensure "this" is correct during handler execution
                });
                
    One can also specify options for each event handler separately:
    myGridPanel.on({
                cellClick: {fn: this.onCellClick, scope: this, single: true},
                mouseover: {fn: panel.onMouseOver, scope: panel}
                });
                
    Names of methods in a specified scope may also be used. Note that scope MUST be specified to use this option:
    myGridPanel.on({
                cellClick: {fn: 'onCellClick', scope: this, single: true},
                mouseover: {fn: 'onMouseOver', scope: panel}
                });
                
    prepareClass(Delegate) Prepares a given class for observable instances. This method is called when a class derives from this class or uses this class as a mixin.
    relayEvents(object, JsArray<T>, object) Relays selected events from the specified Observable as if the events were fired by this. For example if you are extending Grid, you might decide to forward some events from store. So you can do this inside your initComponent:
    this.relayEvents(this.getStore(), ['load']);
                
    The grid instance will then have an observable 'load' event which will be passed the parameters of the store's load event and any function fired with the grid's load event would have access to the grid using the this keyword.
    remove(Sprite, bool) Removes a given sprite from the surface, optionally destroying the sprite in the process. You can also call the sprite own remove method. For example:
    drawComponent.surface.remove(sprite);
                //or...
                sprite.remove();
                
    removeAll(bool) Removes all sprites from the surface, optionally destroying the sprites in the process. For example:
    drawComponent.surface.removeAll();
                
    removeCls(object, object) Removes one or more CSS classes from the element. For example:
    drawComponent.surface.removeCls(sprite, 'x-visible');
                
    removeListener(JsString, Delegate, object) Removes an event handler.
    removeManagedListener(object, object, Delegate, object) Removes listeners that were added by the mon method.
    removeManagedListenerItem(bool, object) Remove a single managed listener item
    resumeEvents() Resumes firing events (see suspendEvents). If events were suspended using the queueSuspended parameter, then all events fired during event suspension will be sent to any listeners now.
    save(Surface, object) Exports a surface in a different format. The surface may be exported to an SVG string, using the Ext.draw.engine.SvgExporter. It may also be exported as an image using the ImageExporter. Note that this requires sending data to a remote server to process the SVG into an image, see the Ext.draw.engine.ImageExporter for more details.
    setSize(JsNumber, JsNumber) Sets the size of the surface. Accomodates the background (if any) to fit the new size too. For example:
    drawComponent.surface.setSize(500, 500);
                
    This method is generally called when also setting the size of the draw Component.
    setStyle(object, object) Sets CSS style attributes to an element. For example:
    drawComponent.surface.setStyle(sprite, {
                'cursor': 'pointer'
                });
                
    setText(object, JsString) Changes the text in the sprite element. The sprite must be a text sprite. This method can also be called from Ext.draw.Sprite. For example:
    var spriteGroup = drawComponent.surface.setText(sprite, 'my new text');
                
    suspendEvents(bool) Suspends the firing of all events. (see resumeEvents)
    un(JsString, Delegate, object) Shorthand for removeListener. Removes an event handler.

    Properties

    Name Description
    eventsSuspended Initial suspended call count. Incremented when suspendEvents is called, decremented when resumeEvents is called. Defaults to: 0
    hasListeners This object holds a key for any event that has a listener. The listener may be set directly on the instance, or on its class or a super class (via observe) or on the MVC EventBus. The values of this object are truthy (a non-zero number) and falsy (0 or undefined). They do not represent an exact count of listeners. The value for an event is truthy if the event must be fired and is falsy if there is no need to fire the event. The intended use of this property is to avoid the expense of fireEvent calls when there are no listeners. This can be particularly helpful when one would otherwise have to call fireEvent hundreds or thousands of times. It is used like this:
    if (this.hasListeners.foo) {
               this.fireEvent('foo', this, arg1);
               }
                
    isObservable true in this class to identify an object as an instantiated Observable, or subclass thereof. Defaults to: true

    Fields

    Name Description
    height The height of this component in pixels (defaults to auto).
    items Array of sprites or sprite config objects to add initially to the surface.
    listeners A config object containing one or more event handlers to be added to this object during initialization. This should be a valid listeners config object as specified in the addListener example for attaching multiple handlers at once. DOM events from Ext JS Components While some Ext JS Component classes export selected DOM events (e.g. "click", "mouseover" etc), this is usually only done when extra value can be added. For example the DataView's itemclick event passing the node clicked on. To access DOM events directly from a child element of a Component, we need to specify the element option to identify the Component property to add a DOM listener to:
    new Ext.panel.Panel({
                width: 400,
                height: 200,
                dockedItems: [{
                xtype: 'toolbar'
                }],
                listeners: {
                click: {
                element: 'el', //bind to the underlying el property on the panel
                fn: function(){ console.log('click el'); }
                },
                dblclick: {
                element: 'body', //bind to the underlying body property on the panel
                fn: function(){ console.log('dblclick body'); }
                }
                }
                });
                
    width The width of this component in pixels (defaults to auto).
    © Copyright 2005-2011 SharpKit. All rights reserved.