Basic event handler

From PhiWiki
Jump to: navigation, search

The following table lists the basic event handler provided by Phi. All handler except the custom handler use the normalized event object as an optional parameter. Surely not every handler makes sense for every item available and some define additional handler which are documented in the related item description.

Basic event handler
Button Mouse Key Misc Custom
.click() .mouseover() .keydown() .focus() .on()
.dblclick() .mouseout() .keyup() .blur() .off()
.mousedown() .mousemove() .keypress() .drop() .one()
.mouseup() .trigger()

Example

Writing handler functions is really easy if you use anonymous functions:

$('id').click( function(e){ doSomething(e); } ); // e=event object

The event object parameter e can be omitted. All handler return a reference to the item itself, so handler functions can be cascaded:

$('id').keypress(function(e){ alert('key '+e.which); }).click(function(e){ alert('clicked '+e.which); });

Even if possible - we highly recommend not to use the built-in handler like

document.getElementById('id').onmouseover=function(){ doSomething(); };

as they are not always cross browser compatible.

Event bubbling

Due to the nature of complete self-contained items used in Phi, event bubbling has not the same significance as in other script tools like jQuery. The only case in which it could make sense is in parent/child relations like Layouts. Item functions in Phi always cover the whole element even if HTML sub elements are present.

Prevent default action

With introduction of v2.0.0 the default action of items can be prevented by calling e.preventDefault(); on the event object e.

Button

.click() .dblclick() .mousedown() .mouseup()

.click()


Synopsis

