sdltk command
Not logged in

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.

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 an 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 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 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?

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 four modes. 0 for normal operation, 1 the root window is duplicated along its horizontal axis and scaled down, 2 the root window must be managed as left and right halves by the application, 3 the root window is duplicated along its horizontal axis without down scaling. For all modes except 0 touch screen panning and zooming on Android is turned off. If mode is omitted, the currently active mode is returned.

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 {0...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

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

<<LowMemory>>

System is in low memory situation.

<<Terminating>>

App is terminating.

<<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.

<<DidEnterForeground>>

App's screen is in the foreground.

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}