View source

class Interactive

package h2d

extends Object

implements Interactive

extended by Slider

@:directlyUsed@:allow(h2d.Scene)

A user input handler.

Hitbox area can be a rectangle, an ellipse or an arbitrary shape (h2d.col.Collider).

Note that Interactive does not reports its hitbox bounds in Object.getBounds unless Interactive.backgroundColor is set, in which case width and height are reported.

By default, Interactive only reacts to primary (left) mouse button for actions, see Interactive.enableRightButton for details.

Constructor

new(width:Float, height:Float, ?parent:Object, ?shape:Collider)

Create a new Interactive with specified parameters. width, height and parent with optional detailed shape.

Parameters:

width

The width of the Interactive hitbox.

height

The height of the Interactive hitbox.

parent

An optional parent h2d.Object instance to which Interactive adds itself if set.

shape

An optional detailed Interactive hitbox.

Variables

@:value(false)allowMultiClick:Bool = false

When enabled, allows to receive several onClick events the same frame.

backgroundColor:Null<Int>

If set, Interactive will draw a Tile with [width, height] dimensions of specified color (including alpha).

@:value(false)cancelEvents:Bool = false

Set the default hxd.Event.cancel mode.

@:value(Button)cursor:Null<Cursor> = Button

Cursor used when Interactive is under mouse cursor.

@:value(false)enableRightButton:Bool = false

When enabled, interacting with secondary mouse buttons (right button/wheel) will cause onPush, onClick, onRelease and onReleaseOutside callbacks. Otherwise those callbacks will only be triggered with primary mouse button (left button).

height:Float

Height of the Interactive. Ignored if Interactive.shape is set.

isEllipse:Bool

Performs an elliptic hit-test instead of rectangular one based on Interactive.width and height. Ignored if Interactive.shape is set.

@:value(false)propagateEvents:Bool = false

Set the default hxd.Event.propagate mode.

shape:Collider

Detailed shape collider for Interactive. If set, width and height properties are ignored for collision checks.

@:value(0)shapeX:Float = 0

Detailed shape X offset from Interactive.

@:value(0)shapeY:Float = 0

Detailed shape Y offset from Interactive.

width:Float

Width of the Interactive. Ignored if Interactive.shape is set.

Methods

blur():Void

Removes focus from interactive if it's focused. If Interactive is currently focused - onFocusLost event will be sent. Interactive won't lose focus if during onFocusLost call it will set Event.cancel to true.

focus():Void

Sets focus on this Interactive. If Interactive was not already focused and it receives focus - onFocus event is sent. Interactive won't become focused if during onFocus call it will set Event.cancel to true.

hasFocus():Bool

Checks if Interactive is currently focused.

isOver():Bool

Checks if Interactive is currently hovered by the mouse.

dynamiconCheck(e:Event):Void

Sent every frame when user hovers an Interactive but does not move the mouse. See Interactive.onMove for event when user moves the mouse.

Cancelling the Event will prevent interactive from becoming overed, causing Interactive.onOut if it was overed previously. Interactive would be treated as not overed as long as event is cancelled even if mouse is within the hitbox area.

dynamiconClick(e:Event):Void

Sent when the Interactive is clicked by the user.

Can be prevented to fire by calling Interactive.preventClick during or after Interactive.onPush event.

Interactive.onRelease is sent with Event.kind being ERelease just before this event.

dynamiconFocus(e:Event):Void

Sent when Interactive receives focus during Interactive.focus call.

Cancelling the Event will prevent the Interactive from becoming focused.

dynamiconFocusLost(e:Event):Void

Sent when Interactive lost focus either via Interactive.blur call or when user clicks on another Interactive/outside this Interactive hitbox area.

Cancelling the Event will prevent the Interactive from losing focus.

dynamiconKeyDown(e:Event):Void

Sent when this Interactive is focused and user pressed a keyboard key. Pressed key can be accessed through Event.keyCode.

dynamiconKeyUp(e:Event):Void