.click([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Click handler.
Attribute Type Default Note
f Function Function to call if click is triggered
e Object Event object

Overview

Description

Reacts on item button clicks.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a click handler function.

Note: the event order of a mouse click is .mousedown(), .mouseup(), .click().

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').click( function(){ doSomething(); } );
$('id').on( 'click', function(){ doSomething(); } );
$('id').click(); // triggers a click

.dblclick()


Synopsis

.dblclick([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Dblclick handler.
Attribute Type Default Note
f Function Function to call if dblclick is triggered
e Object Event object

Overview

Description

Reacts on item double clicks.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a dblclick handler function.

Note:

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').dblclick( function(){ doSomething(); } );
$('id').on( 'dblclick', function(){ doSomething(); } );
$('id').dblclick(); // triggers a double click

.mousedown()


Synopsis

.mousedown([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Mousedown handler.
Attribute Type Default Note
f Function Function to call if mousedown is triggered
e Object Event object

Overview

Description

Reacts on a mouse button down event.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a mousedown handler function.

Note: the event order of a mouse click is .mousedown(), .mouseup(), .click().

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').mousedown( function(e){ alert('button down '+e.which); } );
$('id').on( 'mousedown', function(){ doSomething(); } );
$('id').mousedown(); // triggers a custom mousedown event

.mouseup()


Synopsis

.mouseup([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Mouseup handler.
Attribute Type Default Note
f Function Function to call if mouseup is triggered
e Object Event object

Overview

Description

Reacts on a mouse button up event.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a mouseup handler function.

Note: the event order of a mouse click is .mousedown(), .mouseup(), .click().

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').mouseup( function(e){ alert('button up '+e.which); } );
$('id').on( 'mouseup', function(){ doSomething(); } );
$('id').mouseup(); // triggers a custom mousedown event

Mouse

.mouseover() .mouseout() .mousemove()

.mouseover()


Synopsis

.mouseover([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Mouseover handler.
Attribute Type Default Note
f Function Function to call if mouseover is triggered
e Object Event object

Overview

Description

Reacts on item hover events.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a mouseover handler function.

Note: this handler has not the same behavior as the built-in onmouseover and mouseover from jQuery. Actually it behaves like the jQuery mouseenter which is what the programmer usually need.

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').mouseover( function(e){ alert('hover '+e.pageX+' '+e.pageY); } );
$('id').on( 'mouseover', function(){ doSomething(); } );

.mouseout()


Synopsis

.mouseout([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Mouseout handler.
Attribute Type Default Note
f Function Function to call if mouseout is triggered
e Object Event object

Overview

Description

Reacts on item leave events.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a mouseout handler function.

Note: this handler has not the same behavior as the built-in onmouseout and mouseout from jQuery. Actually it behaves like the jQuery mouseleave which is what the programmer usually need.

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').mouseout( function(e){ alert('mouseout '+e.pageX+' '+e.pageY); } );
$('id').on( 'mouseout', function(){ doSomething(); } );

.mousemove()


Synopsis

.mousemove([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Mousemove handler.
Attribute Type Default Note
f Function Function to call if mousemove is triggered
e Object Event object

Overview

Description

Reacts on item mouse move events.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a mousemove handler function.

Note: you may use the event object to track the actual mouse positions.

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').mousemove( function(e){ alert('move '+e.clientX+' '+e.clientY); } );
$('id').on( 'mousemove', function(){ doSomething(); } );

Key

.keydown() .keyup() .keypress()

.keydown()


Synopsis

.keydown([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Keydown handler.
Attribute Type Default Note
f Function Function to call if keydown is triggered
e Object Event object

Overview

Description

Reacts on key down events.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a keydown handler function.

Note: the event order of a key press is .keydown(), .keyup(), .keypress().

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').keydown( function(e){ alert('keydown '+e.which); } );
$('id').on( 'keydown', function(){ doSomething(); } );

.keyup()


Synopsis

.keyup([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Keyup handler.
Attribute Type Default Note
f Function Function to call if keyup is triggered
e Object Event object

Overview

Description

Reacts on key up events.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a keyup handler function, i.e. when the user releases the key.

Note: the event order of a key press is .keydown(), .keyup(), .keypress().

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').keyup( function(e){ alert('keydown '+e.which); } );
$('id').on( 'keyup', function(){ doSomething(); } );

.keypress()


Synopsis

.keypress([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Keypress handler.
Attribute Type Default Note
f Function Function to call if keypress is triggered
e Object Event object

Overview

Description

Reacts on key press events.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a keypress handler function.

Note: the event order of a key press is .keydown(), .keyup(), .keypress().

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').keypress( function(e){ alert('keypress '+e.which); } );
$('id').on( 'keypress', function(){ doSomething(); } );

Misc

.focus() .blur() .drop()

.focus()


Synopsis

.focus([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Focus handler.
Attribute Type Default Note
f Function Function to call if focus is triggered
e Object Event object

Overview

Description

Reacts on focus events.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a focus handler function.

Note: the handler is triggered if an item gains input focus and will receive key events.

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').focus( function(e){ alert('focus'); } );
$('id').on( 'focus', function(){ doSomething(); } );
$('id).focus(); // makes 'id' the current input item

.blur()


Synopsis

.blur([f([e])])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Blur handler.
Attribute Type Default Note
f Function Function to call if blur is triggered
e Object Event object

Overview

Description

Reacts on blur events.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a blur handler function.

Note: the handler is triggered if an item looses input focus and will not receive key events anymore.

See also: .on(), .one(), .off(), .trigger(), Event object.

Example

$('id').blur( function(e){ alert('lost focus'); } );
$('id').on( 'blur', function(){ doSomething(); } );
$('id').blur(); // removes the input focus from 'id'

.drop()


Synopsis

.drop([e[,ui]])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Drop handler.
Attribute Type Default Note
e String Event object
ui Object Object for accessing the draggable

Overview

Description

Triggered if a draggable item is dropped over this item. This is part of the Drag&Drop system of Phi.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a drop handler for this item.

Note: this handler can not be triggered manually - the result will be unpredictable.

See also: Drag&Drop How-To.

Warning: document.getElementById('id').ondrop is currently not supported and is used differently in recent browser implementations.

The object ui owns the following properties:

  • ui.source - source ID (item ID of the draggable)
  • ui.target - target ID (item ID where the dragged item was dropped)
  • ui.position.left - left position relative to the document where the item was dropped
  • ui.position.top - top position relative to the document where the item was dropped
  • ui.offset.left - left position relative to the browser window
  • ui.offset.top - top position relative to the browser window

Example

$('id').drop( function( e, ui ){ alert( ui.source ); } );
$('id').drop( function( e, ui ){ $(ui.source).hide(); } ); // hides the dragged item

Custom

.on() .off() .one() .trigger()

.on()


Synopsis

.on(s,f([e[,args]]))
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Creates a custom handler.
Attribute Type Default Note
s String Handler name
f Function Function signature
e Object Event object
args Object Additional arguments

Overview

Description

Binds a new event handler to an event. The name s can be one of the built-in events or a custom event. A custom event needs to be triggered manually.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a handler function for event type s for this item.

Note: for custom events a synthetic event object will be created.

See also: .off() .one() .trigger()

Example

$('id').on( 'myevent', function(){ doSomething(); } ); // bind anonymous function to custom event
$('id').on( 'myevent', function( e, args ){} ); // 'args' can be a custom object wich can be passed to .trigger()
$('button').on( 'click', function( e ){ alert( e.type ); } );
$('rect').on( 'mycloseevent', function( e, args ){ $('rect').hide(); alert( args.par ); } );

.one()


Synopsis

.one(s,f([e[,args]]))
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v2.0.0
Brief description: Creates a custom handler.
Attribute Type Default Note
s String Handler name
f Function Function signature
e Object Event object
args Object Additional arguments

Overview

Description

Binds a new event handler to an event. The name s can be one of the built-in events or a custom event. A custom event needs to be triggered manually. The handler will be automatically removed after the event occurred - i.e. it will be called only once.

Read: this is a write-only function and returns a reference to the item itself.

Write: adds a handler function for event type s for this item.

Note: for custom events a synthetic event object will be created.

See also: .on() .off() .trigger()

Example

$('id').one( 'myevent', function(){ doSomething(); } ); // bind anonymous function to custom event
$('id').one( 'myevent', function( e, args ){} ); // 'args' can be a custom object wich can be passed to .trigger()
$('button').one( 'click', function( e ){ alert( e.type ); } ); // a second click will not be handled
$('rect').one( 'mycloseevent', function( e, args ){ $('rect').hide(); alert( args.par ); } );

.off()


Synopsis

.off(s[,f([e[,args]]]))
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Removes a handler.
Attribute Type Default Note
s String Handler name
f Function Function signature
e Object Event object
args Object Additional arguments

Overview

Description

Removes an event handler (the function signature must be exactly the same as passed to .on()). If the function signature is omitted all handler bound to event type s are removed.

Read: this is a write-only function and returns a reference to the item itself.

Write: removes one or all handler function(s) for event type s for this item.

Note:

See also: .on() .one() .trigger()

Example

$('id').off( 'myevent', function(){ doSomething(); } ); // removes function 'doSomething();' from 'myevent'
$('button').off( 'click' ); // removes all 'click' handler from 'button'

.trigger()


Synopsis

.trigger(s[,args])
Returns (read): n/a
Environment: ServerScriptNa.png JavaScriptOk.png
Available since: v1.3.0
Brief description: Triggers a handler.
Attribute Type Default Note
s String Handler name
args Object Additional arguments

Overview

Description

Triggers all bound handler for event type s. The optional object args will be passed to the handler function.

Read: this is a write-only function and returns a reference to the item itself.

Write: triggers handler functions for event type s for this item.

Note: a synthetic event object will be created.

See also: .on() .off()

Example

$('id').trigger( 'myevent' ); // calls all bound functions to 'myevent'
$('id').trigger( 'myevent', {par:'test'} ); // calls $('id').on('myevent',function(e,{par:'test'}){...});
$('button').trigger( 'click' ); // triggers a 'click' for item with id 'button'