termuxgui package

Subpackages

Module contents

This is a library for interacting with the Termux:GUI plugin from python.

You don’t need to include all the submodules, all needed classes are automatically included in the package scope upon importing the package.

class termuxgui.Activity(connection: Connection, tid: Optional[str] = None, dialog: Optional[bool] = None, pip: Optional[bool] = False, overlay: Optional[bool] = None, lockscreen: Optional[bool] = None, canceloutside: bool = True, intercept: bool = False)

Bases: object

This represents an Android Activity.

Use a.c to access the Connection object of an Activity and a.t to access the Task object.

finish()

Finishes an Activity.

getconfiguration() → Configuration

Reads the current configuration of this Activity.

hidesoftkeyboard()

Hides the soft keyboard if this Activity has the soft keyboard focus.

interceptbackbutton(intercept: bool)

Sets whether to intercept a back button press and send an event instead.

keepscreenon(on: bool)

Sets whether the Activity should keep the screen on while it is showing.

movetoback()

Moves this Activity’s Task to the recents screen and hides it.

requestunlock()

Requests the lockscreen to unlock. If the lockscreen is just protected by a swipe, it is unlocked immediately. If a PIN, password or pattern has to be used, brings up the UI to let the user unlock the lockscreen.

sendoverlayevents(send: bool)

Sets whether or not you want to receive overlay events if the Activity is an overlay.

setinputmode(mode: Literal['resize', 'pan'])

Sets the input mode for an Activity.

setorientation(orientation: Literal['behind', 'fullSensor', 'fullUser', 'landscape', 'locked', 'nosensor', 'portrait', 'reverseLandscape', 'reversePortrait', 'sensorLandscape', 'sensorPortrait', 'user', 'userLandscape', 'userPortrait'])

Sets the preferred orientation of the Activity.

setpipmode(pip: bool)

Goes into / out of picture-in-picture mode.

When you exit pip, you Activity is put in the recent tasks list and not shown to the user.

setpipmodeauto(pip: bool)

Set whether the Activity should automatically enter picture-in-picture mode when the user leaves the Activity.

setpipparams(num: int, den: int)

Sets the PiP parameters for the Activity, currently only the aspect ration.

setposition(x: int, y: int)

Sets the screen position of the Activity if it is an overlay.

settaskdescription(label: str, img: str)

Sets the Task icon. img has to be a PNG or JPEG image as a base64 encoded string.

settheme(statusbarcolor: int, colorprimary: int, windowbackground: int, textcolor: int, coloraccent: int)

Sets the Theme for the Activity.

class termuxgui.Buffer(connection, w: int, h: int, format: Literal['ARGB888'] = 'ARGB888')

Bases: object

This represents a raw ARGB888 image buffer.

This is only available on Android 8.1+. Buffers consume much memory, so be sure to close any Buffer you don’t need any more. Preferably use “with” to get the memory object of the buffer so it is automatically closed. The memory object is a shared memory object that can be used like a bytes object or a file object. You can also directly access the memory object as b.mem.

A RuntimeError is raised when a Buffer can’t be created.

blit()

Blits the buffer to the underlying image in the plugin. To update ImageViews using this buffer, they have to be refreshed afterwards.

remove()

Removes this buffer, freeing the memory.