Sent when this Interactive is focused and user unpressed a keyboard key. Unpressed key can be accessed through Event.keyCode.

dynamiconMove(e:Event):Void

Sent when user moves within the Interactive hitbox area. See Interactive.onCheck for event when user does not move the mouse.

Cancelling the Event will prevent interactive from becoming overed, causing Interactive.onOut if it was overed previously. Interactive would be treated as not overed as long as event is cancelled even if mouse is within the hitbox area.

dynamiconOut(e:Event):Void

Sent when mouse exits Interactive hitbox area. Event.propagate and Event.cancel are ignored during onOut.

dynamiconOver(e:Event):Void

Sent when mouse enters Interactive hitbox area.

Event.propagate and Event.cancel are ignored during onOver. Propagation can be set with onMove event, as well as cancelling onMove will prevent onOver.

dynamiconPush(e:Event):Void

Sent when Interactive is pressed by the user.

dynamiconRelease(e:Event):Void

Sent when Interactive is unpressed under multiple circumstances. Always sent if user releases mouse while it is inside Interactive hitbox area.

		This happens regardless if that Interactive was pressed prior or not,
		and due to that it's not guaranteed that `Interactive.onPush` would precede this event.
		`Event.kind` is set to `ERelease` during this event.

Sent before Interactive.onReleaseOutside if this Interactive was pressed, but released outside its hitbox area.

		`Event.kind` is set to `EReleaseOutside` during this event.

	See `Interactive.onClick` and `Interactive.onReleaseOutside` methods for separate events that trigger only when user interacts with this particular Interactive.

dynamiconReleaseOutside(e:Event):Void

Sent when user presses the Interactive, moves the mouse outside its hitbox area and releases the mouse button.

Can be prevented to fire by calling Interactive.preventClick during or after Interactive.onPush event.

Interactive.onRelease is sent with Event.kind being EReleaseOutside just before this event.

dynamiconTextInput(e:Event):Void

Sent when this Interactive is focused and user inputs text. Character added can be accessed through Event.charCode.

dynamiconWheel(e:Event):Void

Sent when user scrolls mouse wheel above the Interactive. Wheel delta can be obtained through the Event.wheelDelta.

preventClick():Void

Reset current pressed state of the Interactive, preventing the onClick or onReleaseOutside being triggered when user releases mouse button.

startCapture(callb:Event ‑> Void, ?onCancel:() ‑> Void, ?touchId:Int):Void

Starts input events capture and redirects them to callb method until Interactive.stopCapture is called. While the method name may imply that only mouse events would be captured: This is not the case, as it will also capture all other input events, including keyboard events.

Starting event capture through Interactive.startCapture will convert Event.relX and relY to local coordinates of the Interactive and will restore them after invoking callb. In order to receive coordinates in scene coordinate space use Scene.startCapture.

Parameters:

callb

A callback method that receives hxd.Event when input event happens. Unless callb sets Event.propagate to true, event won't be sent to other Interactives.

onCancel

An optional callback that is invoked when Interactive.stopCapture is called.

stopCapture():Void

Stops current input event capture.

Inherited Variables

Defined by Object

private@:dox(show)allocated:Bool

A flag that indicates whether the object was allocated or not.

When adding children to allocated objects, onAdd is being called immediately, otherwise it's delayed until the whole tree is added to a currently active Scene.

@:value(1.)alpha:Float = 1.

The amount of transparency of the Object.

@:value(Alpha)blendMode:BlendMode = Alpha

The blending mode of the object.

If there is no Object.filter active, only applies to the current object (not inherited by children). Otherwise tells how the filter is blended with background.

filter:Filter

The post process filter for this object.

When set, Object.alpha value affects both filter and object transparency (use Drawable.color.a to set transparency only for the object).

name:String

The name of the object. Can be used to retrieve an object within a tree by using Object.getObjectByName.

read onlynumChildren:Int

How many immediate children this object has.

read onlyparent:Object

The parent object in the scene tree.

private@:dox(show)parentContainer:Object

