PhiItem class

From PhiWiki
Redirect page
Jump to: navigation, search

Redirect to:

The PhiItem class wraps the Item class and offers an easy API (programming application interface) for manipulating elements. The wrapper running in client (Browser windows) is available since v1.3.0. A similar Wrapper class is also available for the server environment since v1.5.0.

Since v2.0.0 the wrapper is an integrated part (not a module anymore) of the software now and should be the only interface used to access and control elements (even with ServerScript). Please refer to the element description for further documentation on how to manipulate elements. This page is outdated and only available for releases prior V2.0! Soon or later it will be removed.

Usage

This wrapper of the Item class offers additional functions available for both environments: Phi and HTML mode. If you are not calling a getter function, the object returns a reference to itself, so you can cascade multiple setter functions.

You create an object by using the $ and the id (the ID you set for an element in the Artephis editor):

$('id').function1().function2();

Properties

The wrapper does not define any properties.

Functions

The following functions are provided to manipulate an element. Functions which animate an item can also use an optional Easing curve.

.checked()

Checks an Radio button, Check box or a Check list item, or returns the current state.

var isChecked=$('id').checked(); // getter for single value items
var isChecked=$('id').checked( value ); // getter for grouped items and check lists
$('id').checked( true|false ); // setter for single value items
$('id').checked( value, true|false ); // setter for grouped items and check lists

Examples:

// Assume a check list with the following content and a colon ':' as delimiter:
// Header:option 1[opt1]:options 2[opt2]:option 3
// note: option 3 has an undefined value so the label itself is used as the significant value
$('chklist').checked( 'opt2', true );
if ( $('chklist').checked( 'opt1' ) ) doSometing();
$('chklist').checked( 'option 3', true ); // not recommended, if you use translated text
$('radiolayout').checked( 'r1', false );
if ( ('chkbox').checked() ) doSometing();

.cursor()

Sets or returns the cursor image for the item.

var ctype=$('id').cursor(); // getter (String)
$('id').cursor( type ); // setter (String)

Example:

$('id').cursor( 'wait' );

The following cursor types are supported:

  • crosshair
  • default
  • e-resize
  • help
  • move
  • n-resize
  • ne-resize
  • nw-resize
  • pointer
  • progress
  • s-resize
  • se-resize
  • sw-resize
  • text
  • w-resize
  • wait

.fadeIn()

Fades an item in after s milli seconds with the duration time of d, the final opacity value o using the easing curve e. The item becomes fully transparent immediately, a hidden item becomes visible.

$('id').fadeIn( s=0, d=1000, o=1., e='easeOutQuad' );

Examples:

$('id').fadeIn( 2000, 4000, .8 ); // starts fading the item in after 2 sec with a duration of 4sec to 80% opacity.
$('id').fadeIn().opacity( .5 ); // fades the item immediately in with a starting opacity of 50%

See also: .opacity(), .visible().

.fadeOut()

Fades an item out after s milli seconds with the duration time of d, the final opacity value o using the easing curve e. The item becomes visible immediately.

$('id').fadeOut( s=0, d=1000, o=0., e='easeOutQuad' );

Examples:

$('id').fadeOut( 2000, 4000, .2, 'linear' ); // starts fading the item out after 2 sec with a duration of 4sec to 20% opacity using a linear easing curve.
$('id').fadeOut().opacity( .5 ); // fades the item immediately out with a starting opacity of 50%

Note: if the final opacity is below .1 (10%) the item becomes hidden after the animation.

See also: .opacity(), .visible().

.height()

Sets or returns the height of the item. Only sizes in pixels are currently supported.

var h=$('id').height(); // getter
$('id').height( px ); // setter

Examples:

$('id').height( 50 ); // sets the item height to 50px

Warning: some items my have a minimum or maximum height.

See also: .top(), .left(), .width().

.hide()

Hides an item immediately.

$('id').hide();

Note: items in Phi which has the CSS style visibility:hidden attached are treated as hidden as well. This is different to the jQuery behavior where an item needs the CSS style display:none to be treated as really hidden. However in Phi mode the display style is not available because of the nature how items are positioned. We recommend not to use to set the style directly - always use .hide() and .show() to be safe.

Warning: an item with zero opacity is not treated as hidden.

.html()

Sets or gets the HTML markup of a Rich text layouted element. The richtext markup must be a subset of the available Rich text markup in Phi.

var html=$('id').html(); // getter (String)
$('id').html( richttext ); // setter (String)

Example:

$('id').html('<span color="#ff0000">red text</span>');

.left()

Returns or sets the X coordinate (in pixels) relative to the document.

var x=$('id').left(); // getter
$('id').left( xcoord ); // setter

Example:

$('id').left( 30 );

Note: Phi automatically calculates offsets for shadows and graphic styles in Artephis only. Using this function you need to add the appropriate offset by yourself if you have visual graphical effects applied to this item.

See also: top(), width(), height(), pos().

.moveBy()

Starts an animation for a relative movement or size change after s milliseconds with deltax, deltay, deltaw, deltah. The animation takes d millisecond using easing curve ease.

$('id').moveBy( deltax, deltay, deltaw=0, deltah=0, s=0, d=1000, ease='easeOutQuad' );

Examples:

$('id').moveBy( 0, -100 ); // moves the item 100px to the top, starting the animation immediately
$('id').moveBy( 0, 0, 100, 0, 5000, 2000 ); // growth the width of the item with 100px, starting after 5sec and a duration of 2sec
$('id').moveBy( 250, 0, 0, 200, 0, 4000, 'easeOutCirc' ); // moves the item immediately 250px to the right and adds 200px to the 
// height with a duration of 4sec and a circle easing curve

Note: some items have a fixed width or height or both, so changing their size does not have any effect.

.moveTo()

Starts an animation for a movement to a specific position after s milliseconds with left and top as the ending point. The animation takes d millisecond using easing curve ease.

$('id').moveTo( left, top, s=0, d=1000, ease='easeOutQuad' );

Examples:

$('id').moveTo( 0, 0 ); // moves the item to the top, left corner of the document starting the animation immediately
$('id').moveTo( 200, 400, 10000, 5000, 'linear' ); // moves the item to the position x=200, y=400, starting after 10sec and a duration of 5sec

Note: if you use graphical effects like a drop shadow you may need to add an additional offset depending on the size of the shadow. Artephis initially calculates the correct offset automatically, but if you animate the item, you may need to recalculate them.

.opacity()

Sets or returns the opacity for this item. The opacity must be in the range of 0 (fully transparent) to 1 (opaque). An opacity of 0.5 is 50% transparent. Phi normalizes the value to support also older IExplorer versions using an alpha filter.

var o=$('id').opacity(); // getter
$('id').opacity( opacity ); // setter

.pos()

Short hand for getting or setting the item position relative to the document. The getter returns an object with a left and top property.

var obj=$('id').pos(); // getter (x=obj.left, y=obj.top) 
$('id').pos( left, top ); // setter

See also: .left(), .top().

.progress()

Sets or retunes the progress of a Progress bar. The value must be in the range between 0 and 100.

var p=$('id').progress(); // getter
$('id').progress( progress ); // setter

Example:

$('progressbar').progress( 20 );

.rotateIn()

Rotates an item in through its x- or y-axis in Phi mode. In HTML mode the item is animated in. The animation starts after s milliseconds, with a duration of d and easing curve ease. A hidden item becomes visible.

$('id').rotateIn( axis=phi.yAxis, s=0, d=1000, ease='easeOutQuad' );

The axis parameter may contain phi.xAxis, phi.yAxis or both.

Example:

