This page is intended as a place to document the capabilities of the custom commands offered by the [AndroWish], the Tcl/Tk port to Android (excellent work, [chw]!). In the true Wiki spirit '''you''' are invited to extend this documentation. (You may have, already ([chw] definitely has): this information was harvested from the [AndroWish] page!) There are three Android-specific commands: 1. `borg` - control and interact with the Android OS. 1. `rfcomm` - transfer data over a Bluetooth serial port profile; akin to the TCL `socket` command. 1. `sdltk` - exposure of the SDL2 (Simple DirectMedia Layer) Android-related API. Documentation is provided in the order specified. ---- *** Name *** `borg` - control and interact with the Android OS. *** Synopsis *** borg cmd ?arg ...? *** Description *** This command integrates the capabilities of Tcl/Tk with an Android OS by way of several subcommands. These allow Tcl/Tk to go where it has never gone before by querying and controlling Bluetooth functionality, OS notifications (including device vibration and even speach), location information, etc. **** Bluetooth-Related Commands **** `borg bluetooth devices`: Returns a list suited for the "array set" command containing the Bluetooth address and friendly name of all paired Bluetooth devices. `borg bluetooth state`: Returns the current Bluetooth state: `on` or `off`. `borg bluetooth scanmode`: Returns the current Bluetooth scan mode (`off`, `passive`, `visible`, `connectable`, or `on`). `borg bluetooth myaddress`: Returns the Bluetooth address of the local default Bluetooth adapter. `borg remoteaddress address`: Returns the friendly name for the given Bluetooth address. **** Network-Related Commands **** `borg networkinfo`: Returns the current state of the network: `none`, `wifi`, `mobile gsm`, etc. **** Destkop-Related Commands **** `borg shortcut add name-of-shortcut script-to-run ?png-icon-as-base-64-string?`: Adds an icon to the desktop, with the `name-of-shortcut` specified. The script, specified as `script-to-run` must use an absolute path must be readable by the user id under which the AndroWish package has been registered by the Android installer. The last (optional) parameter `png-icon-as-base-64-string` allows the icon graphic to be specified. If not provided, the AndroWish icon (Alladin's lamp) is used. `borg shortcut delete name-of-shortcut`: Deletes an icon from desktop (depends on Android launcher support). **** Notification-Related Commands **** `borg notification add id title text`: Adds a notification with `title` and `text` into the Android notification area. The integer id, specified by the caller, is used to identify the notification on deletion. `borg notification delete ?id?`: Deletes a notification identified that was created with the `id` specified. If no `id` is provided, all notifications are deleted. `borg vibrate ms`: Turns on the vibration motor for integer `ms` milliseconds. `borg beep`: Plays the notification sound. `borg speak text`: Gets the Android to read out the string `text`. **** Location-Related Commands **** `borg location start ?minrate-in-ms? ?min-dist-in-m?`: Begins acquiring location data via the Android OS (which may choose to use GPS, network info, etc.). `borg location stop`: Ends location data acquisition. `borg location get`: Returns the location data (an an `array set` form) where the key is the location source. Location updates trigger a virtual event `<>` (currently untested) which is sent to all toplevel widgets. These toplevel event-handlers should, in turn, invoke `borg location get` to refresh their knowledge. **** General **** `borg activity action uri type ?categories? ?arguments? ?callback?`: This a very flexible command that allows extensive access to the Android OS and other applications. `categories` and `arguments` are optional lists. `callback` is the name of the procedure that is evaluated when the activity `action` is complete. `arguments` are key-value pairs where the values are mapped to Java strings by default. If the key is a 2-element list made up of a data type indicator (int, byte, short, char, long, float, double, Uri) followed by the key, the value is converted to that data type. See below for some examples of this command. (?? categories argument ??) *** `borg activity` Examples *** Sample code to open a browser on this wiki: ====== borg activity android.intent.action.VIEW http://wiki.tcl.tk ====== Sample code to capture an image (only makes thumbnails - there are resizing problems): ====== proc callback {retcode action uri mimetype categories data} { if {$retcode == -1} { # SUCCESS array set result $data if {[info exists result(data)]} { myphoto configure -data $result(data) } } } package require Img image create photo myphoto borg activity android.media.action.IMAGE_CAPTURE {} {} {} {} callback ====== Sample code to capture an image, which works better but requires a file on external storage: ====== proc callback {filename retcode action uri mimetype categories data} { if {$retcode == -1} { # SUCCESS myphoto configure -file $filename catch {file delete -force $filename} } } package require Img image create photo myphoto set filename [file join $env(EXTERNAL_FILES) myphoto.jpeg] borg activity android.media.action.IMAGE_CAPTURE {} {} {} \ [list {Uri output} file://$filename] [list callback $filename] ====== Reading barcodes using the http://code.google.com/p/zxing barcode scanner (which needs to be be installed on your device): ====== proc barcode_read {code action uri type cat data} { array set result $data if {[info exists result(SCAN_RESULT)]} { # that is the barcode # result(SCAN_RESULT_FORMAT) is the barcode format } } borg activity com.google.zxing.client.android.SCAN {} {} {} {} barcode_read ====== ---- *** Name *** `rfcomm` - transfer data over a Bluetooth serial port profile; akin to the TCL `socket` command. *** Synopsis *** This command is used to transfer data over Bluetooth's serial port profile (SPP or SP). The arguments used are nearly identical to the TCL `socket`command. It returns a client or server channel handle that may be used with `gets`, `read`, `puts`, and `close`. For client channels, the remote address must be given as a one- or two-element list: the first element is the Bluetooth address, and the (optional) second element is the UUID of the remote service. For server channels, the first element is the UUID, and the optional second element is the friendly name of the service. Server mode functionality has not yet been verified. *** Description *** ---- *** Name *** '''(More info required here - written by a novice!)''' `sdltk` - exposure of the SDL2 (Simple DirectMedia Layer) Android-related API. *** Synopsis *** This command is used to control portions of the Android system that the SDL2 framework exposes. Actual data processing for this framework is achieved by having handlers for virtual events. *** Description *** `sdltk powerinfo`: Returns a list of key-value pairs describing the state of the battery. `sdltk accelerometer on|off`: Turns the device accelerometer on and off. Creates a top-level virtual event <>. `sdltk textinput ?on|off ?x y??`: 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 pan the application's screen in order to display the insertion cursor when the virtual keyboard is active. *** Events *** Using the sdltk framework usually requires liberal use of virtual event handlers. The virtual events include: `<>`: Event associated with the accelerometer (activated with `sdltk accelerometer on`). `%s` is the accelerometer axis and `%x` is the accelerometer value. `<>`: A touch event. `<>`: A touch completion event. `<>`: A touch movement (sliding) event. The fields `%x` and `%y` are substituted with the finger position scaled to {0...9999}, `%X` and `%Y` with the 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. *** Events related to the APP life cycle *** These events are direct translations from SDL events. They are reported to toplevel widgets only. `<>`: System is in low memory situation `<>`: APP is terminating `<>`: APP's screen will be put in background `<>`: APP's screen is in the background `<>`: APP's screen will be put in foreground `<>`: APP's screen is in the foreground *** Other events *** These events are generated for/by certain `borg` related commands. They are reported to toplevel widgets only. `<>`: Location information has been updated and can be read out using `borg location get`. `<>`: Network state has changed and can be read out using `borg networkinfo`. `<>`: Bluetooth state has changed and can be read out using `borg bluetooth state`. ---- '''Revision History''' | 26/01/2014 | [LWS] - creation from [AndroWish] entries - with lots left out, possible misinterpretation, etc. A momentary editing collision with [chw]: sorry! | | 02/02/2014 | [LWS] - updated `borg shortcut add` with info from [AndroWish Feature Requests] and modified a portion of the barcode reading example | | 03/02/2014 | [chw] - updated `sdltk` command description, added more event descriptions | <>Android