class termuxgui.Button(activity: Activity, text: str, parent: Optional[View] = None, allcaps: bool = False, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: TextView

This represents a Button.

class termuxgui.Checkbox(activity: Activity, text: str, parent: Optional[View] = None, checked: bool = False, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: CompoundButton

This represents a CheckBox.

class termuxgui.CompoundButton(activity: Activity, id: int)

Bases: Button

This represents a CompoundButton.

This class doesn’t correspond to a particular View, it is used to provide common methods for all CompoundButtons.

handleevent(e: Event)

Use this to let the CompoundButton track whether it is checked or not. Just pass every Event here.

setchecked(checked: bool)

Explicitly set the checked status of this CompoundButton.

class termuxgui.Connection

Bases: object

This represents a connection to the Termux:GUI plugin and contains all functions that don’t act on any particular View, Activity or Task.

checkevent() → Optional[Event]

If there is at least one event to be read, returns it. If there is no event, returns None. You can use this to e.g. check for events between drawing a frame instead of having to use a separate thread and blocking it.

close()

Closes the connection.

The connection is automatically closed when the program exits, but it’s good practice to close the connection yourself when you don’t need it anymore or use a “with” statement.

events() → Iterator[Event]

Waits for events. Use this with “for in” to iterate over incoming events and block while waiting.

getversion() → bool

Returns the version code of the plugin app. Can be used to disable features only present in a newer version or prompting the user to update.

islocked() → bool

Returns whether the device is locked.

send_msg(msg: Union[str, dict])

Send a message to the main socket. You should only need to call this yourself if you want to use methods not yet implemented in the library.

send_read_msg(msg: Union[str, dict])

Send a message to the main socket and read a message afterwards. You should only need to call this yourself if you want to use methods not yet implemented in the library.

toast(text: str, long: bool = False)

Sends a Toast. Set long to True if you want to display the text for longer.

totermux()

Returns to the termux task. This is a shorthand for running “am start” to start the termux activity.

turnscreenon()

Turns the screen on.

class termuxgui.EditText(activity: Activity, text: str, parent: Optional[View] = None, singleline: bool = False, line: bool = True, blockinput: bool = False, inputtype: Literal['text', 'textMultiLine', 'phone', 'date', 'time', 'datetime', 'number', 'numberDecimal', 'numberPassword', 'numberSigned', 'numberDecimalSigned', 'textEmailAddress', 'textPassword'] = 'text', visibility: Optional[Literal[0, 1, 2]] = None)

Bases: TextView

This represents an EditText.

showcursor(show: bool)

Sets whether the cursor position should be shown.

class termuxgui.Event(ev: dict)

Bases: object

This represents an Event in the GUI.

The class variables are the available event types.

Use ev.type == Event.eventtype to check for event types.

ev.type contains the event type and ev.value is a dictionary containing the values of the event, if any.

airplane = 'airplane'
back = 'back'
click = 'click'
config = 'config'
create = 'create'
destroy = 'destroy'
focusChange = 'focusChange'
itemselected = 'itemselected'
key = 'key'
locale = 'locale'
longClick = 'longClick'
notification = 'notification'
notificationDismissed = 'notificationDismissed'
notificationaction = 'notificationaction'
overlayScale = 'overlayScale'
overlaytouch = 'overlayTouch'
pause = 'pause'
pipchanged = 'pipchanged'
refresh = 'refresh'
remoteclick = 'remoteclick'
resume = 'resume'
screen_off = 'screen_off'
screenon = 'screen_on'
selected = 'selected'
start = 'start'
stop = 'stop'
text = 'text'
timezone = 'timezone'
touch = 'touch'
touch_cancel = 'cancel'
touch_down = 'down'
touch_move = 'move'
touch_pointer_down = 'pointer_down'
touch_pointer_up = 'pointer_up'
touch_up = 'up'
userleavehint = 'UserLeaveHint'
webviewConsoleMessage = 'webviewConsoleMessage'
webviewDestroyed = 'webviewDestroyed'
webviewError = 'webviewError'
webviewHTTPError = 'webviewHTTPError'
webviewNavigation = 'webviewNavigation'
webviewProgress = 'webviewProgress'
class termuxgui.FrameLayout(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: ViewGroup

This represents a FrameLayout.

class termuxgui.GridLayout(activity: Activity, rows: int, cols: int, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: ViewGroup

This represents a GridLayout.

class termuxgui.HorizontalScrollView(activity: Activity, parent: Optional[View] = None, fillviewport: bool = False, snapping: bool = False, nobar: bool = False, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: FrameLayout

This represents a HorizontalScrollView.

getscrollposition() → List[int]

Gets the x and x scroll positions.

setscrollposition(x: int, y: int, smooth: bool = True)

Sets the x and x scroll positions. smooth specifies whether is’s a smooth scoll or not.

class termuxgui.ImageView(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: View

This represents an ImageView.

refresh()

Redraws the ImageView. You have to use this after blitting the Buffer when using a buffer.

setbuffer(b: Buffer)

Makes the ImageView use a shared buffer as the image source.

setimage(img: bytes)

Sets the image of the ImageView. The image has to be a bytes object containing the image in png or jpeg format.

class termuxgui.LinearLayout(activity: Activity, parent: Optional[View] = None, vertical: bool = True, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: ViewGroup

This represents a LinearLayout.

class termuxgui.NestedScrollView(activity: Activity, parent: Optional[View] = None, fillviewport: bool = False, snapping: bool = False, nobar: bool = False, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: FrameLayout

This represents a NestedScrollView.

getscrollposition() → List[int]

Gets the x and x scroll positions.

setscrollposition(x: int, y: int, smooth: bool = True)

Sets the x and x scroll positions. smooth specifies whether it’s a smooth scroll or not.

class termuxgui.Notification(connection: Connection, channel: str, importance: Literal[0, 1, 2, 3, 4])

Bases: object

This represents a notification.

cancel()

Cancels the notification.

createchannel()

Creates the notification channel for the notification. This is called automatically when you call notify.

notify()

Creates/updates the notification.

setactions(actions: List[str])

Sets the displayed actions for the notification.

setalertonce(alertonce: bool)

If you call notify more than once, whether to alert the user every time.

setcontent(content: str)

Sets the content of the notification, removing any set custom layout.

setexpandedlayout(layout: RemoteViews)

Sets a custom expanded layout for the notification. Removes any title, content largetext or largeimage.

sethudlayout(layout: RemoteViews)

Sets a custom hud layout for the notification. Removes any title, content largetext or largeimage.

seticon(icon: bytes)

Set the icon of the notification. icon has to be a bytes object containing the icon in png or jpeg format.

setlargeimage(img: bytes)

Sets a large image for the notification, removing any set custom layout.

setlargeimageasthumbnail(asthumbnail: bool)

Sets whether to show a large image as a thumbnail in the collapsed notification.

setlargetext(text: str)

Sets the text after expanding the notification, removing any set custom layout.

setlayout(layout: RemoteViews)

Sets a custom layout for the notification. Removes any title, content largetext or largeimage.

setongoing(ongoing: bool)

Ongoing notifications can’t be dismissed by the user.

setshowtimestamp(show: bool)

Whether the timestamp is shown in the notification

settimestamp(timestamp: int)

Sets the timestamp of the notification. The format is the unix time in milliseconds.

settitle(title: str)

Sets the title of the notification, removing any set custom layout.

class termuxgui.ProgressBar(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: View

This represents a ProgressBar.

setprogress(progress: int)

Sets the progress of the ProgressBar. The progress has to be an integer from 0 to 100 (inclusive).

class termuxgui.RadioButton(activity: Activity, text: str, parent: Optional[View] = None, checked: bool = False, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: CompoundButton

This represents a RadioButton.

class termuxgui.RadioGroup(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: LinearLayout

This represents a RadioGroup.

Only one RadioButton inside a RadioGroup can be checked at once, and the RadioGroup emits events when the checked button has changed.

class termuxgui.RemoteViews(connection: Connection)

Bases: object

This represents a remote Layout. You can use remote Layouts for custom notifications or widgets.

addButton(parent: Optional[int] = None) → int

Creates a Button in this remote Layout and returns the id, or -1 if it could not be created. The id can be used in further methods to manipulate the View.

addFrameLayout(parent: Optional[int] = None) → int

Creates a FrameLayout in this remote Layout and returns the id, or -1 if it could not be created. The id can be used in further methods to manipulate the View.

addImageView(parent: Optional[int] = None) → int

Creates an ImageView in this remote Layout and returns the id, or -1 if it could not be created. The id can be used in further methods to manipulate the View.

addLinearLayout(parent: Optional[int] = None, vertical: Optional[bool] = None) → int

Creates a LinearLayout in this remote Layout and returns the id, or -1 if it could not be created. The id can be used in further methods to manipulate the View.

addProgressBar(parent: Optional[int] = None) → int

Creates a ProgressBar in this remote Layout and returns the id, or -1 if it could not be created. The id can be used in further methods to manipulate the View.

addTextView(parent: Optional[int] = None) → int

Creates a TextView in this remote Layout and returns the id, or -1 if it could not be created. The id can be used in further methods to manipulate the View.

delete()

Deletes this remote Layout.

setBackgroundColor(id: int, color: int)

Sets the background color of a View in this remote Layout.

setImage(id: int, img: Union[str, bytes])

Sets the image of an ImageView in this remote Layout. The image has to be a bytes object containing the image in png or jpeg format, or a string containing the base64 encoded version of it.

setPadding(id: int, left: int, top: int, right: int, bottom: int)

Sets the padding of a View in this remote Layout.

setProgress(id: int, progress: int, max: int)

Sets the progress and maximum value of a ProgressBar in this remote Layout.

setText(id: int, text: str)

Sets the text of a TextView in this remote Layout.

setTextColor(id: int, color: int)

Sets the text color of a TextView in this remote Layout.

setTextSize(id: int, size: int, px: bool)

Sets the text size of a TextView in this remote Layout. If px is true, the size will be in pixels. If not, it will be in dip.

setVisibility(id: int, vis: Literal[0, 1, 2])

Sets the visibility of a View in this remote Layout.

0 = gone, 1 = hidden, 2 = visible. While hidden, views are not visible but still take up space in the layout. Gone views do not take up layout space.

updateWidget(wid: str)

Sets the content of the Widget with ID wid to this remote Layout.

class termuxgui.Space(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: View

This represents a Space. You can use this to create empty space in your layout.

class termuxgui.Spinner(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: View

This represents a Spinner.

selectitem(item: int)

Sets the selected item of the Spinner.

setlist(list: List[str])

Sets the list of items displayed in the Spinner.

class termuxgui.SwipeRefreshLayout(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: ViewGroup

This represents a SwipeRefreshLayout.

setrefreshing(refreshing: bool)

Sets whether the SwipeRefreshLayout displays the refresh animation.

You have to call this with False when you refreshed the contents.

class termuxgui.Switch(activity: Activity, text: str, parent: Optional[View] = None, checked: bool = False, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: CompoundButton

This represents a Switch.

class termuxgui.TabLayout(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: HorizontalScrollView

This represents a TabLayout.

selecttab(tab: int)

Selects a tab in the TabLayout. tab is the index of the tab to select, starting at 0.

setlist(list: List[str])

Sets the list tabs.

class termuxgui.Task(connection: Connection, tid: int)

Bases: object

This represents an Android Task. It is automatically created with the Activity.

bringtofront()

Bring this Task to the front and make it visible to the user. Might require “overlay over other apps” permission.

finish()

Finishes this Task.

class termuxgui.TextView(activity: Activity, text: str, parent: Optional[View] = None, selectabletext: bool = False, clickablelinks: bool = False, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: View

This represents a TextView.

gettext() → str

Gets the text of this TextView.

sendtextevent(send: bool)

Sets whether ot not text events are send for this TextView.

setgravity(horizontal: Literal[0, 1, 2], vertical: Literal[0, 1, 2])

Sets the text gravity for this TextView. The values are: 0: left/top, 1: center, 2: right/bottom. Right and left are inverted for right-to-left layouts.

settext(text: str)

Sets the text of this TextView.

settextcolor(color: int)

Sets the text color of this TextView. The color format is the same as for Activity.settheme().

settextsize(size: int)

Sets the text size for this TextView.

class termuxgui.ToggleButton(activity: Activity, parent: Optional[View] = None, checked: bool = False, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: CompoundButton

This represents a ToggleButton.

class termuxgui.View(activity: Activity, id: int)

Bases: object

This represents a generic View.

GONE = 0

Visibility constant for hidden views

HIDDEN = 1

Visibility constant for visible views

MATCH_PARENT: str = 'MATCH_PARENT'
VISIBLE = 2

Special size constant to only take up the space needed.

WRAP_CONTENT: str = 'WRAP_CONTENT'

Special size constant to take up the space of the parent View.

delete()

Deletes this View from the layout.

focus(forcesoft: bool = False)

Sets the Focus to this View and opens the soft keyboard if the View has keyboard input.

getdimensions() → List[int]

Gets the width and height of a View in the layout as a list. The values are in pixels.

handleevent(e: Event)

Handles an Event for this View. Subclasses can override this to provide event handling.

sendclickevent(send: bool)

Sets whether ot not click events are sent for this View.

sendfocuschangeevent(send: bool)

Sets whether ot not focus change events are sent for this View.

sendlongclickevent(send: bool)

Sets whether ot not long click events are sent for this View.

sendtouchevent(send: bool)

Sets whether ot not touch events are sent for this View.

setbackgroundcolor(color: int)

Sets the background color for this view.

setclickable(clickable: bool)

Sets whether the View is clickable by the user.

setdimensions(width: Union[int, str], height: Union[int, str], px: bool = False)

Sets the dimensions of this view. width and height are the same as for setwidth and setheight. If px is true, the values are in pixels instead.

setgridlayoutparams(row: int, col: int, rowsize: int = 1, colsize: int = 1, alignmentrow: Literal['top', 'bottom', 'left', 'right', 'center', 'baseline', 'fill'] = 'center', alignmentcol: Literal['top', 'bottom', 'left', 'right', 'center', 'baseline', 'fill'] = 'center')

Sets the GridLayout position for this View. The rows and columns start at 0. rowsize and colsize define how many row/column cells a View takes up. alignmentrow and alignmentcol specify how the View is positioned in its cells,

setheight(height: Union[int, str], px: bool = False)

Sets the height of this View. Can be either an integer describing the value in dp, “MATCH_PARENT” or “WRAP_CONTENT”. If px is true, the values are in pixels instead.

setlinearlayoutparams(weight: int, position: Optional[int] = None)

Sets the LinearLayout weight and/or position for this view.

setmargin(margin: int, dir: Optional[Literal['top', 'bottom', 'left', 'right']] = None)

Sets the margins of this View for one or all directions.

setvisibility(vis: Literal[0, 1, 2])

Sets the visibility for this view.

0 = gone, 1 = hidden, 2 = visible. While hidden, views are not visible but still take up space in the layout. Gone views do not take up layout space.

setwidth(width: Union[int, str], px: bool = False)

Sets the width of this View. Can be either an integer describing the value in dp, “MATCH_PARENT” or “WRAP_CONTENT”. If px is true, the values are in pixels instead.

class termuxgui.ViewGroup(activity: Activity, id: int)

Bases: View

This represents a generic ViewGroup.

clearchildren()

Removes all child Views of this ViewGroup.

class termuxgui.WebView(activity: Activity, parent: Optional[View] = None, visibility: Optional[Literal[0, 1, 2]] = None)

Bases: View

This represents a WebView.

allowcontenturi(allow: bool)

Sets whether it is allowed to load content from a content:// URI.

allowjavascript(allow: bool)

Sets whether Javascript execution is allowed in the WebView. If requesting to allow, the user is prompted and can deny the request. Blocks until the user responded. Returns wheter Javascript is enabled after the call.

allownavigation(allow: bool)

Sets whether the user and Javascript are allowed to navigate to different sites.

evaluatejs(code: str)

Runs Javascript in the WebView, if Javascript is enabled.

goback()

Goes back in the history.

goforward()

Goes forward in the history.

loaduri(uri: str)

Loads a URI.

setdata(data: str)

Sets the document data.