API Reference

Back to home

Callback functions:

• int (*handleKeyFunc)(int sym, int mod, int scancode, uint16_t unicode, int event)
  • Receives keyboard events as specified in the control descriptor file. Since the values are passed directly from the XML file to the callback function, you can use whatever data you wish for the various fields.
  • The event parameter is either TCO_KB_DOWN or TCO_KB_UP.
  • The model was taken directly as fields from the SDL keysym (see SDL_keysym.h).
• int (*handleDPadFunc)(int angle, int event)
  • Receives event from dpad controls, specifying the angle direction of the dpad, and whether the user is touching (TCO_KB_DOWN) or just released (TCO_KB_UP).
  • The angle is between -180 to 180 in degrees. 0 degrees corresponds to due east, -90 is north, 90 is south, and 180 or -180 is west.
• int (*handleTouchFunc)(int dx, int dy)
  • Provides relative (not absolute) touch motion on a toucharea control, much like a trackpad.
• int (*handleMouseButtonFunc)(int button, int mask, int event)
  • Handles mouse button events. The event is either TCO_MOUSE_BUTTON_UP or TCO_MOUSE_BUTTON_DOWN.
  • The button is one of "left", "right" and "middle", but the mask is completely customizable. Currently SDL uses the convention that the mask is a bitfield with shift 0x1, ctrl 0x2 and alt 0x4.
• int (*handleTapFunc)()
  • Handles tap events on toucharea controls. Often used as a shortcut for a click.
• int (*handleTouchScreenFunc)(int x, int y, int tap, int hold)
  • Provides absolute touch motion and both tap and hold events. This is really most used as the only control on the whole screen, providing a reasonable mouse interface with movement, click and an alternate hold event (often translated as right click). It is not suited for anything more complicated since it has no way of handling drag events or other keyboard modifiers.

---

int tco_initialize(tco_context_t *context, screen_context_t screenContext, struct tco_callbacks callbacks)

• Creates a tco_context_t. You must also provide the current screen_context_t and a struct of function pointers used as callbacks on specified inputs.
• Make sure to call tco_shutdown when finished with the provided context.
• Returns TCO_SUCCESS if successful.

int tco_loadcontrols(tco_context_t context, const char* filename)

• Attempts to load the control descriptor file from the given filename.
• The context must have been initialized with tco_initialize.
• Returns TCO_FAILURE if the file was not found or could not be loaded.
• Returns TCO_SUCCESS on success.

int tco_swipedown(tco_context_t context, screen_window_t window)

• Shows the configuration window and pauses the current game loop. This function may not provide expected behavior in a multithreaded application, since the calling thread will not return until the user swipes down to remove the configuration window.
• The context must have been initialized with tco_initialize.
• The configuration window should appear in front of the window that is passed in.
• WARNING: The window provided must already have its window group set and be an application window.

int tco_showlabels(tco_context_t context, screen_window_t window)

• If you want the labels to be shown on top of the application window at all times, then you should call this during initialization.
• The context must have been initialized with tco_initialize.
• The window parameter is the window handle of your current application window, on top of which the labels should appear.
• WARNING: The window provided must already have its window group set and be an application window.

int tco_touch(tco_context_t context, screen_event_t event)

• You must send touch events to the overlay to have them processed so that your callback functions will be called. This should be called for all touch events.
• The context must have been initialized with tco_initialize.
• The screen_event_t structure provides the actual touch information.

void tco_shutdown(tco_context_t context)

• Clean up the context. The reverse of tco_initialize.

Back to home