feat(plugins): add display name change event to Channel (#6594)

Reviewed-by: Mm2PL <mm2pl+gh@kotmisia.pl>

docs/chatterino.d.ts

@@ -46,12 +46,22 @@ declare namespace c2 {
         game_id: string;
     }
 
+    class ConnectionHandle {
+        disconnect(): void;
+        block(): void;
+        unblock(): void;
+        is_blocked(): boolean;
+        is_connected(): boolean;
+    }
+
     class Channel implements IWeakResource {
         is_valid(): boolean;
         get_name(): string;
         get_type(): ChannelType;
         get_display_name(): string;
 
+        on_display_name_changed(cb: () => void): ConnectionHandle;
+
         send_message(message: string, execute_commands: boolean): void;
         send_message(message: string): void;
 

docs/lua-meta/globals.lua

@@ -244,6 +244,12 @@ function c2.Channel:is_vip() end
 ---@return string
 function c2.Channel:__tostring() end
 
+--- Callback when the channel display name changes.
+---
+---@param cb fun()
+---@return c2.ConnectionHandle hdl
+function c2.Channel:on_display_name_changed(cb) end
+
 --- Finds a channel by name.
 --- Misc channels are marked as Twitch:
 --- - /whispers
@@ -264,6 +270,37 @@ function c2.Channel.by_twitch_id(id) end
 
 -- End src/controllers/plugins/api/ChannelRef.hpp
 
+-- Begin src/controllers/plugins/api/ConnectionHandle.hpp
+
+
+
+---@class c2.ConnectionHandle
+---This type represents a handle to a registration of a callback for an event handler.
+---Conceptually, the event has a _connection_ to the callback/handler.
+---This handle can be used to modify that connection.
+---It does not automatically disconnect the connection when it's destroyed (in `__gc`) -
+---`disconnect()` has to be called manually.
+c2.ConnectionHandle = {}
+
+---Disconnect the signal
+function c2.ConnectionHandle:disconnect() end
+
+---Block events on this connection
+function c2.ConnectionHandle:block() end
+
+---Unblock events on this connection
+function c2.ConnectionHandle:unblock() end
+
+---Is this connection currently blocked?
+---@return boolean is_blocked
+function c2.ConnectionHandle:is_blocked() end
+
+---Is this connection still connected?
+---@return boolean is_connected
+function c2.ConnectionHandle:is_connected() end
+
+-- End src/controllers/plugins/api/ConnectionHandle.hpp
+
 -- Begin src/controllers/plugins/api/HTTPResponse.hpp
 
 ---@class c2.HTTPResponse

docs/wip-plugins.md

@@ -352,6 +352,15 @@ saddummys:get_display_name() -- "서새봄냥"
 
 <!-- F Korean Twitch, apparently you were not profitable enough -->
 
+##### `Channel:on_display_name_changed(cb)`
+
+Callback when the channel display name changes. The callback doesn't get any
+arguments, use [`Channel:get_display_name`](#channelget_display_name) to get the
+updated name.
+
+This returns a [`ConnectionHandle`](#connectionhandle) which can be used to
+disconnect the handler.
+
 ##### `Channel:send_message(message[, execute_commands])`
 
 Sends a message to the channel with the given text. If `execute_commands` is
@@ -775,6 +784,34 @@ This table describes links available to plugins.
 | `JumpToMessage`   | ID of the message                  | Highlight the message with given ID in current split, do nothing if it was not found | n/a                                   |
 | `InsertText`      | Any text, command or emote         | Insert text into split input                                                         | n/a                                   |
 
+#### `ConnectionHandle`
+
+This type represents a handle to a registration of a callback for an event handler.
+Conceptually, the event has a _connection_ to the callback/handler.
+This handle can be used to modify that connection.
+It does not automatically disconnect the connection when it's destroyed (in `__gc`) -
+[`disconnect()`](#connectionhandledisconnect) has to be called manually.
+
+##### `ConnectionHandle:disconnect()`
+
+Disconnect the signal.
+
+##### `ConnectionHandle:block()`
+
+Block events on this connection.
+
+##### `ConnectionHandle:unblock()`
+
+Unblock events on this connection.
+
+##### `ConnectionHandle:is_blocked()`
+
+Is this connection currently blocked?
+
+##### `ConnectionHandle:is_connected()`
+
+Is this connection still connected?
+
 ### Input/Output API
 
 These functions are wrappers for Lua's I/O library. Functions on file pointer