Understanding UI System and Building your Own Components

Understanding tk2dUIManager

The whole UI system is governed by tk2dUIManager. It contains a loop that looks for touch and mouse events and does raycasts to look for colliders. If a raycast hits a collider, it will check to see if it has tk2dUIItem attached to it.

Understanding tk2dUIItem

tk2dUIItem is the base control for all interactive items. To make an item interactive simply add tk2dUIItem to any GameObject with a collider. Once this is complete whenever tk2dUIManager does a raycast (touch and/or mouse interaction) that hit that collider it will begin to fire events.

Listening for tk2dUIItem events

List of events you can listen for:

• OnDown - Pressed down

• OnUp - Unpressed, possibly on exit of collider area without releasing

• OnClick - Click - down and up while not leaving collider area

• OnRelease - After on down, when touch/click is released (this could be anywhere)

• OnHoverOver - On mouse hover over (only if using mouse and hover is enabled (tk2dUIManager.areHoverEventsTracked=true) and if multi-touch is disabled(tk2dUIManager.useMultiTouch=false))

• OnHoverOut - On mouse hover, leaving collider (only if using mouse and hover is enabled(tk2dUIManager.areHoverEventsTracked=true) and if multi-touch is disabled(tk2dUIManager.useMultiTouch=false))

• OnDownUIItem - Same as OnDown above, except returns this tk2dUIItem

• OnUpUIItem - Same as OnUp above, except returns this tk2dUIItem

• OnClickUIItem - Same as OnClick above, except returns this tk2dUIItem

• OnReleaseUIItem - Same as OnRelease above, except returns this tk2dUIItem

• OnHoverOverUIItem - Same as OnHoverOver above, except returns this tk2dUIItem

• OnHoverOutUIItem - Same as OnHoverOut above, except returns this tk2dUIItem

An example of listening to events

void OnEnable()
{
    uiItem.OnDown += ButtonDown;
    uiItem.OnClickUIItem += Clicked;
}

void ButtonDown()
{
    Debug.Log("Button Down");
}

void Clicked(tk2dUIItem clickedUIItem)
{
    Debug.Log("Clicked:" + clickedUIItem);
}

//Also remember if you are adding event listeners to events you need to also remove them:
void OnDisable()
{
    uiItem.OnDown -= ButtonDown;
    uiItem.OnClickUIItem -= Clicked;
}

tk2dUIMask

The tk2dUIMask object is a special object that allows you to efficiently and almost effortlessly mask standard sprites. Once you select a mask, you will see a blue volume in scene view. All sprites appearing inside this volume will be clipped automatically.

It achieves this by using the tk2dUIMask object, and tk2d/Depth Mask shaders in conjunction. These shaders and scripts aren't meant for general use outside of this very specific task.

Refer to demo 4 - UI Masks in the tk2dUI_demo folder for a scene to help understand how they work.

Advanced tk2dUIItem

Within tk2dUIItem are some more advanced settings.

Child of Another UIItem

This will allow hierarchy parents to listen for events of this child. When checked it will look up the hierarchy and find the next tk2dUIItem and that will be it's ParentUIItem.

Register Events From Children

If a hierarchy child of this tk2dUIItem has 'Child of Another UIItem' set to true, this tk2dUIItem will receive all of its events. This allows for complex things like button within buttons systems.

Is Hover Events Enabled

Hover events can be disabled to increase performance. If you need hover events simply set this to true. Hover events are disabled automatically when running on multi-touch devices.

Send Message Target

While it is recommended you use events, there is built-in Send Message system in the inspector. Simply drag the GameObject (target) you wish to send a message to, into the 'Send Message Target' field. Once complete a list of fields will appear. Type the function name into the desired field. When this event occurs this function will be called via SendMessage.

Automatic Bounds Calculation

The tk2dUIItem has some additional functionality to help the editor best-guess a bounding collider. Bounds calculation recursively goes down the hierarchy until another collider is found. You can add objects to the “ignore bounds” array to ignore bounds of certain parts of the hierarchy. You can also consider additional hierarchies by adding them to the “extra bounds” array.