UI: menus, commands, windows

Toasts

freshgram.ui.toast("Done")
freshgram.ui.toast("Deleted", action="undo-1", undo=True, duration=5)

@freshgram.on_toast("undo-1")
def undo(event):
    ...

Permission: ui.toast. duration is in seconds, 1–8 (5 by default). At most one toast per 2 seconds; text up to 200 bytes. title adds a first line of up to 64 bytes. on_toast_close tells how it ended: reason is "action" or "timeout". undo=True without an action fails with Invalid (“undo needs an action”); Unavailable (“toast actions”) means the app cannot show toast buttons.

Commands

Declared in contributes.commands, need the ui.command permission, handled with @freshgram.on_command("name").

Menus

Items are declared in contributes.menus (surface, id, title, icon, when) and handled with:

@freshgram.on_menu("copy-link", surface="message")
def copy_link(event):
    ...

Needs the ui.menu permission and, for a specific surface, the menu.<surface> feature (for example menu.message).

Settings page

Permission ui.settings_page; the plugin’s settings page is switched on in the manifest. The host asks for the page with a settings.open event:

@freshgram.on_settings_open
def open_page(event):
    freshgram.ui.settings_page("My plugin", [
        {"type": "header", "text": "General"},
        {"type": "toggle", "id": "enabled", "label": "Enabled"},
    ])

@freshgram.on_setting("enabled")
def changed(event):
    ...

Item types: text, header, divider, link, toggle, button, input, select, slider, chat, progress, page, row, column, card, tabs, image, list, table, code. All of them work on the settings page, in dialogs and in windows. Every field is in the UI schema. You can open your own page from a click with freshgram.ui.open_settings().

Dialogs and windows

Permission ui.dialog.

freshgram.ui.dialog("Title", items, buttons=[{"id": "ok", "label": "OK", "style": "primary"}])
freshgram.ui.window("w1", "Window", items, mode="layer")   # or "window"
freshgram.ui.update_window("w1", "Window", new_items)
freshgram.ui.close_window("w1")

A plugin can have at most 3 windows open. Items can be nested: row, column, card, tabs, plus image, list, table, code. Events: dialog.* (on_dialog), window.* (on_window). Long presses are handled by on_long_click for items with long_click: true.

Badges

Permission ui.badges:

freshgram.badges.set(user_id, [{"id": "vip", "icon": "star", "tooltip": "VIP"}])

Up to 4 icons per user; image is PNG/JPEG a PNG is limited to 128×128 (see the UI schema). A click arrives in @freshgram.on_badge_click. A bad list is Invalid with a message such as “a badge needs a unique id of up to 32 characters” or “a badge image is up to 64 KiB”; the full list is in the UI schema. Windows can fail with Unavailable (“windows”) when the app cannot show them.

Other

• freshgram.notify.show(text, title="") — system notification (permission notifications), at most one per 5 seconds.
• freshgram.clipboard — clipboard (permission clipboard), only within 10 seconds after a user action.
• freshgram.files.pick/save — file chosen by the user (fs.user_selected), only through aio.
• freshgram.fs — the folder chosen by the user (fs.folder), only through aio.
• freshgram.composer — the draft (composer.draft).