Documentation about modifying exteraGram using Python.

Helpers for UI-thread work, Android listeners, logging, clipboard access, and Java Runnable wrappers.

This module provides small but very frequently used helpers for Android-side work inside plugins.

Most of the time you will use it for three things:

running code on the UI thread
attaching simple click listeners
logging and quick debugging

Wrappers for Java Interfaces

These wrappers let you pass Python callables into Android APIs that expect Java listener objects.

R (Runnable Proxy)

R(fn) creates a real Java Runnable backed by your Python callable.

This is useful when some Android or Telegram API expects a java.lang.Runnable instance, for example view.post(...), delayed callbacks, or various internal helper methods.

from android_utils import R, log
 
 
def my_task():
    log("Runnable task executed.")
 
 
# Create a Java Runnable instance backed by Python.
runnable_instance = R(my_task)
 
# Example usage with an API that expects Runnable.
some_view = ...
some_view.post(runnable_instance)

`run_on_ui_thread` already wraps your callable

run_on_ui_thread(...) accepts a normal Python callable and internally converts it to a Java Runnable for you. Use R(...) when some other API explicitly requires a Runnable object.

OnClickListener

OnClickListener(fn) is a convenience wrapper for android.view.View.OnClickListener.

from android_utils import OnClickListener, log
from android.view import View
 
 
def handle_button_click(view: View):
    log(f"Button {view.getId()} was clicked.")
 
 
button = ...
button.setOnClickListener(OnClickListener(handle_button_click))

Your callable receives the clicked View as its only argument.

OnLongClickListener

OnLongClickListener(fn) is a convenience wrapper for android.view.View.OnLongClickListener.

from android_utils import OnLongClickListener, log
from android.view import View
 
 
def handle_button_long_click(view: View):
    log(f"Button {view.getId()} was long-clicked.")
    return True
 
 
button = ...
button.setOnLongClickListener(OnLongClickListener(handle_button_long_click))
 
# Or with a lambda:
button.setOnLongClickListener(OnLongClickListener(lambda v: (log("Long click!"), True)[1]))

The wrapped Python callable is expected to return a boolean:

True: consume the long-click event
False: let Android continue processing it

Utility Functions

run_on_ui_thread

run_on_ui_thread(func, delay=0) schedules a Python callable on the Android UI thread.

Any UI mutation should happen there: changing text, updating views, showing dialogs, attaching adapters, and so on.

from android_utils import run_on_ui_thread
 
 
def update_ui_content():
    text_view = ...
    text_view.setText("Updated from Python on UI thread")
 
 
# Run immediately (or as soon as possible) on the UI thread.
run_on_ui_thread(update_ui_content)
 
# Run with a delay of 500 milliseconds.
run_on_ui_thread(update_ui_content, 500)

Parameters:

func: Python callable to execute
delay: optional delay in milliseconds

log

log(data) sends data into the app's logging pipeline.

It behaves slightly differently depending on the value you pass:

simple values such as str, int, float, bool, and None are logged as text
complex objects are passed to the Java-side object inspector, which is useful for debugging Telegram and Android objects

from android_utils import log
 
 
# Log simple messages.
log("This is a simple log message.")
log(f"Current account: {2}")
log(True)
 
# Log objects.
log(user_object)
log(some_list)
 
# Error handling example.
try:
    x = 1 / 0
except Exception as e:
    log(f"An error occurred: {e}")
    import traceback
    log(traceback.format_exc())

copy_to_clipboard

copy_to_clipboard(text) copies a string to the Android clipboard and, if the operation succeeds, shows the standard "copied" bulletin.

from android_utils import copy_to_clipboard
 
 
copy_to_clipboard("https://t.me/exteraPlugins")

This is handy for deeplinks, debug info, exported IDs, or user-facing share actions.

Android Utilities