urMus - Audio and Media Interactions and Interfaces on Mobile Phones


urMus

API Documentation

Region API

These functions are members of any created region. Some aspects of urMus Regions are inspired by the concept of a frame in the WoW addon API. For example arguments to region creation or layering are compatible.

Region:Handle

Synopsis

region:Handle("handler", function)
region:Handle("handler", nil)

Description

Sets the action handler callback function for this given region. The function called should be of the function(region, ...), with extra arguments depending on the event type. If nil is passed for the function parameter, the current handler will be removed.

Arguments

Region:ReadHandle

Synopsis

function = region:ReadHandle("handler")

Description

Reads the action handler callback function for this given region. Will return nil if no function is currently set for a given handler.

Arguments

Region:SetHeight

Synopsis

region:SetHeight(heightInPx)

Description

Sets the height of the region in pixels. Will reflow children if this affects their positioning.

Arguments

Region:SetWidth

Synopsis

region:SetWidth(widthInPx)

Description

Sets the width of the region in pixels. Will reflow children if this affects their positioning.

Arguments

Region:Show

Synopsis

region:Show()

Description

Makes the given region visible. Note that this is still subject to its parent's visibility.

Region:Hide

Synopsis

region:Hide()

Description

Makes the given region hidden.

Region:EnableInput

Synopsis

region:EnableInput(doEnable)

Description

Enables or disables OnInput events for the given region. This allows regions which would normally receive events to in effect "bubble up" their events to parent regions. Defaults to no.

Arguments

Region:EnableHorizontalScroll

Synopsis

region:EnableHorizontalScroll(doEnable)

Description

Enables or disables horizontal scrolling for the given region. If enabled and triggered, the region will send out OnHorizontalScroll events its handlers and physically scroll itself on the page.

Arguments

Region:EnableVerticalScroll

Synopsis

region:EnableVerticalScroll(doEnable)

Description

Enables or disables vertical scrolling for the sgiven region. If enabled and triggered, the region will send out OnVerticalScroll events its handlers and physically scroll itself on the page.

Arguments

Region:EnableMoving

Synopsis

region:EnableMoving(doEnableMoving)

Description

Set whether to enable/disable moving for this region. Defaults to no.

Arguments

Region:EnableResizing

Synopsis

region:EnableResizing(doEnableResizing)

Description

Set whether to enable or disable resizing for this region. Defaults to no. If enabled, pinch zoom gestures will scale the object.

Arguments

Region:SetAnchor

Synopsis

region:SetAnchor("anchorLocation")
region:SetAnchor("anchorLocation", relativeRegion)
region:SetAnchor("anchorLocation", relativeRegion, "relativeAnchorLocation")
region:SetAnchor("anchorLocation", relativeRegion, "relativeAnchorLocation", offsetX, offsetY)
region:SetAnchor("anchorLocation", offsetX, offsetY)

Description

Allows the region object to "attach" itself to a given point location on a parent or relative region. In this way, changing a parent object will move its children in a well-specified way. If offsetX is given, offsetY must also be given. Otherwise they default to (0,0).

Arguments

Region:Layer

Synopsis

"layerName" = region:Layer()

Returns

Region:SetLayer

Synopsis

region:SetLayer("layerName")

Description

Changes the z-index of the region.

Arguments

Region:Parent

Synopsis

parent = region:Parent()

Description

Returns a reference to the parent region.

Region:SetParent

Synopsis

region:SetParent(parent)

Arguments

Region:Children

Synopsis

child1, child2, ... = region:Children()

Returns

Region:Name

Synopsis

rName = region:Name()

Returns

Region:Bottom

Synopsis

bottomY = region:Bottom()

Description

Gets the Y coordinate of bottom of the region, offset from the side of the screen.

Returns

Region:Center

Synopsis

centerX, centerY = region:Center()

Description

Gets the center X and Y coordinates for the region.

Returns

Region:Height

Synopsis

heightInPx = region:Height()

Returns

Region:Left

Synopsis

leftX = region:Left()

Returns

Region:Right

Synopsis

rightX = region:Right()

Returns

Region:Top

Synopsis

topY = region:Top()

Returns

Region:Width

Synopsis

widthInPx = region:Width()

Returns

Region:Anchor

Synopsis

anchorLocation, relativeToRegion, relativeAnchorLocation, offsetX, offsetY = region:Anchor()

Description

Returns information about the current anchor point settings for this region.

Returns

Region:IsShown

Synopsis

isShown = region:IsShown()

Returns

Region:IsVisible

Synopsis

isVisible = region:IsVisible()

Returns

Region:SortStrata

Region:Alpha

Synopsis

opacity = region:Alpha()

Description

Gets the alpha opacity of this region.

Returns

Region:SetAlpha

Synopsis

region:SetAlpha(opacity)

Description

Set the alpha opacity of this region.

Arguments

Region:Texture

Synopsis

region:Texture()
region:Texture("imageName.ext")

Description

Instantiates and sets a new texture object which is tied to this region.

Arguments

Region:TextLabel

Synopsis

