QuasarApp/qTbot
4
1
Fork 0
mirror of https://github.com/QuasarApp/qTbot.git synced 2025-05-13 13:49:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix docs

Browse Source
This commit is contained in:
Andrei Yankovich 2023-10-08 13:50:47 +02:00
parent bcad34ef98
commit ef558b5543
1 changed files with 87 additions and 174 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
src/qTbot/src/public/qTbot/itelegrambot.h
View File

@ -37,43 +37,24 @@ public:
bool sendMessage(const QVariant &chatId, const QString& text) override; bool sendMessage(const QVariant &chatId, const QString& text) override;
/** /**
* @brief Send a message to a chat or channel with optional additional objects. * @brief Sends a specific message to a chat.
* *
* The `sendSpecificMessage` method is used to send a message to a chat or channel. This method allows * This function sends a specific message to a chat. You can include text and additional objects as needed to customize the message's content and behavior.
* sending text messages to chats and channels. You can also specify additional
* parameters such as text formatting, replying to a specific message, disabling
* web page preview, and including extra JSON objects in the message.
* *
* @param chatId The identifier of the chat or channel to which the message will be sent. * @param chatId The unique identifier of the chat to send the message to.
* It can be a string, number, or another valid data type containing the chat identifier. * @param text The text content of the message to be sent.
* @param text The text of the message to be sent. * @param extraObjects A map containing additional objects associated with the message (optional).
* @param extraObjects A map containing additional JSON objects to include in the message. * @param callBackQueryId The unique identifier for callback queries triggered by the message (optional).
* @param callBackQueryId A unique identifier for this message (can be used to identify responses). * @param replyToMessageId The unique identifier of the message to reply to, if any (optional).
* @param replyToMessageId The identifier of the message to which you want to reply. If you want to send * @param markdown Set to true to enable Markdown formatting for the text (optional).
* a regular message without replying to another message, leave this field as 0. * @param disableWebPagePreview Set to true to disable web page previews for links in the message (optional).
* @param markdown A flag indicating whether the message text should be formatted using Markdown.
* If `true`, the text will be formatted using Markdown syntax. If `false`, the text will be
* sent as plain text.
* @param disableWebPagePreview A flag indicating whether to disable web page preview in the message.
* If `true`, web page preview will be disabled.
* *
* @return `true` if the message was successfully sent, and `false` otherwise. * @return Returns true if the message was sent successfully, false otherwise.
* *
* Usage examples: * @note The extraObjects parameter is a map where each key represents the object's name, and the associated value is a shared pointer to a JSON object (optional).
* @code * @note The callBackQueryId parameter is used to handle callback queries when applicable (optional).
* // Send a plain text message * @note By default, the message will be sent with Markdown formatting enabled (optional).
* bool result = sendSpecificMessage(chatId, "Hello, world!"); * @note By default, web page previews for links in the message are not disabled (optional).
*
* // Send a formatted text message as a reply to another message with additional JSON objects
* QMap<QString, QJsonObject> additionalObjects = {
* {"key1", {"value1"}},
* {"key2", {"value2"}}
* };
* bool result = sendSpecificMessage(chatId, "This is a reply with additional objects.", additionalObjects, "123456789", messageId);
*
* // Send a message with disabled web page preview
* bool result = sendSpecificMessage(chatId, "Check)", {}, "987654321", 0, false, true);
* @endcode
*/ */
bool sendSpecificMessage(const QVariant &chatId, bool sendSpecificMessage(const QVariant &chatId,
const QString& text, const QString& text,
@ -84,45 +65,24 @@ public:
bool disableWebPagePreview = false); bool disableWebPagePreview = false);
/** /**
* @brief Send a message to a chat or channel with an optional custom **inline keyboard**. * @brief Sends a specific message with a custom keyboard to a chat.
* *
* The `sendSpecificMessageWithKeyboard` method is used to send a message to a chat or channel. This method allows * This function sends a specific message to a chat with a custom keyboard. The message can contain text and additional settings to customize its behavior.
* sending text messages with optional interactive **inline keyboards** to chats and channels. You can also specify
* additional parameters such as text formatting, replying to a specific message, disabling web page preview,
* and providing a custom inline keyboard for user interaction.
* *
* @param chatId The identifier of the chat or channel to which the message will be sent. It can be a string, * @param chatId The unique identifier of the chat to send the message to.
* number, or another valid data type containing the chat identifier. * @param text The text content of the message to be sent.
* @param text The text of the message to be sent. * @param keyboard A list of maps where each map represents a button with a callback function.
* @param keyboard A list of maps, each containing buttons and corresponding callback functions for a custom inline keyboard. * @param callBackQueryId The unique identifier for callback queries triggered by the message (optional).
* Each map should have button text as the key and a callback function as the value. * @param replyToMessageId The unique identifier of the message to reply to, if any (optional).
* @param callBackQueryId A unique identifier for this message (can be used to identify responses). * @param markdown Set to true to enable Markdown formatting for the text (optional).
* @param replyToMessageId The identifier of the message to which you want to reply. If you want to send a regular message * @param disableWebPagePreview Set to true to disable web page previews for links in the message (optional).
* without replying to another message, leave this field as 0. Default is 0.
* @param markdown A flag indicating whether the message text should be formatted using Markdown syntax. If `true`, the text
* will be formatted using Markdown. If `false`, the text will be sent as plain text. Default is `true`.
* @param disableWebPagePreview A flag indicating whether to disable web page preview in the message. If `true`, web page
* preview will be disabled. Default is `false`.
* *
* @return `true` if the message was successfully sent, and `false` otherwise. * @return Returns true if the message was sent successfully, false otherwise.
* *
* Usage examples: * @note The keyboard parameter should be a list of maps where each map represents a button. The button's label is the map key, and the associated callback function is the map value.
* @code * @note The callBackQueryId parameter is used to handle callback queries when buttons are pressed (optional).
* // Send a plain text message * @note By default, the message will be sent with Markdown formatting enabled (optional).
* bool result = sendSpecificMessageWithKeyboard(chatId, "Hello, world!", {}, "123456789"); * @note By default, web page previews for links in the message are not disabled (optional).
*
* // Send a formatted text message as a reply to another message with a custom inline keyboard
* QList<QMap<QString, std::function<void(const QString &queryID)>>> customKeyboard = {
* {
* {"Button 1", [](const QString &queryID) { "Callback function for Button 1" }},
* {"Button 2", [](const QString &queryID) { "Callback function for Button 2" }}
* }
* };
* bool result = sendSpecificMessageWithKeyboard(chatId, "This is a reply with a custom inline keyboard.", customKeyboard, "987654321", messageId);
*
* // Send a message with disabled web page preview
* bool result = sendSpecificMessageWithKeyboard(chatId, "Check)", {}, "555555555", 0, false, true);
* @endcode
*/ */
bool sendSpecificMessageWithKeyboard(const QVariant &chatId, bool sendSpecificMessageWithKeyboard(const QVariant &chatId,
const QString& text, const QString& text,
@ -133,43 +93,26 @@ public:
bool disableWebPagePreview = false); bool disableWebPagePreview = false);
/** /**
* @brief Send a specific message with a custom keyboard to a chat. * @brief Sends a specific message with a custom keyboard to a chat.
* *
* This method sends a specific message with a custom keyboard to a chat, allowing * This function sends a specific message to a chat with a custom keyboard. The message can contain text and additional settings to customize its behavior.
* you to customize various aspects of the message, such as the text, keyboard layout,
* and other options.
* *
* @param chatId The identifier of the chat to which the message will be sent. * @param chatId The unique identifier of the chat to send the message to.
* @param text The text of the message to be sent. * @param text The text content of the message to be sent.
* @param keyboard A list of text buttons to display in the custom keyboard. * @param keyboard A list of lists containing the keyboard buttons to display.
* @param callBackQueryId A unique identifier for this message (can be used to identify responses). * @param callBackQueryId The unique identifier for callback queries triggered by the message.
* @param onTimeKeyboard A flag indicating whether the keyboard should be hidden after * @param onTimeKeyboard Set to true to display the keyboard only once.
* selecting one of the buttons (one-time keyboard). * @param autoResizeKeyboard Set to true to automatically resize the keyboard.
* @param autoResizeKeyboard A flag indicating whether the keyboard should automatically * @param replyToMessageId The unique identifier of the message to reply to, if any.
* adjust its size based on the number of buttons. * @param markdown Set to true to enable Markdown formatting for the text.
* @param replyToMessageId The identifier of the message to which this message is a reply * @param disableWebPagePreview Set to true to disable web page previews for links in the message.
* (if applicable).
* @param markdown A flag indicating whether Markdown formatting is supported in the message text.
* @param disableWebPagePreview A flag indicating whether to disable web page preview in the message.
* *
* @return Returns true if the message was successfully sent, and false in case of an error. * @return Returns true if the message was sent successfully, false otherwise.
* *
* @example * @note The keyboard parameter should be a list of lists of strings representing keyboard buttons.
* @code * @note The callBackQueryId parameter is used to handle callback queries when buttons are pressed.
* bool result = sendSpecificMessageWithKeyboard(chatId, "Hello, how are you?", {"Button 1", "Button 2"}, "123456789", true, true, 0, true, false); * @note By default, the message will be sent with Markdown formatting enabled.
* if (result) { * @note By default, web page previews for links in the message are not disabled.
* qDebug() << "Message sent successfully.";
* } else {
* qDebug() << "Error sending the message.";
* }
* @endcode
*
* @note If the onTimeKeyboard parameter is set to true, the keyboard will be hidden after selecting
* one of the buttons, and the user won't be able to use it again.
* @note If the autoResizeKeyboard parameter is set to true, the keyboard will automatically adjust
* its size based on the number of buttons.
* @note The markdown and disableWebPagePreview parameters allow you to configure text formatting
* and web page preview options in the message.
*/ */
bool sendSpecificMessageWithKeyboard(const QVariant &chatId, bool sendSpecificMessageWithKeyboard(const QVariant &chatId,
const QString& text, const QString& text,
@ -184,32 +127,26 @@ public:
bool deleteMessage(const QVariant& chatId, const QVariant& messageId) override; bool deleteMessage(const QVariant& chatId, const QVariant& messageId) override;
/** /**
* @brief Edit a specific message's keyboard in a chat or channel. * @brief Edits a specific message with a custom keyboard in a chat.
* *
* The `editSpecificMessageWithKeyboard` method is used to edit the keyboard of a specific message in a chat or channel. * This function allows you to edit a specific message in a chat with a custom keyboard. You can update the message's text and customize its behavior as needed.
* This method allows you to modify the keyboard layout and options of an existing message, including adding or changing buttons.
* *
* @param chatId The identifier of the chat or channel where the message to be edited is located. * @param messageId The unique identifier of the message to edit.
* It can be a string, number, or another valid data type containing the chat identifier. * @param chatId The unique identifier of the chat containing the message.
* @param keyboard A list of text buttons for the new keyboard layout. * @param newText The new text content for the message.
* @param callBackQueryId A unique identifier for this message (can be used to identify responses). * @param markdown Set to true to enable Markdown formatting for the new text (optional).
* @param onTimeKeyboard A flag indicating whether the new inline keyboard should be hidden after the user interacts with it * @param disableWebPagePreview Set to true to disable web page previews for links in the new text (optional).
* (one-time keyboard). Default is `false`. * @param keyboard A list of lists containing the new keyboard buttons to display (optional).
* @param autoResizeKeyboard A flag indicating whether the new inline keyboard should automatically adjust its size based on * @param callBackQueryId The unique identifier for callback queries triggered by the edited message (optional).
* the number of buttons. Default is `false`. * @param onTimeKeyboard Set to true to display the keyboard only once (optional).
* @param autoResizeKeyboard Set to true to automatically resize the keyboard (optional).
* *
* @return `true` if the message keyboard was successfully edited, and `false` otherwise. * @return Returns true if the message was successfully edited, false otherwise.
* *
* Usage example: * @note The keyboard parameter should be a list of lists of strings representing keyboard buttons (optional).
* @code * @note The callBackQueryId parameter is used to handle callback queries when buttons are pressed (optional).
* // Edit the keyboard of a specific message * @note By default, the new text will be displayed with Markdown formatting enabled (optional).
* bool result = editSpecificMessageWithKeyboard(chatId, {"New Button 1", "New Button 2"}, "123456789", true, true); * @note By default, web page previews for links in the new text are not disabled (optional).
* if (result) {
* qDebug() << "Message keyboard edited successfully.";
* } else {
* qDebug() << "Error editing the message keyboard.";
* }
* @endcode
*/ */
bool editSpecificMessageWithKeyboard(const QVariant &messageId, bool editSpecificMessageWithKeyboard(const QVariant &messageId,
const QVariant &chatId, const QVariant &chatId,
@ -222,39 +159,25 @@ public:
bool autoResizeKeyboard = false); bool autoResizeKeyboard = false);
/** /**
* @brief Edit the keyboard of a specific message in a chat or channel. * @brief Edits a specific message with a custom keyboard in a chat.
* *
* The `editSpecificMessageWithKeyboard` method is used to modify the keyboard of a specific message in a chat or channel. * This function allows you to edit a specific message in a chat with a custom keyboard. You can update the message's text and customize its behavior as needed.
* This method allows you to customize the layout and behavior of the keyboard by providing a list of text buttons
* along with their corresponding callback functions.
* *
* @param chatId The identifier of the chat or channel where the message to be edited is located. * @param messageId The unique identifier of the message to edit.
* It can be a string, number, or another valid data type containing the chat identifier. * @param chatId The unique identifier of the chat containing the message.
* @param keyboard A list of maps, each containing buttons and their corresponding callback functions for the new keyboard layout. * @param text The new text content for the message.
* Each map should have button text as the key and a callback function as the value. * @param markdown Set to true to enable Markdown formatting for the new text (optional).
* @param callBackQueryId A unique identifier for this message (can be used to identify responses). * @param disableWebPagePreview Set to true to disable web page previews for links in the new text (optional).
* @param keyboard A list of maps where each map represents a button with a callback function (optional).
* @param callBackQueryId The unique identifier for callback queries triggered by the edited message (optional).
* *
* @return `true` if the message keyboard was successfully edited, and `false` otherwise. * @return Returns true if the message was successfully edited, false otherwise.
* *
* Usage example: * @note The keyboard parameter should be a list of maps where each map represents a button. The button's label is the map key, and the associated callback function is the map value (optional).
* @code * @note The callBackQueryId parameter is used to handle callback queries when buttons are pressed (optional).
* // Define a custom keyboard layout with callback functions * @note By default, the new text will be displayed with Markdown formatting enabled (optional).
* QList<QMap<QString, std::function<void(const QString &queryID)>> customKeyboard = { * @note By default, web page previews for links in the new text are not disabled (optional).
* { */
* {"Button 1", [](const QString &queryID) { Callback function for Button 1 }},
* {"Button 2", [](const QString &queryID) { Callback function for Button 2 }}
* }
* };
*
* // Edit the keyboard of a specific message with the custom keyboard layout
* bool result = editSpecificMessageWithKeyboard(chatId, customKeyboard, "123456789");
* if (result) {
* qDebug() << "Message keyboard edited successfully.";
* } else {
* qDebug() << "Error editing the message keyboard.";
* }
* @endcode
*/
bool editSpecificMessageWithKeyboard(const QVariant& messageId, bool editSpecificMessageWithKeyboard(const QVariant& messageId,
const QVariant &chatId, const QVariant &chatId,
const QString &text, const QString &text,
@ -264,32 +187,22 @@ public:
const QString &callBackQueryId = ""); const QString &callBackQueryId = "");
/** /**
* @brief Edit a specific message in a chat or channel with optional additional objects. * @brief Edits a specific message in a chat.
* *
* The `editSpecificMessage` method is used to edit the content of a specific message in a chat or channel. This method allows * This function allows you to edit a specific message in a chat. You can update the message's text and customize its behavior as needed.
* you to modify the message text, various message options, and additional parameters.
* *
* @param messageId The identifier of the message to be edited. * @param messageId The unique identifier of the message to edit.
* @param chatId The identifier of the chat or channel where the message to be edited is located. * @param chatId The unique identifier of the chat containing the message.
* It can be a string, number, or another valid data type containing the chat identifier. * @param newText The new text content for the message.
* @param newText The updated text for the message. * @param callBackQueryId The unique identifier for callback queries triggered by the edited message (optional).
* @param callBackQueryId A unique identifier for this message (can be used to identify responses). * @param markdown Set to true to enable Markdown formatting for the new text (optional).
* @param markdown A flag indicating whether the edited message text should be formatted using Markdown syntax. * @param disableWebPagePreview Set to true to disable web page previews for links in the new text (optional).
* If `true`, the text will be formatted using Markdown. If `false`, the text will be sent as plain text.
* Default is `true`.
* @param disableWebPagePreview A flag indicating whether to disable web page preview in the edited message.
* If `true`, web page preview will be disabled. Default is `false`.
* *
* @return `true` if the message was successfully edited, and `false` otherwise. * @return Returns true if the message was successfully edited, false otherwise.
* *
* Usage examples: * @note The callBackQueryId parameter is used to handle callback queries when applicable (optional).
* @code * @note By default, the new text will be displayed with Markdown formatting enabled (optional).
* // Edit the text of a specific message * @note By default, web page previews for links in the new text are not disabled (optional).
* bool result = editSpecificMessage(123456789, chatId, "Updated message text");
*
* // Edit the message with a callback query identifier and disable web page preview
* bool result = editSpecificMessage(987654321, chatId, "Updated message text with callback query ID", "555555555", false, true);
* @endcode
*/ */
bool editSpecificMessage(const QVariant &messageId, bool editSpecificMessage(const QVariant &messageId,
const QVariant &chatId, const QVariant &chatId,