<h2>Name</h2>

<b>sdltk</b> - exposure of the SDL2 (Simple DirectMedia Layer) API.

<h2>Synopsis</h2>

<tt>sdltk <i>option</i> ?<i>arg

<h2>Description</h2>

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.

<tt>sdltk powerinfo</tt>

    Returns a list of key-value pairs describing the state of the battery.

<tt>sdltk accelerometer on|off</tt>

    Turns event reporting of the device's accelerometer on or off. Creates top-level virtual events <tt><<Accelerometer>></tt> when turned on. This command is not usable on Windows and Linux.

<tt>sdltk accelbuffer

    Returns the accelerometer values for (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 <tt><<Accelerometer>></tt> virtual event, missed values with respect to the framerate are interpolated. This command is not usable on Windows and Linux.

<tt>sdltk textinput ?on|off ?<i>x y</i>

    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 <tt>entry</tt>, <tt>ttk::entry</tt>, <tt>text</tt>, and <tt>spinbox</tt> 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 <tt>SdlTkNoTextInput</tt>. Android specific: the 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).

<tt>sdltk android</tt>

    Returns true when running on Android, false otherwise, i.e. when built for Windows or Linux platforms.

<tt>sdltk framebuffer</tt>

    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), and the Linux KMSDRM video driver.

<tt>sdltk isandroidtv</tt>

    Returns true when running on an AndroidTV device (currently untested).

<tt>sdltk ischromebook</tt>

    Returns true when running on a Chromebook (currently untested).

<tt>sdltk maxroot</tt>

    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.

<tt>sdltk root ?<i>width

    When invoked without and parameters the command returns the current size of the root window as two element list of integers. When and are given, the root window is resized to the size given. When both and are given as zero, the root window is resized to the device screen size.

<tt>sdltk vsync</tt>

    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.

<tt>sdltk viewport ?<i>x y</i> ?<i>width

    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 and parameters are given, the viewport is shifted that and are shown in the top-left corner of the screen. When all four parameters are given, the viewport is adjusted accordingly, i.e. and determine the zoom factor, and and 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.

<tt>sdltk touchtranslate

    Controls touchscreen event translation, or reports the current translation state. 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 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 <tt><<PinchToZoom>></tt>. 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 <tt><<FingerUp>></tt>, <tt><<FingerDown>></tt>, and <tt><<FingerMotion>></tt> 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 <tt><ButtonPress></tt> and <tt><ButtonRelease></tt> 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 <tt><<PinchToZoom>></tt> and finger down/up as is enabled. On Windows and Linux platforms only bit 3 (mask 8) to control the viewport is supported.

<tt>sdltk screensaver ?on|off?</tt>

    Turns the screen saver on or off or reports the current state of the screensaver.

<tt>sdltk joystick ids</tt>

    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.

<tt>sdltk joystick name

    Returns the name of the joystick identified by

<tt>sdltk joystick guid

    Returns the globally unique id (GUID, 128 bit string) of the joystick identified by

<tt>sdltk joystick numaxes

    Returns the number of axes of the joystick identified by

<tt>sdltk joystick numballs

    Returns the number of balls of the joystick identified by

<tt>sdltk joystick numbuttons

    Returns the number of buttons of the joystick identified by

<tt>sdltk joystick numhats

    Returns the number of hats of the joystick identified by

<tt>sdltk addfont

    Adds TrueType font(s) contained in and returns the font family names which were added. If the font already has been loaded an error is thrown.

<tt>sdltk hasgl</tt>

    Returns true when OpenGL support is available, e.g. for the 3D canvas widget.

<tt>sdltk log <i>priority

    Outputs the log message using SDL's logging facility. specifies the priority of the log message and must be one of <tt>verbose</tt>, <tt>debug</tt>, <tt>info</tt>, <tt>warn</tt>, <tt>error</tt>, or <tt>fatal</tt> (from lowest to highest).

<tt>sdltk deiconify</tt>

    Deiconifies the SDL root window (not usable on Android and Wayland).

<tt>sdltk fullscreen</tt>

    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 <tt>-sdlresizable</tt>).

<tt>sdltk iconify</tt>

    Iconifies (minimizes) the SDL root window (not usable on Android and Wayland).

<tt>sdltk maximize</tt>

    Maximizes the SDL root window (not usable on Android and Wayland). The SDL root window must be resizable (command line option <tt>-sdlresizable</tt>).

<tt>sdltk restore</tt>

    Restores the last unmaximized geometry of the SDL root window (not usable on Android and Wayland).

<tt>sdltk withdraw</tt>

    Withdraw (hides entirely) the SDL root window (not usable on Android and Wayland).