$('id').rotateIn( phi.xAxis, 5000, 2000 ); // Rotates the item in starting after 5sec with a duration of 2sec.
$('id').rotateIn( phi.xAxis+phi.yAxis, 0, 4000 ); // Rotates the item immediately in with a duration of 4sec over both axis.

Note: a phi.zAxis parameter will be silently ignored.

.rotateOut()

Rotates an item out through its x- or y-axis in Phi mode. In HTML mode the item is animated out. The animation starts after s milliseconds, with a duration of d and easing curve ease. The item becomes invisible after the animation.

$('id').rotateOut( axis=phi.yAxis, s=0, d=1000, ease='easeOutQuad' );

The axis parameter may contain phi.xAxis, phi.yAxis or both.

Example:

$('id').rotateOut( phi.xAxis, 5000, 2000 ); // Rotates the item out starting after 5sec with a duration of 2sec.
$('id').rotateOut( phi.xAxis+phi.yAxis, 0, 4000 ); // Rotates the item immediately out with a duration of 4sec over both axis.

Note: a phi.zAxis parameter will be silently ignored.

.selected()

Returns if a child element is selected or selects a child element. This only applies to Country selection, List box and Selection box. If no parameter is specified all selected values are returned as an array of strings.

var list=$('id').selected(); // getter (list is a string array)
var b=$('id').selected( value ); // getter (Boolean)
$('id').selected( value, [true|false] ); // setter (String, Boolean)

Example:

// Asume the following content for a list box item and the colon ':' as delimiter
// Option 1[opt1]:Option 2[opt2][true]:Option 3
// Option 3 has no value set, so the label itself is used as significant value
$('list').selected( 'opt2', false );
$('list').selected( 'Option 3', true ); // not recommended if you use translated text

Warning: unselecting a value for a Selection box using $('select').selected( 'child', false ); is unpredictable and the behavior depends on the browser. A Selection box should always have exactly one element selected. If you select an element of a Selection box all other elements will be unselected.

.selectOptions()

Sets the option list of a List box item or Selection box item.

$('id').selectOptions( data, delimiter );

Example:

$('id').selectOptions( 'row 1[1]:row 2[2]:row 3[3]', ':' );

See also: .selected().

.show()

Makes an item visible. CSS styles set in HTML mode like display:none or visibility:hidden will be changed. An item with opacity 0 remains transparent.

$('id').show();

Note: The CSS style visibility:hidden is treated as invisible. This is a different behavior than in the jQuery API. We recommend to use always .show() and .hide() and not to set the style directly to be safe. display:none is not supported in Phi mode.

.slide()

Slides an item up or down. This is usually used for layouted menus. If you slide up the item becomes hidden and the original height is restored.

$('id').slide( 'up'|'down', duration=400, ease='easeOutQuad' );

Example:

$('id').slide( 'down', 1000 ); // slides an item down with a duration of 1sec

.stop()

Stops any animation for this item immediately.

$('id').stop();

.title()

Sets or returns the current title (tool tip) set for this element.

var t=$('id').title(); // getter
$('id').title( title ); // setter

Example:

$('id').title( 'My special tool tip for this item' );

Note: use an empty title to switch off the tool tip.

.toggle()

Toggles an item. Makes a hidden item visible and vice versa.

$('id').toggle();

.top()

Returns or sets the Y coordinate (in pixels) relative to the document.

var y=$('id').top(); // getter
$('id').top( ycoord ); // setter

Example:

$('id').top( 130 );

Note: Phi automatically calculates offsets for shadows and graphic styles in Artephis only. Using this function you need to add the appropriate offset by yourself if you use visual graphical effects for this item.

See also: left(), width(), height(), pos().

.val()

Sets or returns the value for input items. For example you can use this function to preset Line edits or read the content of a Hidden field.

var v=$('id').val(); // getter
$('id').val( value ); // setter

.visible()

Changes the visibility state or returns the current state. An item is invisible if the style visibility:hidden or display:none is set.