region:TextLabel()

Description

Instantiates and sets a name text label object inside of this region.

Region:Lower

Synopsis

region:Lower()

Description

Lower this region on the viewing hierarchy. This is useful if two regions have the same visibility and they should be higher / lower than another.

Region:Raise

Synopsis

region:Raise()

Description

Raise this region in the viewing hierachy. See Lower()

Region:IsTopLevel

Synopsis

isTopLevel = region:IsTopLevel()

Returns

Region:MoveToTop

Synopsis

region:MoveToTop()

Description

Moves this region to the top of the page viewing hierarchy.

Region:EnableClamping

Synopsis

region:EnableClamping(doEnableClamping)

Description

If enabled, the region can never be dragged outside of the screen boundaries.

Arguments

Region:RegionOverlap

Synopsis

isOverlapping = region:RegionOverlap(otherRegion)

Description

Helper function to check whether two regions are overlapping eachother.

Arguments

Returns

Region:UseAsBrush

Synopsis

region:UseAsBrush()

Description

Given a region, use this as a draggable "brush" object to paint to. If a texture hasn't been instantiated for this region already, it will give it a default one.

Region:EnableClipping

Synopsis

region:EnableClipping(doEnable)

Description

Enables or disables clipping for the region. In other words, clipping enabled means that only parts of the region that are within the current clip region will be viewable on screen

Arguments

Region:ClipRegion

Synopsis

leftX, bottomY, width, height = region:ClipRegion

Description

Gets the current clip region's bounding box.

Returns

Region:SetClipRegion

Synopsis

region:SetClipRegion(leftX, bottomY, width, height)

Description

Sets the current clip region's bounding box.

Arguments

Event handling

OnDragStart

Description

Fires when a region starts being dragged. This is requires that the region has been made movable via EnableMoving().

OnDragStop

Description

Fires when a region stops being dragged.

OnEnter

Description

Fires when it has been detected that an input device has entered a given region.

OnLeave

Description

Fires when it has been detected that an input device has left a given region.

OnTouchDown

Description

Fires when a touch event happens inside a region that takes input. This must be enabled via EnableInput(). This will only be triggered for the topmost region that takes input.

OnTouchUp

Description

Fires when a touch event is released while inside a region that takes input. This must be enabled via EnableInput(). This will only be triggered for the topmost region that takes input.

OnDoubleTap

Description

Fires when a double-tap touch event is performed while inside a region that takes input. This must be enabled via EnableInput(). This will only be triggered for the topmost region that takes input.

OnHide

Description

Fires when an object has been hidden.

OnShow

Description

Fires when an object is made to be shown. Note that this is different from being visible; if the parent object is still invisible then this will still fire; however the object itself will not be actually visible on screen.

OnUpdate

Handler Synopsis

function(region, elapsed)

Description

Fires when a the screen is about to be redrawn. elapsed is the time since the last screen update in seconds.

OnNetConnect

Handler Synopsis

function(region, hostname)

Description

Fires when a network service is found via the ZeroConf system. Can only trigger after StartNetDiscovery(). hostname is the name of the found host.

OnNetDisconnect

Handler Synopsis

function(region, hostname)

Description

Fires when a network service is no longer available via the ZeroConf system. Can only trigger after StartNetDiscovery(). hostname is the name of the host no longer available.

OnOSCMessage

Handler Synopsis

function(region, arg1, [arg2, ...])

Description

Fires when an OSC message was received. Can only trigger after StartOSCListener() was called. Returns a variable number of arguments in accordance with the sent OSC message.

OnAccelerate

Handler Synopsis

function(region,x, y, z)

Description

Fires when an acceleration event is detected. No guarantees are made about the frequency of its updates. Arguments are the x, y, and z axis acceleration values in units of g (typically between -1 and 1).

OnRotation

Handler Synopsis

function(region, x, y, z)

Description

Fires when a gyroscpe event is detected. No guarantees are made about the frequency of its update. Arguments are the x, y, and z axis angular velocity values.

OnHeading

Handler Synopsis

function(region,x,y, z, north)

Description

Fires when the heading for the given device changes. Note that this is only possible if the device supports compass directions.

OnLocation

Handler Synopsis

function(region,latitude, longitude)

Description

Fires when the location of the given device changes. Note this is only possible with a device which supports GPS coordinate finding.

OnHorizontalScroll

Handler Synopsis

function(region, scrollspeedX)

Description

Fires when a given region is scrolled horizontally. This handler returns scrollspeedX, the velocity of the current scroll.

OnVerticalScroll

Handler Synopsis

function(region, scrollspeedY)

Description

Fires when a given region is scrolled vertically. This handler returns scrollspeedY, the velocity of the current scroll.

OnMove

Handler Synopsis

function(region, x, y, dx, dy)

Description

Fires when a touch event moves within the region. This handler returns the old position x, and y as well as the relative distance moved inside the region dx, dy.

OnPageEntered

Description

Fires when the page that the region belongs to has been entered into.

OnPageLeft

Description

Fires when the page that the region belongs to is left.

urMus API Overview