The parent container of this object. See Object.contentChanged for more details.

private@:dox(show)posChanged:Bool

A flag that indicates that the object transform was modified and absolute position recalculation is required.

Automatically cleared on Object.sync and can be manually synced with the Object.syncPos.

@:value(0)rotation:Float = 0

The rotation angle of this object, in radians.

@:value(1)scaleX:Float = 1

The amount of horizontal scaling of this object.

@:value(1)scaleY:Float = 1

The amount of vertical scaling of this object.

@:value(true)visible:Bool = true

Is the object and its children are displayed on screen.

@:value(0)x:Float = 0

The x position (in pixels) of the object relative to its parent.

@:value(0)y:Float = 0

The y position (in pixels) of the object relative to its parent.

Inherited Methods

Defined by Object

private@:dox(show)addBounds(relativeTo:Object, out:Bounds, dx:Float, dy:Float, width:Float, height:Float):Void

Adds specified area in local coordinate space to the bounds. Expected to be used within Object.getBoundsRec.

Parameters:

relativeTo

An object relative to which the Object bounds coordinates should be. If not set, coordinates are in absolute coordinate space.

out

An output Bounds instance.

dx

The top-left X offset of the added bounds rectangle.

dy

The top-left Y offset of the added bounds rectangle.

width

The width of the added bounds rectangle.

height

The height of the added bounds rectangle.

addChild(s:Object):Void

Add a child object at the end of the children list.

addChildAt(s:Object, pos:Int):Void

Insert a child object at the specified position of the children list.

private@:dox(show)calcAbsPos():Void

Internal usage Calculates the absolute object position transform. See `Object.syncPos` for a safe position sync method. This method does not ensure that object parents also have up-to-date transform nor does it clear the `Object.posChanged` flag.

private@:value({ scaleY : 1., scaleX : 1. })@:dox(show)clipBounds(ctx:RenderContext, bounds:Bounds, scaleX:Float = 1., scaleY:Float = 1.):Void

Internal usage Clip the local bounds with our global viewport. Used during filter rendering in order to clip out areas that are off-screen and should not be rendered.

h2d.Scene note: clipBounds will always output bounds equivalent to entire window. This is done in order for scene to never clip out cameras as they may render virtually any area of the Scene.

private@:dox(show)constraintSize(maxWidth:Float, maxHeight:Float):Void

Advanced usage This can be called by a parent container to constraint the size of its children. Negative value mean that constraint is to be disabled.

For example, Text constraints it's maximum width, causing word-wrap to occur within constrained area.

See also:

contains(o:Object):Bool

Tells if the object is contained into this object children, recursively.

private@:dox(show)contentChanged(s:Object):Void

Advanced usage Called by the children of a container object if they have `parentContainer` defined in them. Primary use-case is when the child size got changed, requiring content to reevaluate positioning such as `Flow` layouts, but also can be used for other purposes.

private@:dox(show)draw(ctx:RenderContext):Void

Override this method in order to add custom graphics rendering to your Object. draw is invoked before rendering of the object children.

drawTo(t:Texture):Void

Draw the object and all its children into the given Texture.

drawToTextures(texs:Array<Texture>, outputs:Array<Output>):Void

Draw the object and all its children into the given Textures.

private@:dox(show)emitTile(ctx:RenderContext, tile:Tile):Void

Draws single Tile instance with this Object transform.

find<T>(f:Object ‑> Null<T>):Null<T>

Find a single object in the tree by calling f on each and returning the first not-null value returned, or null if not found.

findAll<T>(f:Object ‑> Null<T>, ?arr:Array<T>):Array<T>

Find several objects in the tree by calling f on each and returning all the not-null values returned.

Parameters:

arr

An optional array instance to fill results with. Allocates a new array if not set.

inlinegetAbsPos():Matrix

Returns the updated absolute position matrix. See Object.getMatrix for current matrix values.

getBounds(?relativeTo:Object, ?out:Bounds):Bounds

Return the bounds of the object for its whole content, recursively.

Parameters:

