From 7ed5b4dfbea5de00f6fcce039424719a26d770e0 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Mon, 19 Oct 2020 10:48:51 +0200 Subject: [PATCH] Explain what happens when a button is pressed in the docs --- telethon/tl/custom/button.py | 42 ++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/telethon/tl/custom/button.py b/telethon/tl/custom/button.py index 1df7cdfa..134fbec7 100644 --- a/telethon/tl/custom/button.py +++ b/telethon/tl/custom/button.py @@ -20,12 +20,14 @@ class Button: instances instead making them yourself (i.e. don't do ``Button(...)`` but instead use methods line `Button.inline(...) ` etc. - You can use `inline`, `switch_inline` and `url` + You can use `inline`, `switch_inline`, `url` and `auth` together to create inline buttons (under the message). - You can use `text`, `request_location` and `request_phone` + You can use `text`, `request_location`, `request_phone` and `request_poll` together to create a reply markup (replaces the user keyboard). You can also configure the aspect of the reply with these. + The latest message with a reply markup will be the one shown to the user + (messages contain the buttons, not the chat itself). You **cannot** mix the two type of buttons together, and it will error if you try to do so. @@ -63,6 +65,13 @@ class Button: Note that the given `data` must be less or equal to 64 bytes. If more than 64 bytes are passed as data, ``ValueError`` is raised. + If you need to store more than 64 bytes, consider saving the real + data in a database and a reference to that data inside the button. + + When the user clicks this button, `events.CallbackQuery + ` will trigger with the + same data that the button contained, so that you can determine which + button was pressed. """ if not data: data = text.encode('utf-8') @@ -85,6 +94,10 @@ class Button: If ``same_peer is True`` the inline query will directly be set under the currently opened chat. Otherwise, the user will have to select a different dialog to make the query. + + When the user clicks this button, after a chat is selected, their + input field will be filled with the username of your bot followed + by the query text, ready to make inline queries. """ return types.KeyboardButtonSwitchInline(text, query, same_peer) @@ -96,6 +109,11 @@ class Button: If no `url` is given, the `text` will be used as said URL instead. You cannot detect that the user clicked this button directly. + + When the user clicks this button, a confirmation box will be shown + to the user asking whether they want to open the displayed URL unless + the domain is trusted, and once confirmed the URL will open in their + device. """ return types.KeyboardButtonUrl(text, url or text) @@ -133,6 +151,9 @@ class Button: fwd_text (`str`): The new text to show in the button if the message is forwarded. By default, the button text will be the same. + + When the user clicks this button, a confirmation box will be shown + to the user asking whether they want to login to the specified domain. """ return types.InputKeyboardButtonUrlAuth( text=text, @@ -161,6 +182,12 @@ class Button: be "selective". The keyboard will be shown only to specific users. It will target users that are @mentioned in the text of the message or to the sender of the message you reply to. + + When the user clicks this button, a text message with the same text + as the button will be sent, and can be handled with `events.NewMessage + `. You cannot distinguish + between a button press and the user typing and sending exactly the + same text on their own. """ return cls(types.KeyboardButton(text), resize=resize, single_use=single_use, selective=selective) @@ -172,6 +199,10 @@ class Button: Creates a new keyboard button to request the user's location on click. ``resize``, ``single_use`` and ``selective`` are documented in `text`. + + When the user clicks this button, a confirmation box will be shown + to the user asking whether they want to share their location with the + bot, and if confirmed a message with geo media will be sent. """ return cls(types.KeyboardButtonRequestGeoLocation(text), resize=resize, single_use=single_use, selective=selective) @@ -183,6 +214,10 @@ class Button: Creates a new keyboard button to request the user's phone on click. ``resize``, ``single_use`` and ``selective`` are documented in `text`. + + When the user clicks this button, a confirmation box will be shown + to the user asking whether they want to share their phone with the + bot, and if confirmed a message with contact media will be sent. """ return cls(types.KeyboardButtonRequestPhone(text), resize=resize, single_use=single_use, selective=selective) @@ -202,6 +237,9 @@ class Button: the vote, and the pol might be multiple choice. ``resize``, ``single_use`` and ``selective`` are documented in `text`. + + When the user clicks this button, a screen letting the user create a + poll will be shown, and if they do create one, the poll will be sent. """ return cls(types.KeyboardButtonRequestPoll(text, quiz=force_quiz), resize=resize, single_use=single_use, selective=selective)