var b=$('id').visible(); // getter (Boolean)
$('id').visible( [false|true] );

Warning: Phi has a different behavior then jQuery where the style visibility:hidden is not treated to be invisible. We recommend to use .hide(), .show() or this function and not to set the style directly (i.e. item.style.display='none') to be safe.

.width()

Sets or returns the width of the item in pixel.

var w=$('id').width(); // getter
$('id').width( width ); // setter

Note: some items have a maximum or minimum width which can not be changed.

.zIndex()

Sets or returns the z-index of the item. A higher z-index brings an element to the front of an other item with a lower z-index. A z-index can also be negative and should be in the range of -1000 to 1000.

var z=$('id').zIndex(); // getter (Number)
$('id').zIndex( index ); // setter (Number)

Event handler

Using the provided shorthand of the event handler has the advantage that the event object can be normalized over different browser implementations. We highly recommend not to use the browser build in event handler like item.onclick. Using the shorthand without a function parameter triggers the handler manually. You can also create custom events using .on(), .off() and .trigger().

Note: all handler return a reference to the item itself.

.blur()

Triggered if the item gains focus.

$('id').blur(); // trigger: removes focus
$('id').blur( function( e ) {} ); // e=event object

Example:

$('id').blur( function( e ) { alert( e.type ); $(this).hide(); } ); // 

Hides the item after displaying the message box with blur as soon the item looses focus.

.change()

Triggers a change event or called if a item changed the content.

$('id').change(); // trigger: change
$('id').change( function( e ) {} ); // e=event object

Example:

$('lineedit').change( function() { $(this).val( $(this).val().toUpperCase() ); } );

Changes the text entered to upper case.

.click()

Triggers a click or reacts on mouse button clicks.

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

The normalized e.which can be used to detect the mouse button and is cross browser compatible:

  • 1 - left button
  • 2 - mid button
  • 3 - right button

Example:

$('button').click( function(e) { alert( 'button:'+e.which ); });

Displays a message box with the mouse button pressed.

.drop()

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

$('id').drop( function( e, obj ) {} ); // e=event object

obj has the following properties

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

Example:

$('id').drop( function( e, o ) { alert( o.target ); } );

Note: this handler can not be triggered manually.

See also: Drag&Drop How-To.

Warning: item.ondrop is not supported and is used differently in current browser implementations.

.dblclick()

Triggers a double click or reacts on double click events.

$('id').dblclick(); // trigger: double click
$('id').dblclick( function( e ){} ); // e=event object

Example:

$('button').dblclick( function() { $(this).hide(); } );

Hides the button on a double click.

.focus()

Gives an item focus or reacts on a focus event.

$('id').focus(); // trigger: focus
$('id').focus( function( e ){} ); // e=event object

Example:

$('button').click( function() { $('myitem').focus(); } );

Gives myitem focus after the button was clicked.

.keydown()

Triggers a key down or reacts on a key down event.

$('id').keydown(); // trigger: key down
$('id').keydown( function( e ){} ); // e=event object

Note: pressing a single meta key is also recognized in a key down event.

Example:

$('lineedit').keydown( function( e ) { alert( 'Pressed key code: '+e.which ); } );

Opens a message box containing the text with the code of the pressed key.

.keypress()

Triggers a key press or reacts on a key press event.

$('id').keypress(); // trigger: key press
$('id').keypress( function( e ){} ); // e=event object

You can usee.shiftKey, e.altKey and e.ctrlKey to find out if one of the meta keys where pressed.

Example:

$('lineedit').keypress( function( e ) { alert( 'Pressed key code: '+e.which ); } );

Opens a message box containing the text with the code of the pressed key.

Note: in Phi mode .keypress() and .keyup() are used similar.

.keyup()

Triggers a key up or reacts on a key press event.

$('id').keyup(); // trigger: key up
$('id').keyup( function( e ){} ); // e=event object