relativeTo

An optional object relative to coordinates of which bounds are returned. Returns bounds in the absolute coordinates if not set.

out

An optional bounds instance to fill. Allocates new Bounds instance and returns it if not set.

private@:dox(show)getBoundsRec(relativeTo:Object, out:Bounds, forSize:Bool):Void

Override this method in order to expand the reported bounds of an object. Object.addBounds can be used to add bounds with respect to relativeTo. Do not remove the super call.

Parameters:

relativeTo

An object relative to which the Object bounds coordinates should be.

out

An output Bounds instance.

forSize

Whether it's being called for Object.getSize or Object.getBounds.

getChildAt(n:Int):Object

Return the nth element among the immediate children list of this object, or null if there is no Object at this position.

getChildIndex(o:Object):Int

Return the index of the object o within the immediate children list of this object, or -1 if it is not part of the children list.

private@:dox(show)getMatrix(m:Matrix):Void

Populates m with current absolute object transform values. See Object.getAbsPos for up-to-date values.

getObjectByName(name:String):Object

Search for an object recursively by name, return null if not found.

getObjectsCount():Int

Return the total number of children in the whole tree, recursively.

getScene():Scene

Returns an h2d.Scene down the hierarchy tree or null if object is not added to Scene.

finalgetSize(?out:Bounds):Bounds

Similar to getBounds(parent), but instead of the full content, it will return the size based on the alignment of the object. For instance for a text, Object.getBounds will return the full glyphs size whereas getSize will ignore the pixels under the baseline.

Parameters:

out

An optional bounds instance to fill. Allocates new Bounds instance and returns it if not set.

globalToLocal(pt:Point):Point

Convert an absolute screen position into a local position relative to the object origin, applying all the inherited transforms.

Parameters:

pt

A position to convert and return. Modifies the Point instance as is.

inlineiterator():ArrayIterator_h2d_Object

Return an iterator over this object immediate children

localToGlobal(?pt:Point):Point

Convert a local position (or [0,0] if pt is null) relative to the object origin into an absolute screen position, applying all the inherited transforms.

Parameters:

pt

An optional position to convert and return. Allocates new Point at 0,0 position if not set. Modifies the Point instance as is.

move(dx:Float, dy:Float):Void

Move the object by the specified amount along its current direction (Object.rotation angle).

private@:dox(show)onAdd():Void

Sent when object is being added to an allocated scene.

Do not remove the super call when overriding.

private@:dox(show)inlineonContentChanged():Void

Should be called when Object content was changed in order to notify parent container. See Object.contentChanged.

private@:dox(show)onHierarchyMoved(parentChanged:Bool):Void

Sent when object was already allocated and moved within scene object tree hierarchy.

Do not remove the super call when overriding.

Parameters:

parentChanged

Whether Object was moved withing same parent (through Layers.ysort for example) or relocated to a new one.

private@:dox(show)onRemove():Void

Sent when object is removed from the allocated scene.

Do not remove the super call when overriding.

inlineremove():Void

Same as parent.removeChild(this), but does nothing if parent is null.

removeChild(s:Object):Void

Remove the given object from the immediate children list of the object if it's part of it.

removeChildren():Void

Remove all children from the immediate children list.

inlinerotate(v:Float):Void

Rotate the object by the given angle (in radians)

inlinescale(v:Float):Void

Scale uniformly the object by the given factor.

private@:dox(show)setParentContainer(c:Object):Void

Sets the parent container for this Object and it's children. See Object.contentChanged for more details.

inlinesetPosition(x:Float, y:Float):Void

Set the position of the object relative to its parent.

inlinesetScale(v:Float):Void

Set the uniform scale for the object.

private@:dox(show)sync(ctx:RenderContext):Void

Performs a sync of data for rendering (such as absolute position recalculation). While this method can be used as a substitute to an update loop, it's primary purpose it to prepare the Object to be rendered.

Do not remove the super call when overriding.

private@:dox(show)syncPos():Void

Ensures that object has an up-to-date position transform.