<tt>sdltk opacity

    Query or set the opacity of the SDL root window. 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.

<tt>sdltk fonts</tt>

    Returns a list made up of font information in the form of three elements XLFD, file name, font index of all registered fonts.


<tt>sdltk vrmode <i>?mode ?distortion

    Experimental VR headset mode currently only supported on the Android platform. If 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 lenses of a VR headset. The optional parameters and if present, must be specified as floating point numbers and control the degree of distortion. If and additional arguments are omitted, the currently active mode including the distortion control parameters are returned as a Tcl list of three elements.

<h2>Touchscreen and Accelerometer Events</h2>

Using the sdltk framework usually requires liberal use of virtual event handlers. The virtual events include:

<tt><<Accelerometer>></tt>

    Event associated with the accelerometer (activated with <tt>sdltk accelerometer on</tt>). <tt>%s</tt> is substituted with the accelerometer axis {1..3} and <tt>%x</tt> with the accelerometer value in the range {-32768...+32767}. This event is reported to toplevel widgets only.

<tt><<FingerDown>></tt>

    A touch event.

<tt><<FingerUp>></tt>

    A touch completion event.

<tt><<FingerMotion>></tt>

    A touch movement (sliding) event. The fields <tt>%x</tt> and <tt>%y</tt> are substituted with the finger position scaled to {0...9999} of the device screen or viewport, <tt>%X</tt> and <tt>%Y</tt> with the motion difference scaled to {0...9999}, <tt>%t</tt> with the pressure scaled to {0...9999}, and <tt>%s</tt> with the finger identifier {1...10}. These substitutions are performed for all finger related touch events.

<tt><<PinchToZoom>></tt>

    A zoom gesture event. <tt>%X</tt> and <tt>%Y</tt> are substituted with the root window coordinate of the center of the two fingers, <tt>%x</tt> with the distance between the two fingers, and <tt>%y</tt> with the angle measured in 64 times degrees CCW starting at 3 o'clock. The finger state is reported in the <tt>%s</tt> 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).

<h2>Joystick Events</h2>

Following virtual events are reported for joysticks and game controllers:

<tt><<JoystickAdded>></tt>, <tt><<JoystickRemoved>></tt>

    Event generated when a joystick or game controller is plugged or unplugged. The field <tt>%X</tt> is substituted with the joystick id (instance identifier in SDL2 terminology).

<tt><<JoystickMotion>></tt>

    Similar to <tt><<Accelerometer>></tt> this event is reported when the position of the joystick has changed. An additional substitution is made for <tt>%X</tt> which receives the joystick id (instance identifier in SDL2 terminology).

<tt><<TrackballMotion>></tt>

    A joystick trackball has moved. The fields <tt>%x</tt> and <tt>%y</tt> are substituted with the deltas of the move, <tt>%s</tt> with the trackball number counted from 1, the field <tt>%X</tt> indicates the joystick id.

<tt><<HatPosition>></tt>

    A joystick hat has changed. The field <tt>%x</tt> is substituted with the value of the hat, <tt>%s</tt> with the hat number counted from 1, the field <tt>%X</tt> indicates the joystick id.

<tt><<JoystickButtonUp>></tt>,

    A joystick button was pressed or released. The field <tt>%s</tt> is substituted with the button number counted from 1, the field <tt>%X</tt> indicates the joystick id.


<h2>Events related to the device screen</h2>

<tt><<ViewportUpdate>></tt>

    This event is sent to toplevel widgets when the viewport has changed. <tt>%x</tt> and <tt>%y</tt> are substituted with the viewport offset (top-left corner of the screen), <tt>%X</tt> and <tt>%Y</tt> with the width and height, respectively, and <tt>%s</tt> with the scale factor (relation of root window size to displayed size) scaled to 10000.

<h2>Events related to the app life-cycle</h2>

Android specific: these events are direct translations from SDL events. They are reported to toplevel widgets only.

<tt><<LowMemory>></tt>

    System is in low memory situation.

<tt><<Terminating>></tt>

    App is terminating.

<tt><<WillEnterBackground>></tt>

    App's screen will be put in background.

<tt><<DidEnterBackground>></tt>

    App's screen is in the background.

<tt><<WillEnterForeground>></tt>

    App's screen will be put in foreground.

<tt><<DidEnterForeground>></tt>

    App's screen is in the foreground.

<h2>Accelerometer Example</h2>

<verbatim>
    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
</verbatim>

<h2>Pinch-to-zoom Example</h2>

<verbatim>
    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}
</verbatim>