RasterListEvent

Object passed to a list event handler containing information about the event in progress. The object has the following properties:

event       The associated DOM event object.
type        Indicates the type of event.
list        The list control that issued the event.
item        The list item that was clicked.
colIdx      Index of the column clicked (table mode).
index       Index of the list item clicked.
newColWidth New width a column has been resized to (table mode).
newColIdx   Index a column was moved to (table mode).
dataIdx     Index of the item.data[] element
            associated with the clicked column (table mode).
dragValue   The value being dragged/dropped over the control.
position    Indicates where dragged value is about
            to be dropped.

Not all object properties apply to all event types. When a property is not relevant to a given event type, its value is set to null (Tip: do an alert() on the event object to see which properties are set for any particular event type).

The type property indicates what the event does. The following table lists its possible values:

Event Type Description colclick A column header was clicked. The colIdx has the index of the column being clicked. Cancelling this event will prevent a column from being moved and the "colsort" event from happening next. colcontext A column header was right-clicked. This might be used to open a context menu at the mouse position. colsort The list is about to be sorted based on the data associated with the column header being clicked. This event can be cancelled to perform a custom sort on a hidden list item data element, or fetching new data rows from the database and re-populate the list. colmove A column was moved. The colIdx has the index of the column being moved, the newColIdx indicates the index where the column was dropped. Cancelling this event will prevent a column from being moved. colsize A column was resized. The colIdx has the index of the column being resized, the newColWidth indicates the new column width. Cancelling this event will prevent the new column size from being applied. The event handler may assign a new value to the newColWidth property and overwrite the current new width value. This mechanism can be used to prevent a column from being too wide or too narrow. click A list item was clicked. The item property points to the list item being clicked. Cancelling this event will prevent the list current selection from changing. dblclick A list item was double-clicked. The item property points to the list item being clicked. Note the "click" event will fire twice before "dblclick" fires. This is normal. context A list item was right-clicked. The item property points to the list item being clicked. This might be used to open a context menu at the mouse position. beforedrag One or more list items are about to be dragged. The item property points to the list item being dragged. In case of a multiple selections, use the RasterList.getSelectedItems() method to know which items are being dragged. Cancelling this event will prevent the drag operation from occurring. over A value is being dragged over a list item. The item property points to the list item currently under the mouse pointer. The dragValue property contains the value being dragged over the item. The position property indicates where the dragged value is about to be dropped in relation to the list item.

If the event handler wishes to accept the dragValue at the current position, it must invoke RasterEvent.accept() to signal the control to highlight the item as a potential drop target (i.e. draw insertion line or shaded box at the item's location).

The event handler may overwrite the current position by passing a new position to the accept() method. If the event handler does not invoke accept(), the item will not be highlighted as a potential drop target, nor the "drop" event will fire on the item if the mouse button is released over the item. drop A value was dropped over an item. The item property points to the list item receiving the drop. The dragValue property contains the value dropped over the item. The position property indicates where the dragValue was dropped in relation to the item.

Moving Local Items

When dragging and dropping items inside the same control, the drag operation is said to be "local". In such case, the control's default behavior is to reorganize the dropped items automatically after the event handler returns from a "drop" event. If the event handler wishes to prevent the default "reorganize" behavior, it must invoke RasterEvent.cancel() before it returns. Note: When reorganising local items in a list, a drop position equal to "over" will be treated as "before".

Example: Hooking up a list event handler

var list = new RasterList("myDiv");
list.setEventHandler( myHandler );  //assign event handler

...

function myHandler( evt )
{
    switch ( evt.type )
    {
       case "click"    : alert ( evt.item.text +
                                 " was clicked" );
                         break;

       case "colclick" : if ( evt.colIdx == 0)
                            evt.cancel(); //prevent user from moving
                                          //or sorting column 0
                         break;
    }
}

See Also

• RasterEvent.cancel()
• RasterEvent.accept()
• RasterList.setEventHandler()