TouchGamepad

class TouchGamepad

Bases: InputDevice

A gamepad drawn on a touch screen and played with the fingers: a stick that appears where a finger lands on the left of the screen, a look area on the right (dragging moves the right stick), and buttons. It is an InputDevice of the GAMEPAD class, registered with the InputDeviceManager, so a game that supports gamepads plays on a phone without a gamepad of its own.

setup_window() draws it over the window in a display region of its own and reads that window’s touches (GraphicsWindow::get_touch_info()). By default it shows itself while the window’s mouse mode is relative (a game’s mouse look: on Android the fingers then stop standing in for the mouse), so menus are tapped as with a mouse and play has the pad; or set_visibility() shows or hides it outright.

The buttons are GamepadButton handles at places given as fractions of the window’s width and height, sized in fractions of its shorter side; set_default_layout() puts the face buttons, the shoulders, start and back and a D-pad where thumbs reach them on a phone held sideways.

A game themes it: set_button_images() draws a button with its own art (a square image the button’s diameter wide; another while pressed), set_stick_images() the stick’s base and knob, set_font() and set_label_color() the labels (an empty label draws none), set_opacity() the whole of it. Without them, translucent white discs with white labels.

Looking: a stick turns at a rate, which is not how a camera follows a finger. A game with mouse look sets LM_delta and adds get_look_delta() (how far the look finger moved since the last frame) to its mouse motion, so the view follows the finger; LM_stick (the default) moves the right stick instead, for games that only read gamepads.

A finger that is already down when the gamepad appears (the tap that resumed the game) is ignored until it lifts.

Inheritance diagram

digraph inheritanceadd67d30b6 { bgcolor=transparent; rankdir=BT; size="8.0, 12.0"; "DTOOL_SUPER_BASE" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style=""]; "InputDevice" [URL="acron.core.InputDevice.html#acron.core.InputDevice",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedReferenceCount" -> "InputDevice" [arrowsize=0.75,style=""]; "ReferenceCount" [URL="acron.core.ReferenceCount.html#acron.core.ReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "ReferenceCount" [arrowsize=0.75,style=""]; "TouchGamepad" [URL="acron.core.TouchGamepad.html#acron.core.TouchGamepad",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "InputDevice" -> "TouchGamepad" [arrowsize=0.75,style=""]; "TypedObject" [URL="acron.core.TypedObject.html#acron.core.TypedObject",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "TypedObject" [arrowsize=0.75,style=""]; "TypedReferenceCount" [URL="acron.core.TypedReferenceCount.html#acron.core.TypedReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedObject" -> "TypedReferenceCount" [arrowsize=0.75,style=""]; "ReferenceCount" -> "TypedReferenceCount" [arrowsize=0.75,style=""]; }

enum LookMode

enumerator LM_stick = 0

dragging in the look area moves the right stick

enumerator LM_delta = 1

it only reports get_look_delta() (a game’s mouse look)

enum Visibility

enumerator V_auto = 0

shown while the window’s mouse mode is relative

enumerator V_shown = 1

enumerator V_hidden = 2

TouchGamepad.__init__()

Makes a gamepad with the default layout; it is drawn and played once setup_window() names a window.

TouchGamepad.add_button()

Adds a button: the GamepadButton it presses, its label, its centre in fractions of the window’s width and height (0, 0 is the top left), and its radius in fractions of the window’s shorter side.

TouchGamepad.clear_buttons()

Removes every button (the sticks stay).

TouchGamepad.clear_window()

Undoes setup_window(): the gamepad is no longer drawn, played or registered.

TouchGamepad.get_button_label()

Returns a button’s label (”” if the gamepad has no such button), for a game’s prompts.

static TouchGamepad.get_class_type()

TouchGamepad.get_look_delta()

How far the look finger moved since the last frame, in window pixels (x right, y down, like the window’s pointer); zero without one. Scaled by the look sensitivity.

TouchGamepad.get_look_mode()

Returns what set_look_mode() set.

TouchGamepad.get_look_sensitivity()

Returns what set_look_sensitivity() set.

TouchGamepad.get_visibility()

Returns what set_visibility() set.

TouchGamepad.get_window()

Returns the window the gamepad is drawn on and played on, or NULL.

TouchGamepad.is_shown()

Whether the gamepad is on the screen now.

TouchGamepad.set_button_images()

Draws a button with the game’s own art: a square image the button’s diameter wide, and another while it is pressed (else the same one, brighter). NULL goes back to the plain disc.

TouchGamepad.set_default_layout()

The buttons of a phone held sideways: A, B, X and Y under the right thumb, the shoulders at the top corners, start and back at the top, and a small D-pad on the left above the stick.

TouchGamepad.set_font()

The font of the buttons’ labels (NULL: TextNode’s default).

TouchGamepad.set_label_color()

The colour of the buttons’ labels.

TouchGamepad.set_label_shadow()

The colour of a soft shadow under the labels, for reading them over a bright scene (half-transparent black by default; a zero alpha draws none).

TouchGamepad.set_look_mode()

Whether dragging in the look area moves the right stick (LM_stick, the default) or only reports get_look_delta() (LM_delta).

TouchGamepad.set_look_sensitivity()

Scales how far the right stick moves for a drag in the look area (1 by default: a drag of 2% of the screen’s shorter side in a frame is a full push).

TouchGamepad.set_opacity()

How opaque the whole gamepad is, 0..1 (1 by default: the art’s own alpha).

TouchGamepad.set_stick_images()

Draws the stick with the game’s own art: the base (the stick’s whole reach) and the knob (under the thumb), both square images. NULL goes back to the plain discs.

TouchGamepad.set_visibility()

Shows the gamepad, hides it, or (V_auto, the default) shows it while the window’s mouse mode is relative. A hidden gamepad has its sticks centred and its buttons up.

TouchGamepad.setup_window()

Draws the gamepad over the given window, reads that window’s touches and registers the gamepad with the InputDeviceManager. The gamepad updates itself every frame (a task on the global task manager); poll() is also fine to call.