Note: in HTML mode pressing a single meta key is also recognized in a key up event.

Example:

$('lineedit').keyup( function( e ) { alert( 'Pressed key code: '+e.which ); } );

Opens a message box containing the text with the code of the pressed key.

Note: in Phi mode .keypress() and .keyup() are used similar.

.mousedown()

Triggers a mouse down or reacts on a mouse down (button) event. This is manly used to detect a drag operation.

$('id').mousedown(); // trigger: mouse down 
$('id').mousedown( function( e ){} ); // e=event object

Example:

$('image').mousedown( function() { alert( 'Mouse down' ); } );

Opens a message box containing the text on a mouse down event.

Warning: querying e.which for detecting a mid or right button click is not reliable in this case. Use .click() to be safe.

.mousemove()

Triggers a mouse move or reacts on a mouse move event.

$('id').mousemove(); // trigger: mouse move 
$('id').mousemove( function( e ){} ); // e=event object

Example:

$('rect').mousemove( function( e ) { $('lineedit').val( 'x: '+e.clientX+' y:'+e.clientY ); } );

Prints the mouse coordinates relative to the browser window into the line edit while moving over the rect area.

.mouseout()

Triggers a mouse out or reacts on a mouse out event (i.e. when the mouse pointer leaves an item)

$('id').mouseout(); // trigger: mouse out 
$('id').mouseout( function( e ){} ); // e=event object

Example:

$('rect').mouseout( function() { $(this).opacity( .2 ); } );

Sets the opacity to 20% when the mouse leaves the area of the rect item.

.mouseover()

Triggers a mouse over or reacts on a mouse over event (i.e. when the mouse pointer enters an item)

$('id').mouseover(); // trigger: mouse over 
$('id').mouseover( function( e ){} ); // e=event object

Example:

$('rect').mouseover( function() { $(this).opacity( 1. ); } );

Sets the opacity to fully opaque when the mouse enters the area of the rect item.

.mouseup()

Triggers a mouse up or reacts on a mouse up (button) event.

$('id').mouseup(); // trigger: mouse up
$('id').mouseup( function( e ){} ); // e=event object

Example:

$('image').mouseup( function() { alert( 'Mouse button released' ); } );

Opens a message box containing the text when a mouse button was released.

Warning: querying e.which for detecting a mid or right button click is not reliable in this case. Use .click() to be safe.

.on()

Binds a new event handler to an event. The type can be one of the build in events or a custom event. A custom event has to be triggered manually. The function returns a reference to it self.

$('id').on( 'type', function( e ){} ); // e=event object
$('id').on( 'type', function( e, args ) {} ); // 'args' can be a custom object wich is passed to .trigger()

Example:

$('button').on( 'click', function( e ) { alert( e.type ); } );
$('rect').on( 'mycloseevent', function( e, args ) { $(this).hide(); alert( args.par ) } );

.off()

Removes a build in or a custom event handler. The function returns a reference to it self. If func is omitted all events bound to type are removed. If a func parameter is passed, the func must have the same signature (i.e. exactly same string) as it was bound with .on().

$('id').off( 'type' ); // type=String
$('id').off( 'type', func );

Example:

$('button').off( 'click' ); // removes all 'click' events from button
$('button').off( 'click', function( e ) { alert( e.type ); } ); // removes only the 'click' function with the alert
$('rect').off( 'mycloseevent' );

.trigger()

Triggers an event bound with .on(). The parameter args kann be omitted. Otherwise it will passed to the .on() function.

$('id').trigger( 'type' );
$('id').trigger( 'type', args );

Example:

$('button').trigger( 'click' );
$('rect').trigger( 'mycloseevent', { par:'test' } ); // calls: $('rect').on( 'mycloseevent', function( e, args ) );

Additional notes

If you need a function Phi does currently not provide, you may contact us and place a request for the appropriate feature. Some more useful functions will be added in the future.