'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2020 Christian Werner <chw at ch minus werner dot de>
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH sdltk n 3.3 Tk "Tk Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
sdltk \- Exposure of the SDL2 (Simple Direct Media Layer) API.
.SH SYNOPSIS
\fBsdltk\fR \fIoption ?arg ...?\fR
.BE
.SH DESCRIPTION
.PP
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.
.TP
\fBsdltk powerinfo\fR
.
Returns a list of key-value pairs describing the state of the battery.
The keys are \fBstate\fR, \fBseconds\fR, and \fBpercent\fR.
The possible values for the state are \fBonbattery\fR, \fBnobattery\fR,
\fBcharging\fR, \fBcharged\fR, and \fBunknown\fR. The other items are
reported as integer numbers.
.TP
\fBsdltk accelerometer on|off\fR
.
Turns event reporting of the device's accelerometer on or off.
Creates top-level virtual events \fB<<Accelerometer>>\fR when turned on.
This command is not usable on Windows and Linux.
.TP
\fBsdltk accelbuffer\fR \fIaxis\fR
.
Returns the accelerometer values for \fIaxis\fR (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 \fB<<Accelerometer>>\fR virtual event, missed
values with respect to the framerate are interpolated. This command
is not usable on Windows and Linux.
.TP
\fBsdltk textinput\fR \fI?on|off ?x y ?hint???\fR
.
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 \fBentry\fR,
\fBttk::entry\fR, \fBtext\fR, and \fBspinbox\fR 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 \fBSdlTkNoTextInput\fR.
Android specific: the \fIhint\fR 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).
.TP
\fBsdltk android\fR
.
Returns true when running on Android, false otherwise, i.e. when built
for Windows or Linux platforms.
.TP
\fBsdltk framebuffer\fR
.
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 \fBjsmpeg\fR video driver.
.TP
\fBsdltk isandroidtv\fR
.
Returns true when running on an AndroidTV device (currently untested).
.TP
\fBsdltk ischromebook\fR
.
Returns true when running on a Chromebook (currently untested).
.TP
\fBsdltk maxroot\fR
.
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.
.TP
\fBsdltk root\fR \fI?width height?\fR
.
When invoked without \fIwidth\fR and \fIheight\fR parameters the command
returns the current size of the root window as two element list of integers.
When \fIwidth\fR and \fIheight\fR are given, the root window is resized to
the size given. When both \fIwidth\fR and \fIheight\fR are given as zero,
the root window is resized to the device screen size.
.TP
\fBsdltk vsync\fR
.
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.
.TP
\fBsdltk viewport\fR \fI?x y ?width height??\fR
.
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 \fIx\fR and \fIy\fR parameters are given, the viewport
is shifted that \fIx\fR and \fIy\fR are shown in the top-left corner of
the screen. When all four parameters are given, the viewport is adjusted
accordingly, i.e. \fIwidth\fR and \fIheight\fR determine the zoom factor,
and \fIx\fR and \fIy\fR 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.
.TP
\fBsdltk touchtranslate\fR \fI?mask?\fR
.
Controls touchscreen event translation, or reports the current translation
state. \fImask\fR 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 \fB<<PinchToZoom>>\fR. 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 \fB<<FingerUp>>\fR,
\fB<<FingerDown>>\fR, and \fB<<FingerMotion>>\fR 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 \fB<ButtonPress>\fR and \fB<ButtonRelease>\fR 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
\fB<<PinchToZoom>>\fR and finger down/up as
\fB<ButtonPress>\fR/\fB<ButtonRelease>\fR is enabled. On Windows and Linux
platforms only bit 3 (mask 8) to control the viewport is supported.
.TP
\fBsdltk screensaver\fB \fI?on|off?\fR
.
Turns the screen saver on or off or reports the current state of the
screensaver.
.TP
\fBsdltk joystick ids\fR
.
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.
.TP
\fBsdltk joystick name\fR \fIid\fR
.
Returns the name of the joystick identified by \fIid\fR.
.TP
\fBsdltk joystick guid\fR \fIid\fR
.
Returns the globally unique id (GUID, 128 bit string) of the joystick
identified by \fIid\fR.
.TP
\fBsdltk joystick numaxes\fR \fIid\fR
.
Returns the number of axes of the joystick identified by \fIid\fR.
.TP
\fBsdltk joystick numballs\fR \fIid\fR
.
Returns the number of balls of the joystick identified by \fIid\fR.
.TP
\fBsdltk joystick numbuttons\fR \fIid\fR
.
Returns the number of buttons of the joystick identified by \fIid\fR.
.TP
\fBsdltk joystick numhats\fR \fIid\fR
.
Returns the number of hats of the joystick identified by \fIid\fR.
.TP
\fBsdltk addfont\fB \fIfilename\fR
.
Adds TrueType font(s) contained in \fIfilename\fR and returns the
font family names which were added. If the font already has been
loaded an error is thrown.
.TP
\fBsdltk hasgl\fR
.
Returns true when OpenGL support is available, e.g. for the 3D canvas widget.
.TP
\fBsdltk log\fR \fIpriority message\fR
.
Outputs the log message \fImessage\fR using SDL's logging facility.
\fIpriority\fR specifies the priority of the log message and must be
one of \fBverbose\fR, \fBdebug\fR, \fBinfo\fR, \fBwarn\fR, \fBerror\fR,
or \fBfatal\fR (from lowest to highest).
.TP
\fBsdltk deiconify\fR
.
Deiconifies the SDL root window (not usable on Android and Wayland).
.TP
\fBsdltk fullscreen\fR
.
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 \fB\-sdlresizable\fR).
.TP
\fBsdltk iconify\fR
.
Iconifies (minimizes) the SDL root window (not usable on Android and Wayland).
.TP
\fBsdltk maximize\fR
.
Maximizes the SDL root window (not usable on Android and Wayland).
The SDL root window must be resizable (command line option
\fB\-sdlresizable\fR).
.TP
\fBsdltk restore\fR
.
Restores the last unmaximized geometry of the SDL root window
(not usable on Android and Wayland).
.TP
\fBsdltk withdraw\fR
.
Withdraw (hides entirely) the SDL root window
(not usable on Android and Wayland).
.TP
\fBsdltk opacity\fR \fIvalue\fR
.
Query or set the opacity of the SDL root window. \fIvalue\fR 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.
.TP
\fBsdltk fonts\fR
.
Returns a list made up of font information in the form of three
elements XLFD, file name, font index of all registered fonts.
.TP
\fBsdltk vrmode\fR \fI?mode ?distortion rescale??\fR
.
Experimental VR headset mode currently only supported on the Android
platform. If \fImode\fR 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 \fIdistortion\fR and \fIrescale\fR, 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,
\fImode\fR can be bitwise or'ed with 4 (horizontal flip) and/or 8
(vertical flip) for all modes except 0. If \fImode\fR and additional
arguments are omitted, the currently active mode including the distortion
control parameters are returned as a Tcl list of three elements.
.TP
\fBsdltk pointer\fR \fI?flag?\fR
.
Queries or sets the state of the mouse pointer shape. If present,
\fIflag\fR must be a boolean value and specifies the new state.
If not present, the current state is returned as 0 (off) or 1 (on).
.TP
\fBsdltk touchcalibration\fR \fI?xmin xmax ymin ymax swapxy?\fR
.
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.
.TP
\fBsdltk size\fR \fI?width height?\fR
.
Queries the size of the enclosing SDL root window when \fIwidth\fR
and \fIheight\fR 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 \fB\-sdlresizeable\fR was specified and
the command line parameter \fB\-sdlfullscreen\fR was not specified on
startup. However, changing the SDL root window size is not supported
on framebuffer like devices (see \fBsdltk framebuffer\fR).  
.SH "TOUCHSCREEN AND ACCELEROMETER EVENTS"
.PP
Using the sdltk framework usually requires liberal use of virtual
event handlers. The virtual events include:
.TP
\fB<<Accelerometer>>\fR
Event associated with the accelerometer (activated with
\fBsdltk accelerometer on\fR). \fI%s\fR is substituted with the
accelerometer axis {1..3} and \fI%x\fR with the accelerometer value
in the range {-32768...+32767}. This event is reported to
toplevel widgets only.
.TP
\fB<<FingerDown>>\fR
.
A touch event.
.TP
\fB<<FingerUp>>\fR
.
A touch completion event.
.TP
\fB<<FingerMotion>>\fR
.
A touch movement (sliding) event. The fields \fI%x\fR and \fI%y\fR are
substituted with the finger position scaled to {0...9999} of the device
screen or viewport, \fI%X\fR and \fI%Y\fR with the motion difference
scaled to {-9999...+9999}, \fI%t\fR with the pressure scaled to {0...9999},
and \fI%s\fR with the finger identifier {1...10}. These substitutions
are performed for all finger related touch events.
.TP
\fB<<PinchToZoom>>\fR
.
A zoom gesture event. \fI%X\fR and \fI%Y\fR are substituted with the
root window coordinate of the center of the two fingers, \fI%x\fR with
the distance between the two fingers, and \fI%y\fR with the angle
measured in 64 times degrees CCW starting at 3 o'clock. The finger
state is reported in the \fI%s\fR 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).
.SH "JOYSTICK EVENTS"
.PP
Following virtual events are reported for joysticks and game controllers:
.TP
\fB<<JoystickAdded>>\fR, \fB<<JoystickRemoved>>\fR
.
Event generated when a joystick or game controller is plugged or
unplugged. The field \fI%X\fR is substituted with the joystick id
(instance identifier in SDL2 terminology).
.TP
\fB<<JoystickMotion>>\fR
.
Similar to \fB<<Accelerometer>>\fR this event is reported when the
position of the joystick has changed. An additional substitution is
made for \fI%X\fR which receives the joystick id (instance identifier
in SDL2 terminology).
.TP
\fB<<TrackballMotion>>\fR
.
A joystick trackball has moved. The fields \fI%x\fR and \fI%y\fR are
substituted with the deltas of the move, \fI%s\fR with the trackball
number counted from 1, the field \fI%X\fR indicates the joystick id.
.TP
\fB<<HatPosition>>\fR
.
A joystick hat has changed. The field \fI%x\fR is substituted with
the value of the hat, \fI%s\fR with the hat number counted from 1,
the field \fI%X\fR indicates the joystick id.
.TP
\fB<<JoystickButtonUp>>\fR, \fB<<JoystickButtonDown>>\fR
.
A joystick button was pressed or released. The field \fI%s\fR is
substituted with the button number counted from 1, the field
\fI%X\fR indicates the joystick id.
.SH "EVENTS RELATED TO THE DEVICE SCREEN"
.TP
\fB<<ViewportUpdate>>\fR
.
This event is sent to toplevel widgets when the viewport has changed.
\fI%x\fR and \fI%y\fR are substituted with the viewport offset
(top-left corner of the screen), \fI%X\fR and \fI%Y\fR with the width
and height, respectively, and \fI%s\fR with the scale factor (relation
of root window size to displayed size) scaled to 10000.
.SH "EVENTS RELATED TO THE APP LIFE-CYCLE"
.PP
These events are direct translations from SDL events (\fBSDL_APP_*\fR
in SDL header files) and depend on platform support. They are reported
to toplevel widgets only.
.TP
\fB<<LowMemory>>\fR
.
System is in low memory situation. Although implemented for Android
and iOS, this event was never observed in reality.
.TP
\fB<<Terminating>>\fR
.
App is terminating. Although implemented for Android and iOS,
this event was never observed in reality, maybe due to timing
regarding threads.
.TP
\fB<<WillEnterBackground>>\fR
.
App's screen will be put in background.
.TP
\fB<<DidEnterBackground>>\fR
.
App's screen is in the background.
.TP
\fB<<WillEnterForeground>>\fR
.
App's screen will be put in foreground. On Android, not reported
on startup of the app.
.TP
\fB<<DidEnterForeground>>\fR
.
App's screen is in the foreground. On Android, not reported on
startup of the app.
.PP
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 \fB<<WillEnterBackground>>\fR virtual event since it
may be received before unexpected app termination.
.SH "ACCELEROMETER EXAMPLE"
.sp 1
.nf
\fC
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
\fR
.fi
.SH "PINCH-TO-ZOOM EXAMPLE"
.sp 1
.nf
\fC
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}
\fR
.fi
.SH "SEE ALSO"
tk(n), winfo(n), wm(n)
.SH KEYWORDS
windowing system
'\" Local Variables:
'\" mode: nroff
'\" End: