# Custom OfficeExcel events

- Introduction
- Available events
  - ontooltip
  - onbeforecontextmenu
  - oncontextmenu
  - onbeforedraw
  - ondraw
  - onzoom
  - onmodaldialog
  - onresizebeforedraw
  - onresizebegin
  - onresize
  - onresizeend
  - onadjustbegin
  - onadjust
  - onadjustend
  - onannotatebegin
  - onannotate
  - onannotateend
  - onannotatecolor
  - onannotateclear
  - onclear
  - oncrosshairs
- Removing events

#### Introduction

Custom events allow you to easily interact with and extend OfficeExcel for your own purposes. The list of available events is below, as is an example of how to make use of them with the OfficeExcel.AddCustomEventListener() function. Event handler functions (ie your functions) are passed a single parameter - the chart object. With this you can get references to the canvas and context. There's an example of this below.

    <script>
        window.onload = function ()
        {
            var line = new OfficeExcel.Line('myLine', [45,12,16,18,44,54,23,21,56]);
            line.Set('chart.tooltips', ['Fred', 'Barney', 'Jay', 'Pete', 'Frank', 'Bob', 'Ted', 'Lou', 'Kev']);
            line.Set('chart.labels', ['Fred', 'Barney', 'Jay', 'Pete', 'Frank', 'Bob', 'Ted', 'Lou', 'Kev']);
            line.Set('chart.hmargin', 5);
            line.Set('chart.tickmarks', 'dot');
            line.Draw();

            /**
            * This is the call to the OfficeExcel function that registers the event listener
            *
            *      line: The chart object
            * ontooltip: The name of the event
            *    myFunc: The function that handles the event
            */
            OfficeExcel.AddCustomEventListener(line, 'ontooltip', myFunc);
        }

        /**
        * The function that is called when the ontooltip event fires. It is  passed a single parameter - the chart object.
        * With this you can get the ID and references to the canvas and context:
        *  o obj.id
        *  o obj.canvas
        *  o obj.context
        */
        function myFunc(obj)
        {
            var id      = obj.id;
            var canvas  = obj.canvas;
            var context = obj.context;

            alert('This alert was triggered by the custom ontooltip event');
        }
    </script>

#### Available events

ontooltip
This event fires immediately after a tooltip has been created. This event allows you to easily show charts in your tooltips (tooltip effects that involve moving the tooltip, eg. contract, expand & snap, will not function). You can find the tooltip object in the OfficeExcel registry - OfficeExcel.Registry.Get('chart.tooltip'). Note that if you're testing and using a function that pauses execution (eg alert()), this will also pause any timers (for animation effects etc). If you want to avoid this you should use a function that doesn't block execution, eg the Firebug/WebKit function, console.log() (you can use the cl() shortcut in OfficeExcel).

onbeforecontextmenu
The onbeforecontextmenu event fires before the context menu is shown.

oncontextmenu
This event fires immediately after the OfficeExcel context menu is shown. If you want it, you can get at the context menu in the OfficeExcel registry: OfficeExcel.Registry.Get('chart.contextmenu')
Important: Like the ontooltip event, using alert() can pause the fade in timers, so you might consider using the Firebug/Webkit console.log functions instead.

onbeforedraw
Much like the ondraw event, however this fires at the start of the .Draw() method, in effect "before" the method. Keep in mind that since other charts may trigger the .Draw() method, this event can also be triggered by other charts.

ondraw
The ondraw event fires after the .Draw() method has run. Note that the interactive features of OfficeExcel may call the .Draw() method multiple times - the zoom in area mode is a prime example. A chart with tooltips is also an example. In this case it would demonstrate that the .Draw() method is called twice (and hence the ondraw event), whereas the ontooltip event only fires once.
Note: The ondraw event is not only fired by its own chart, but (if you're using tooltips for example), can also be fired by other charts on the page.

onzoom
The onzoom event fires whenever the canvas is zoomed. When the zoom is in area and canvas modes this fires once, but when in thumbnail mode this event is like the onmousemove event in that it fires whenever the mouse is moved.

onmodaldialog
The onmodaldialog event fires when the ModalDialog is shown. This event is easily replicated yourself, though using this event may help you to keep your code tidy. This event is utilised slightly differently to the other events:

    ModalDialog.AddCustomEventListener('onmodaldialog', function () {alert('Hello world!');});

onresizebeforedraw
The onresizebeforedraw event was added when translating was necessary to reclaim wasted space, before the introduction of independent gutters. This event is now no longer necessary to reposition the resize handle. It will still have an effect though, so if you choose to upgrade then you should remove this from your configuration. The event isn't planned to be removed, so if you wish to use it, you can.

Note: The annotation events send notifications to the console because using alert() would cause them to lock the window.

onresizebegin
The onresizebegin event fires when a canvas is starting to be resized. It also fires when the canvas is reset to the original size.
onresize
The onresize event fires when a canvas is resized. It also fires when the canvas is reset to the original size.
onresizeend
The onresizeend event fires when a canvas is ended resizing. It also fires when the canvas is reset to the original size.

Note: The adjusting events send notifications to the console because using alert() would cause them to lock the window.

onadjustbegin
The onadjustbegin event fires once at the start of an adjusting process. It can be thought of as similar to the onmousedown event as that's when it usually fires.

onadjust
The onadjust event fires whenever one of the supported chart types is adjusted. It usually fires in conjunction with the onmousemove event, and can be blocked by alert(). You therefore may need to use a different function (eg console.log()) whilst debugging.

onadjustend
The onadjustend event fires once at the end of an adjusting process. It can be thought of as similar to the onmouseup event as that's when it usually fires.

Note: The annotation events send notifications to the console because using alert() would cause them to lock the window.

onannotatebegin
The onannotatebegin event fires at the beginning of the annotating procedure (ie in a similar vein to the onmousedown event).

onannotate
The onannotate event fires when the chart has been annotated. It fires during the annotate procedure.

onannotateend
The onannotateend event fires at the end of the annotating procedure (ie in a similar vein to the onmouseup event).

onannotatecolor
The onannotatecolor event fires when the annotation color has been changed using the OfficeExcel palette.

onannotateclear
The onannotateclear event fires when the OfficeExcel annotation data has been cleared using the OfficeExcel.ClearAnnotations() API function.

onclear
The onclear event fires when the function OfficeExcel.Clear() is called. If you use the .Clear()function inside the onclear event handler, it will create a loop. Instead, you could use this function:

    /**
    * This function clears the canvas
    *
    * @param object obj The chart object
    */
    function myClear(obj)
    {
        obj.context.beginPath();
        obj.context.fillStyle = 'white';
        obj.context.fillRect(-10,-10,obj.canvas.width + 20, obj.canvas.height + 20);
        obj.context.fill();
    }

oncrosshairs
The oncrosshairs event fires when the crosshairs are moved. This event is very similar to the onmousemove event, but you can guarantee that this event fires after the crosshairs have been repainted.

#### Removing events

In the case that you need to remove OfficeExcel event listeners, there are a few ways that you can do it. The API function OfficeExcel.RemoveCustomEventListener(obj, id) can be used to remove a single event listener. This function takes the chart object and the numerical ID (returned by OfficeExcel.AddCustomEventListener()) as its arguments.

There's also the OfficeExcel.RemoveAllCustomEventListeners(), for easily removing all of the pertinent event listeners. This function can either take no arguments at all, in which case ALL event listeners for ALL objects are removed. Or it can also take an objects ID (the same id that you pass to the constructor), in which case the removal will be limited to that object.
Login to admin area

Email: |
Password: |

Dismiss