sdltk command
Name
sdltk - exposure of the SDL2 (Simple DirectMedia Layer) API.
Synopsis
sdltk option ?arg ...?
Description
This command is used to control portions of the Android (or Windows or Linux) system that the SDL2 framework exposes. Actual data processing for this framework is achieved by having handlers for virtual events.
sdltk powerinfo
Returns a list of key-value pairs describing the state of the battery. The keys are state, seconds, and percent. The possible values for the state are onbattery, nobattery, charging, charged, and unknown. The other items are reported as integer numbers.
sdltk accelerometer on|off
Turns event reporting of the device's accelerometer on or off. Creates top-level virtual events <<Accelerometer>> when turned on. This command is not usable on Windows and Linux.
sdltk accelbuffer axis
Returns the accelerometer values for axis (1..3) which have been read during the last second as a list of integer values in the range -32768 .. 32767. The time resolution is identical with the framerate (20 ms). The values can be read out anytime independent of the accelerometer event enable state. The buffer is filled based on occurrences of the <<Accelerometer>> virtual event, missed values with respect to the framerate are interpolated. This command is not usable on Windows and Linux.
sdltk textinput ?on|off ?x y ?hint???
Returns the state of the virtual keyboard or switches the virtual keyboard on or off. The optional coordinate pair is a hint for the system where the insertion cursor is displayed in screen coordinates. This allows the system to adjust the application's screen in order to display the insertion cursor when the virtual keyboard is active. The entry, ttk::entry, text, and spinbox widgets have standard bindings which activate text input on left mouse button press (or equivalent touch event) if the widget's state is not disabled. Activation of text input for these widgets can be turned off entirely by providing a dummy bindtag named SdlTkNoTextInput. Android specific: the hint parameter is an integer which controls the kind of virtual keyboard to be displayed. Known values are 0 (normal keyboard), 2 (number input), 3 (phone number input), 4 (date/time input).
sdltk android
Returns true when running on Android, false otherwise, i.e. when built for Windows or Linux platforms.
sdltk framebuffer
Returns true when the video driver resembles a framebuffer, i.e. no windowing manager is available. Currently this is the case for Android, the Raspberry Pi video driver (RPI), the Linux KMSDRM video driver, and the jsmpeg video driver.
sdltk isandroidtv
Returns true when running on an AndroidTV device (currently untested).
sdltk ischromebook
Returns true when running on a Chromebook (currently untested).
sdltk maxroot
Returns the maximum size of the root window as two element list made up of width and height in pixels. The maximum size is device dependent and determined by the maximum texture size of the underlying OpenGL/OpenGLES drivers.
sdltk root ?width height?
When invoked without width and height parameters the command returns the current size of the root window as two element list of integers. When width and height are given, the root window is resized to the size given. When both width and height are given as zero, the root window is resized to the device screen size.
sdltk vsync
Waits until the next screen refresh and returns the number of screen refreshes which happened during that wait. The maximum wait time is limited to 20 milliseconds (the internal tick rate for screen updates) but can be longer due to system load.
sdltk viewport ?x y ?width height??
Changes the viewport (root window to device screen) to allow zooming and panning of the root window. When invoked without parameters, the current viewport settings are returned as a four element list of integers. When the x and y parameters are given, the viewport is shifted that x and y are shown in the top-left corner of the screen. When all four parameters are given, the viewport is adjusted accordingly, i.e. width and height determine the zoom factor, and x and y the top-left corner of the view. Note however, that the aspect ratio is retained, i.e. the given parameters are adjusted to keep the aspect.
sdltk touchtranslate ?mask?
Controls touchscreen event translation, or reports the current translation state. mask is a bit mask controlling various translations. Bit 0 (mask 1) turns on translation of middle/right mouse buttons, i.e. fast wipes with one finger are translated to mouse button 2 press/motion/release events to allow scrolling of listboxes, entries, and text widgets. Slow wipes still deliver mouse button 1 motion events. Holding down one finger for about a second is translated into mouse button 3 press for context menus. Bit 1 (mask 2) turns on pinch-to-zoom with two fingers which is reported as a virtual event named <<PinchToZoom>>. Bit 2 (mask 4) turns on pinch-to-zoom and wipes for zooming and panning the root window. When both, bits 1 and 2 are on (mask equals 6), zooming the root window requires three instead of two fingers and panning four instead of three fingers. Bit 3 (mask 8) turns on translation of finger events to the current viewport settings, i.e. the <<FingerUp>>, <<FingerDown>>, and <<FingerMotion>> events are translated to the current viewable portion of the root window instead of the device screen. Bit 4 (mask 16) turns on reporting of finger down/up events for up to 10 fingers as <ButtonPress> and <ButtonRelease> events with button numbers 10 to 19. However, no provisions are taken to ensure proper implicit button grabs like a real X server would do, thus use this feature with caution. The default touchscreen translation mode on startup is mask 13 (bits 0, 2, and 3 are on), i.e. everything except <<PinchToZoom>> and finger down/up as <ButtonPress>/<ButtonRelease> is enabled. On Windows and Linux platforms only bit 3 (mask 8) to control the viewport is supported.
sdltk screensaver ?on|off?
Turns the screen saver on or off or reports the current state of the screensaver.
sdltk joystick ids
Returns a list made up joystick ids (in SDL2 referred to as joystick instance identifiers) which are reported in related virtual events. These ids are integer numbers which increase for each new detected joystick.
sdltk joystick name id
Returns the name of the joystick identified by id.
sdltk joystick guid id
Returns the globally unique id (GUID, 128 bit string) of the joystick identified by id.
sdltk joystick numaxes id
Returns the number of axes of the joystick identified by id.
sdltk joystick numballs id
Returns the number of balls of the joystick identified by id.
sdltk joystick numbuttons id
Returns the number of buttons of the joystick identified by id.
sdltk joystick numhats id
Returns the number of hats of the joystick identified by id.
sdltk addfont filename
Adds TrueType font(s) contained in filename and returns the font family names which were added. If the font already has been loaded an error is thrown.
sdltk hasgl
Returns true when OpenGL support is available, e.g. for the 3D canvas widget.
sdltk log priority message
Outputs the log message message using SDL's logging facility. priority specifies the priority of the log message and must be one of verbose, debug, info, warn, error, or fatal (from lowest to highest).
sdltk deiconify
Deiconifies the SDL root window (not usable on Android and Wayland).
sdltk fullscreen
Makes the SDL root window into a fullscreen window (not usable on Android and Wayland). The SDL root window must be resizable (command line option -sdlresizable).
sdltk iconify
Iconifies (minimizes) the SDL root window (not usable on Android and Wayland).
sdltk maximize
Maximizes the SDL root window (not usable on Android and Wayland). The SDL root window must be resizable (command line option -sdlresizable).
sdltk restore
Restores the last unmaximized geometry of the SDL root window (not usable on Android and Wayland).
sdltk withdraw
Withdraw (hides entirely) the SDL root window (not usable on Android and Wayland).
sdltk opacity value
Query or set the opacity of the SDL root window. value must be a floating point number between 0.0 and 1.0 (not usable on Android). On POSIX operating systems the window manager must support transparent toplevels for this setting having an effect.
sdltk fonts
Returns a list made up of font information in the form of three elements XLFD, file name, font index of all registered fonts.
sdltk vrmode ?mode ?distortion rescale??
Experimental VR headset mode currently only supported on the Android platform. If mode is specified, it changes the VR headset mode to one of the following: Mode 0 for normal operation, in mode 1 the root window is duplicated along its horizontal axis and scaled up or down, in mode 2 the root window must be managed as left and right halves by the application, and in mode 3 the root window is duplicated along its horizontal axis without scaling. For all modes except mode 0 touch screen panning and zooming on Android is turned off and touch coordinates in X are reported equal for both left and right halves of the screen. All modes except mode 0 turn on a shader performing a barrel distortion (when OpenGL ES 2 is available) which theoretically compensates the effect of lenses of a VR headset. The optional parameters distortion and rescale, if present, must be specified as floating point numbers and control the degree of distortion. In order to flip the image(s) horizontally and/or vertically, mode can be bitwise or'ed with 4 (horizontal flip) and/or 8 (vertical flip) for all modes except 0. If mode and additional arguments are omitted, the currently active mode including the distortion control parameters are returned as a Tcl list of three elements.
sdltk pointer ?flag?
Queries or sets the state of the mouse pointer shape. If present, flag must be a boolean value and specifies the new state. If not present, the current state is returned as 0 (off) or 1 (on).
sdltk touchcalibration ?xmin xmax ymin ymax swapxy?
Queries or sets the calibration data for resistive touchscreens supported on certain SDL video drivers (currently Linux EVDEV devices with KMSDRM or RPI video drivers). The calibration data consists of five integer numbers which are returned as a list, when the command is called without parameters.
sdltk size ?width height?
Queries the size of the enclosing SDL root window when width and height parameters are omitted. A two element list is returned with the current width and height in pixels. If parameters are given, the enclosing SDL root window is resized respectively, provided that the command line parameter -sdlresizeable was specified and the command line parameter -sdlfullscreen was not specified on startup. However, changing the SDL root window size is not supported on framebuffer like devices (see sdltk framebuffer).
Touchscreen and Accelerometer Events
Using the sdltk framework usually requires liberal use of virtual event handlers. The virtual events include:
<<Accelerometer>>
Event associated with the accelerometer (activated with sdltk accelerometer on). %s is substituted with the accelerometer axis {1..3} and %x with the accelerometer value in the range {-32768...+32767}. This event is reported to toplevel widgets only.
<<FingerDown>>
A touch event.
<<FingerUp>>
A touch completion event.
<<FingerMotion>>
A touch movement (sliding) event. The fields %x and %y are substituted with the finger position scaled to {0...9999} of the device screen or viewport, %X and %Y with the motion difference scaled to {-9999...+9999}, %t with the pressure scaled to {0...9999}, and %s with the finger identifier {1...10}. These substitutions are performed for all finger related touch events.
<<PinchToZoom>>
A zoom gesture event. %X and %Y are substituted with the root window coordinate of the center of the two fingers, %x with the distance between the two fingers, and %y with the angle measured in 64 times degrees CCW starting at 3 o'clock. The finger state is reported in the %s substitution as 0 (zoom motion), 1 (zoom start, i.e. 2nd finger down event), 2 (zoom end by 1st finger up event), 3 (zoom end by 2nd finger up event).
Joystick Events
Following virtual events are reported for joysticks and game controllers:
<<JoystickAdded>>, <<JoystickRemoved>>
Event generated when a joystick or game controller is plugged or unplugged. The field %X is substituted with the joystick id (instance identifier in SDL2 terminology).
<<JoystickMotion>>
Similar to <<Accelerometer>> this event is reported when the position of the joystick has changed. An additional substitution is made for %X which receives the joystick id (instance identifier in SDL2 terminology).
<<TrackballMotion>>
A joystick trackball has moved. The fields %x and %y are substituted with the deltas of the move, %s with the trackball number counted from 1, the field %X indicates the joystick id.
<<HatPosition>>
A joystick hat has changed. The field %x is substituted with the value of the hat, %s with the hat number counted from 1, the field %X indicates the joystick id.
<<JoystickButtonUp>>, <<JoystickButtonDown>>
A joystick button was pressed or released. The field %s is substituted with the button number counted from 1, the field %X indicates the joystick id.
Events related to the device screen
<<ViewportUpdate>>
This event is sent to toplevel widgets when the viewport has changed. %x and %y are substituted with the viewport offset (top-left corner of the screen), %X and %Y with the width and height, respectively, and %s with the scale factor (relation of root window size to displayed size) scaled to 10000.
Events related to the app life-cycle
These events are direct translations from SDL events (SDL_APP_* in SDL header files) and depend on platform support. They are reported to toplevel widgets only.
<<LowMemory>>
System is in low memory situation. Although implemented for Android and iOS, this event was never observed in reality.
<<Terminating>>
App is terminating. Although implemented for Android and iOS, this event was never observed in reality, maybe due to timing regarding threads.
<<WillEnterBackground>>
App's screen will be put in background.
<<DidEnterBackground>>
App's screen is in the background.
<<WillEnterForeground>>
App's screen will be put in foreground. On Android, not reported on startup of the app.
<<DidEnterForeground>>
App's screen is in the foreground. On Android, not reported on startup of the app.
Note that on Android the system may kill an app at any time due to low memory situations. In order to keep some app state persistent, the best option is to record each change immediately. Another option is using the <<WillEnterBackground>> virtual event since it may be received before unexpected app termination.
Accelerometer Example
proc showaccel {canvas axis value} {
set ix 0
set iy 0
if {$axis == 1} {
set ix [expr {$value / 256}]
} elseif {$axis == 2} {
set iy [expr {$value / 256}]
} elseif {$axis == 3} {
set ::pos(t) [expr {($value / 256) % 360}]
} else {
return
}
if {![info exists ::pos(x)]} {
set ::pos(x) [expr [winfo width $canvas] / 4]
set ::pos(y) [expr [winfo height $canvas] / 4]
set ::pos(t) 0
}
set ::pos(x) [expr {$::pos(x) + $ix}]
set ::pos(y) [expr {$::pos(y) + $iy}]
if {$::pos(x) < 50} {
set ::pos(x) 50
} elseif {$::pos(x) > [winfo width $canvas] - 50} {
set ::pos(x) [expr {[winfo width $canvas] - 50}]
}
if {$::pos(y) < 50} {
set ::pos(y) 50
} elseif {$::pos(y) > [winfo height $canvas] - 50} {
set ::pos(y) [expr {[winfo height $canvas] - 50}]
}
if {$axis == 3} {
$canvas delete a
set x0 [expr {$::pos(x) - 48}]
set x1 [expr {$x0 + 96}]
set y0 [expr {$::pos(y) - 48}]
set y1 [expr {$y0 + 96}]
$canvas create arc $x0 $y0 $x1 $y1 -fill yellow -outline red \
-width 6 -start [expr {330 - $::pos(t)}] -extent -300.0 -tags a
}
}
wm attributes . -fullscreen 1
canvas .c -bg black -bd 0 -highlightthickness 0
pack .c -side top -fill both -expand 1 -padx 0 -pady 0
set f [open [info script]]
.c create text 20 120 -anchor nw -tag s -font {Courier 5} -text [read $f] \
-fill gray50
close $f
button .c.x -text Exit -command {exit 0}
.c create window 30 60 -anchor nw -tag x -window .c.x
bind . <<Accelerometer>> {showaccel .c %s %x}
sdltk accelerometer on
Pinch-to-zoom Example
proc showzoom {canvas rootx rooty dist angle state} {
$canvas itemconf t -text "XY: $rootx,$rooty L: $dist P: $angle S: $state"
$canvas delete a
# state 0 -> zoom motion
# state 1 -> zoom start
# state 2 -> zoom end, 1st finger up
# state 3 -> zoom end, 2nd finger up
if {$state < 2} {
set phi [expr {$angle / 64.0}]
set x0 [expr {$rootx - [winfo rootx $canvas] - $dist / 2}]
set x1 [expr {$x0 + $dist}]
set y0 [expr {$rooty - [winfo rooty $canvas] - $dist / 2}]
set y1 [expr {$y0 + $dist}]
$canvas create arc $x0 $y0 $x1 $y1 -fill yellow -outline red -width 6 \
-start [expr {330 - $phi}] -extent -300.0 -tags a
}
}
wm attributes . -fullscreen 1
sdltk touchtranslate 15 ;# turn <<PinchToZoom>> on
canvas .c -bg black -bd 0 -highlightthickness 0
pack .c -side top -fill both -expand 1 -padx 0 -pady 0
set f [open [info script]]
.c create text 30 120 -anchor nw -tag s -font {Courier 6} -text [read $f] \
-fill gray50
close $f
.c create text 30 30 -anchor w -fill green -tag t -font {Helvetica 16} \
-text "Try pinch-to-zoom with two fingers"
button .c.x -text Exit -command {exit 0}
.c create window 30 60 -anchor nw -tag x -window .c.x
bind .c <<PinchToZoom>> {showzoom %W %X %Y %x %y %s}
Disable Android keyboard input to a text widget
bindtags .mywidget [list SdlTkNoTextInput {*}[bindtags .mywidget]]