Documentation about modifying exteraGram using Python.

You can create a settings screen for your plugin by implementing the create_settings method. This method should return a list of setting control objects, which are Python dataclasses imported from the ui.settings module.

General Example

Here is a general example that demonstrates how to use all available setting controls.

from ui.settings import Header, Input, Divider, Switch, Selector, Text, EditText
from android.view import View
from typing import List, Any
 
class MyPlugin(BasePlugin):
    def _on_test_switch_change(self, new_value: bool):
        self.log(f"Test switch changed to: {new_value}")
 
    def _on_test_input_change(self, new_value: str):
        self.log(f"Test input changed to: {new_value}")
 
    def _on_test_selector_change(self, new_index: int):
        self.log(f"Test selector changed to index: {new_index}")
 
    def _on_text_click(self, view: View):
        self.log("Text item clicked!")
 
    def _create_sub_page(self) -> List[Any]:
        return [
            Header(text="This is a Sub-Page"),
            Text(text="You can nest settings pages.")
        ]
 
    def create_settings(self) -> List[Any]:
        return [
            Header(text="General Settings"),
            Switch(
                key="test_switch_key",
                text="Test Switch",
                default=True,
                subtext="This is a sample switch control.",
                icon="msg_settings",
                on_change=self._on_test_switch_change,
                link_alias="test_switch"
            ),
            Selector(
                key="test_selector_key",
                text="Test Selector",
                default=1,
                items=["Option A", "Option B", "Option C"],
                icon="msg_list",
                on_change=self._on_test_selector_change
            ),
            Divider(),
            Header(text="Advanced Settings"),
            Input(
                key="test_input_key",
                text="Test Input",
                default="Hello, World!",
                subtext="A simple text input field.",
                icon="msg_text",
                on_change=self._on_test_input_change
            ),
            EditText(
                key="multiline_key",
                hint="Enter multiple lines of text here...",
                default="",
                multiline=True,
                max_length=1000
            ),
            Divider(text="This is a divider with text."),
            Text(
                text="Click for Sub-Page",
                icon="msg_arrow_forward",
                on_click=self._on_text_click,
                create_sub_fragment=self._create_sub_page,
                link_alias="sub_page_link"
            ),
            Text(
                text="This is red text",
                icon="msg_error",
                red=True
            )
        ]

Accessing and Modifying Settings

To access settings from your code, use the self.get_setting("KEY", DEFAULT_VALUE) method:

# Get the value of 'test_switch_key', defaulting to False if not set
is_enabled = self.get_setting("test_switch_key", False)

To save or update a setting's value programmatically, use the self.set_setting() method:

# Example: Toggle a boolean setting
current_value = self.get_setting("test_switch_key", False)
self.set_setting("test_switch_key", not current_value)
 
# You can also force the settings page to reload after changing a value.
# This is useful if changing one setting should affect another's visibility or options.
self.set_setting("main_option", "A", reload_settings=True)

The set_setting method will persist the new value. If reload_settings is set to True, the settings UI will be completely rebuilt.

You can also export all settings for a plugin to a dictionary or import them from a dictionary. This can be useful for backup/restore functionality.

# Export all settings for the current plugin to a dictionary
all_my_settings = self.export_settings()
self.log(f"My settings: {all_my_settings}")
 
# Example: Import settings from a dictionary
# This will overwrite existing settings for the plugin
new_settings = {"test_switch_key": False, "test_input_key": "New Value"}
self.import_settings(new_settings)
 
# By default, the settings UI will reload after an import.
# To prevent this, pass `reload_settings=False`
self.import_settings(new_settings, reload_settings=False)

Supported Controls

Here is a summary of the available setting controls and their parameters.

Control	`key`	`text`	`default`	Other Important Parameters
Header	-	Required	-	`text`: The title of the section.
Divider	-	-	-	`text`: (Optional) A note displayed on the divider line.
Switch	Required	Required	Required (`bool`)	`subtext: str`, `icon: str`, `on_change(bool)`, `on_long_click(View)`, `link_alias: str`
Selector	Required	Required	Required (`int` index)	`items: List[str]`, `icon: str`, `on_change(int)`, `on_long_click(View)`, `link_alias: str`
Input	Required	Required	(Optional) `str`	`subtext: str`, `icon: str`, `on_change(str)`, `on_long_click(View)`, `link_alias: str`
Text	-	Required	-	`icon: str`, `accent: bool`, `red: bool`, `on_click(View)`, `create_sub_fragment() -> List`, `on_long_click(View)`, `link_alias: str`
EditText	Required	-	(Optional) `str`	`hint: str`, `multiline: bool`, `max_length: int`, `mask: str` (regex), `on_change(str)`

Parameter Details

Parameter	Type	Description
`key`	`str`	Required for stateful controls. A unique string to identify the setting. This key is used with `get_setting()` and `set_setting()` to manage its value.
`text`	`str`	Required for most controls. The main display text or label for the setting item.
`default`	`Any`	The initial value of the setting if no value has been saved yet. The type depends on the control (`bool` for `Switch`, `int` for `Selector`, `str` for `Input`/`EditText`).
`subtext`	`str`	Optional. Additional text displayed below the main `text` for more context or explanation.
`icon`	`str`	Optional. The name of a drawable resource to use as an icon (e.g., `"msg_settings"`). You can find icon names in the Telegram app's source code.
`on_change`	`Callable`	Optional. A function that is called immediately when the user changes the setting's value. The function receives the new value as an argument (e.g., `Callable[[bool]]` for `Switch`, `Callable[[int]]` for `Selector`).
`on_click`	`Callable`	Optional. A function that is called when the user clicks on the item. It receives the Android `View` object as an argument. Primarily used with the `Text` control.
`on_long_click`	`Callable`	Optional. A function that is called when the user long-presses the setting item. It receives the Android `View` object as an argument.
`link_alias`	`str`	Optional. A unique alias for this setting. If provided, a "Copy Link" option will appear on long-press, allowing users to get a direct deeplink to this specific setting.
`items`	`List[str]`	Required for `Selector`. A list of strings representing the options the user can choose from.
`create_sub_fragment`	`Callable`	Optional. Used with `Text`. A function that returns a new list of setting items. Clicking the `Text` item will navigate to a new sub-page with these settings.
`accent`	`bool`	Optional. Used with `Text`. If `True`, the text is styled with the theme's accent color.
`red`	`bool`	Optional. Used with `Text`. If `True`, the text is styled in red, typically for warnings or destructive actions.
`hint`	`str`	Required for `EditText`. Placeholder text displayed inside the text field when it's empty.
`multiline`	`bool`	Optional. Used with `EditText`. If `True`, allows the text field to have multiple lines.
`max_length`	`int`	Optional. Used with `EditText`. The maximum number of characters allowed in the input.
`mask`	`str`	Optional. Used with `EditText`. A regex pattern to filter input characters (e.g., `"[0-9]"` would only allow digits).

Plugin Settings

General Example

Accessing and Modifying Settings

Supported Controls

Parameter Details

On this page