feat(api): add get_current_window call

Add prof_get_current_window API to retrieve the title of the currently active window, matching the titlebar display. The feature is especially useful to track currently used plugin window.
2026-07-17 20:36:21 +00:00 · 2025-09-30 16:40:02 +02:00
parent 3738be4af1
commit 266f5aa046
8 changed files with 112 additions and 57 deletions
--- a/apidocs/c/profapi.h
+++ b/apidocs/c/profapi.h
@@ -20,13 +20,13 @@
 typedef char* PROF_WIN_TAG;

 /** Function pointer for command callbacks, accepting an array of arguments. */
-typedef void(*CMD_CB)(char **args);
+typedef void (*CMD_CB)(char** args);

 /** Function pointer for timed callbacks, accepting no arguments. */
-typedef void(*TIMED_CB)(void);
+typedef void (*TIMED_CB)(void);

 /** Function pointer for window callbacks, accepting a window tag and input line. */
-typedef void(*WINDOW_CB)(PROF_WIN_TAG win, char *line);
+typedef void (*WINDOW_CB)(PROF_WIN_TAG win, char* line);

 /** Highlights the console window in the status bar. */
 void prof_cons_alert(void);
@@ -41,7 +41,7 @@ void prof_cons_alert(void);
 * prof_cons_show("This will appear in the console window");
 * @endcode
 */
-int prof_cons_show(const char * const message);
+int prof_cons_show(const char* const message);

 /**
 * Shows a message in the console with a specified theme.
@@ -57,7 +57,7 @@ int prof_cons_show(const char * const message);
 * prof_cons_show_themed("myplugin", "text", NULL, "Plugin themed message");
 * @endcode
 */
-int prof_cons_show_themed(const char *const group, const char *const item, const char *const def, const char *const message);
+int prof_cons_show_themed(const char* const group, const char* const item, const char* const def, const char* const message);

 /**
 * Shows a message indicating a command was used incorrectly.
@@ -69,7 +69,7 @@ int prof_cons_show_themed(const char *const group, const char *const item, const
 * prof_cons_bad_cmd_usage("/mycommand");
 * @endcode
 */
-int prof_cons_bad_cmd_usage(const char *const cmd);
+int prof_cons_bad_cmd_usage(const char* const cmd);

 /**
 * Registers a new command with help information and callback.
@@ -91,9 +91,9 @@ int prof_cons_bad_cmd_usage(const char *const cmd);
 * prof_register_command("/newcommand", 1, 2, synopsis, "Example command", args, examples, my_function);
 * @endcode
 */
-void prof_register_command(const char *command_name, int min_args, int max_args,
-    char **synopsis, const char *description, char *arguments[][2], char **examples,
-    CMD_CB callback);
+void prof_register_command(const char* command_name, int min_args, int max_args,
+                           char** synopsis, const char* description, char* arguments[][2], char** examples,
+                           CMD_CB callback);

 /**
 * Registers a function to be called periodically by CProof.
@@ -118,7 +118,7 @@ void prof_register_timed(TIMED_CB callback, int interval_seconds);
 * prof_completer_add("/mycommand", items);
 * @endcode
 */
-void prof_completer_add(const char *key, char **items);
+void prof_completer_add(const char* key, char** items);

 /**
 * Removes autocomplete values for a command or argument.
@@ -131,7 +131,7 @@ void prof_completer_add(const char *key, char **items);
 * prof_completer_remove("/mycommand", items);
 * @endcode
 */
-void prof_completer_remove(const char *key, char **items);
+void prof_completer_remove(const char* key, char** items);

 /**
 * Clears all autocomplete values for a command or argument.
@@ -142,7 +142,7 @@ void prof_completer_remove(const char *key, char **items);
 * prof_completer_clear("/mycommand");
 * @endcode
 */
-void prof_completer_clear(const char *key);
+void prof_completer_clear(const char* key);

 /**
 * Adds filepath autocompletion for a command or argument.
@@ -153,7 +153,7 @@ void prof_completer_clear(const char *key);
 * prof_filepath_completer_add("/filecmd");
 * @endcode
 */
-void prof_filepath_completer_add(const char *prefix);
+void prof_filepath_completer_add(const char* prefix);

 /**
 * Sends a desktop notification.
@@ -166,7 +166,7 @@ void prof_filepath_completer_add(const char *prefix);
 * prof_notify("Example notification", 5000, "Example plugin");
 * @endcode
 */
-void prof_notify(const char *message, int timeout_ms, const char *category);
+void prof_notify(const char* message, int timeout_ms, const char* category);

 /**
 * Sends a line of input to CProof to execute.
@@ -177,7 +177,7 @@ void prof_notify(const char *message, int timeout_ms, const char *category);
 * prof_send_line("/who online");
 * @endcode
 */
-void prof_send_line(char *line);
+void prof_send_line(char* line);

 /**
 * Gets the Jabber ID of the current chat recipient.
@@ -185,6 +185,17 @@ void prof_send_line(char *line);
 */
 char* prof_get_current_recipient(void);

+/**
+ * Gets the title of the current window as shown in the titlebar.
+ *
+ * Special cases:
+ * - MUC configuration window: Includes "config" and an asterisk if modified (e.g., "room@example.com config *").
+ * - vCard window: Includes the bare JID and an asterisk if modified (e.g., "vCard user@example.com *").
+ *
+ * @return A null-terminated string containing the window title. The caller must free the returned string.
+ */
+char* prof_get_current_window(void);
+
 /**
 * Gets the Jabber ID of the current chat room.
 * @return The room Jabber ID (e.g., "metalchat@conference.example.com") or NULL if not in a room.
@@ -198,7 +209,7 @@ char* prof_get_current_muc(void);
 int prof_current_win_is_console(void);

 /**
- * Gets the user’s nickname in the current chat room.
+ * Gets the user's nickname in the current chat room.
 * @return The nickname (e.g., "eddie") or NULL if not in a room.
 */
 char* prof_get_current_nick(void);
@@ -208,14 +219,14 @@ char* prof_get_current_nick(void);
 * @param barejid The Jabber ID.
 * @return The nickname (e.g., "eddie") or the barejid if not in the roster.
 */
-char* prof_get_name_from_roster(const char *barejid);
+char* prof_get_name_from_roster(const char* barejid);

 /**
 * Gets the barejid for a nickname from the roster.
 * @param name The nickname.
 * @return The barejid (e.g., "eddie@server.tld") or NULL if not in the roster.
 */
-char* prof_get_barejid_from_roster(const char *name);
+char* prof_get_barejid_from_roster(const char* name);

 /**
 * Gets nicknames of all occupants in the current chat room.
@@ -225,10 +236,10 @@ char** prof_get_current_occupants(void);

 /**
 * Gets the current nickname in a chat room.
- * @param barejid The room’s Jabber ID.
+ * @param barejid The room's Jabber ID.
 * @return The nickname.
 */
-char* prof_get_room_nick(const char *barejid);
+char* prof_get_room_nick(const char* barejid);

 /**
 * Logs a debug message to the CProof log.
@@ -239,7 +250,7 @@ char* prof_get_room_nick(const char *barejid);
 * prof_log_debug("Debug message");
 * @endcode
 */
-void prof_log_debug(const char *message);
+void prof_log_debug(const char* message);

 /**
 * Logs an info message to the CProof log.
@@ -250,7 +261,7 @@ void prof_log_debug(const char *message);
 * prof_log_info("Info message");
 * @endcode
 */
-void prof_log_info(const char *message);
+void prof_log_info(const char* message);

 /**
 * Logs a warning message to the CProof log.
@@ -261,7 +272,7 @@ void prof_log_info(const char *message);
 * prof_log_warning("Warning message");
 * @endcode
 */
-void prof_log_warning(const char *message);
+void prof_log_warning(const char* message);

 /**
 * Logs an error message to the CProof log.
@@ -272,7 +283,7 @@ void prof_log_warning(const char *message);
 * prof_log_error("Error message");
 * @endcode
 */
-void prof_log_error(const char *message);
+void prof_log_error(const char* message);

 /**
 * Creates a plugin window.
@@ -321,7 +332,7 @@ int prof_win_focus(PROF_WIN_TAG win);
 * prof_win_show("My Plugin", "Message in plugin window");
 * @endcode
 */
-int prof_win_show(PROF_WIN_TAG win, char *message);
+int prof_win_show(PROF_WIN_TAG win, char* message);

 /**
 * Shows a message in a plugin window with a specified theme.
@@ -338,7 +349,7 @@ int prof_win_show(PROF_WIN_TAG win, char *message);
 * prof_win_show_themed("My Plugin", "myplugin", "text", NULL, "Themed message");
 * @endcode
 */
-int prof_win_show_themed(PROF_WIN_TAG tag, char *group, char *key, char *def, char *message);
+int prof_win_show_themed(PROF_WIN_TAG tag, char* group, char* key, char* def, char* message);

 /**
 * Sends an XMPP stanza.
@@ -350,7 +361,7 @@ int prof_win_show_themed(PROF_WIN_TAG tag, char *group, char *key, char *def, ch
 * prof_send_stanza("<iq to='juliet@capulet.lit' id='s2c1' type='get'><ping xmlns='urn:xmpp:ping'/></iq>");
 * @endcode
 */
-int prof_send_stanza(char *stanza);
+int prof_send_stanza(char* stanza);

 /**
 * Gets a boolean setting.
@@ -365,7 +376,7 @@ int prof_send_stanza(char *stanza);
 * prof_settings_boolean_get("myplugin", "notify", 0);
 * @endcode
 */
-int prof_settings_boolean_get(char *group, char *key, int def);
+int prof_settings_boolean_get(char* group, char* key, int def);

 /**
 * Sets a boolean setting.
@@ -379,7 +390,7 @@ int prof_settings_boolean_get(char *group, char *key, int def);
 * prof_settings_boolean_set("myplugin", "activate", 1);
 * @endcode
 */
-void prof_settings_boolean_set(char *group, char *key, int value);
+void prof_settings_boolean_set(char* group, char* key, int value);

 /**
 * Gets a string setting.
@@ -394,7 +405,7 @@ void prof_settings_boolean_set(char *group, char *key, int value);
 * prof_settings_string_get("myplugin", "prefix", "prefix-->");
 * @endcode
 */
-char* prof_settings_string_get(char *group, char *key, char *def);
+char* prof_settings_string_get(char* group, char* key, char* def);

 /**
 * Sets a string setting.
@@ -408,7 +419,7 @@ char* prof_settings_string_get(char *group, char *key, char *def);
 * prof_settings_string_set("myplugin", "prefix", "myplugin, ");
 * @endcode
 */
-void prof_settings_string_set(char *group, char *key, char *value);
+void prof_settings_string_set(char* group, char* key, char* value);

 /**
 * Gets a string list setting, separated by semicolons.
@@ -422,7 +433,7 @@ void prof_settings_string_set(char *group, char *key, char *value);
 * prof_settings_string_list_get("myplugin", "somelist");
 * @endcode
 */
-char** prof_settings_string_list_get(char *group, char *key);
+char** prof_settings_string_list_get(char* group, char* key);

 /**
 * Adds an item to a string list setting.
@@ -437,7 +448,7 @@ char** prof_settings_string_list_get(char *group, char *key);
 * prof_settings_string_list_add("myplugin", "somelist", "anelement");
 * @endcode
 */
-void prof_settings_string_list_add(char *group, char *key, char *value);
+void prof_settings_string_list_add(char* group, char* key, char* value);

 /**
 * Removes an item from a string list setting.
@@ -452,7 +463,7 @@ void prof_settings_string_list_add(char *group, char *key, char *value);
 * prof_settings_string_list_remove("myplugin", "somelist", "anelement");
 * @endcode
 */
-int prof_settings_string_list_remove(char *group, char *key, char *value);
+int prof_settings_string_list_remove(char* group, char* key, char* value);

 /**
 * Clears all items from a string list setting.
@@ -466,7 +477,7 @@ int prof_settings_string_list_remove(char *group, char *key, char *value);
 * prof_settings_string_list_clear("myplugin", "somelist");
 * @endcode
 */
-int prof_settings_string_list_clear(char *group, char *key);
+int prof_settings_string_list_clear(char* group, char* key);

 /**
 * Gets an integer setting.
@@ -481,7 +492,7 @@ int prof_settings_string_list_clear(char *group, char *key);
 * prof_settings_int_get("myplugin", "timeout", 10);
 * @endcode
 */
-int prof_settings_int_get(char *group, char *key, int def);
+int prof_settings_int_get(char* group, char* key, int def);

 /**
 * Sets an integer setting.
@@ -495,7 +506,7 @@ int prof_settings_int_get(char *group, char *key, int def);
 * prof_settings_int_set("myplugin", "timeout", 100);
 * @endcode
 */
-void prof_settings_int_set(char *group, char *key, int value);
+void prof_settings_int_set(char* group, char* key, int value);

 /**
 * Triggers handling of an incoming message as if received by CProof.
@@ -508,10 +519,10 @@ void prof_settings_int_set(char *group, char *key, int value);
 * prof_incoming_message("bob@server.org", "laptop", "Hello there");
 * @endcode
 */
-void prof_incoming_message(char *barejid, char *resource, char *message);
+void prof_incoming_message(char* barejid, char* resource, char* message);

 /**
- * Adds a service discovery feature to CProof’s supported features.
+ * Adds a service discovery feature to CProof's supported features.
 * Sends a presence update if a session is connected.
 * @param feature The feature to add.
 *
@@ -520,7 +531,7 @@ void prof_incoming_message(char *barejid, char *resource, char *message);
 * prof_disco_add_feature("urn:xmpp:omemo:0:devicelist+notify");
 * @endcode
 */
-void prof_disco_add_feature(char *feature);
+void prof_disco_add_feature(char* feature);

 /**
 * Ends an encrypted session with a user.
@@ -531,7 +542,7 @@ void prof_disco_add_feature(char *feature);
 * prof_encryption_reset("alice@server.org");
 * @endcode
 */
-void prof_encryption_reset(char *barejid);
+void prof_encryption_reset(char* barejid);

 /**
 * Sets the titlebar encryption indicator text for a recipient.
@@ -544,10 +555,10 @@ void prof_encryption_reset(char *barejid);
 * prof_chat_set_titlebar_enctext("bob@example.com", "safe");
 * @endcode
 */
-int prof_chat_set_titlebar_enctext(char *barejid, char *enctext);
+int prof_chat_set_titlebar_enctext(char* barejid, char* enctext);

 /**
- * Resets the titlebar encryption indicator for a recipient to CProof’s default.
+ * Resets the titlebar encryption indicator for a recipient to CProof's default.
 * @param barejid Jabber ID of the recipient.
 * @return 1 on success, 0 on failure.
 *
@@ -556,7 +567,7 @@ int prof_chat_set_titlebar_enctext(char *barejid, char *enctext);
 * prof_chat_unset_titlebar_enctext("bob@example.com");
 * @endcode
 */
-int prof_chat_unset_titlebar_enctext(char *barejid);
+int prof_chat_unset_titlebar_enctext(char* barejid);

 /**
 * Sets the incoming message prefix character for a contact.
@@ -569,7 +580,7 @@ int prof_chat_unset_titlebar_enctext(char *barejid);
 * prof_chat_set_incoming_char("kristine@example.com", "*");
 * @endcode
 */
-int prof_chat_set_incoming_char(char *barejid, char *ch);
+int prof_chat_set_incoming_char(char* barejid, char* ch);

 /**
 * Resets the incoming message prefix character for a contact.
@@ -581,7 +592,7 @@ int prof_chat_set_incoming_char(char *barejid, char *ch);
 * prof_chat_unset_incoming_char("kristine@example.com");
 * @endcode
 */
-int prof_chat_unset_incoming_char(char *barejid);
+int prof_chat_unset_incoming_char(char* barejid);

 /**
 * Sets the outgoing message prefix character for a contact.
@@ -594,7 +605,7 @@ int prof_chat_unset_incoming_char(char *barejid);
 * prof_chat_set_outgoing_char("david@example.com", "+");
 * @endcode
 */
-int prof_chat_set_outgoing_char(char *barejid, char *ch);
+int prof_chat_set_outgoing_char(char* barejid, char* ch);

 /**
 * Resets the outgoing message prefix character for a contact.
@@ -606,7 +617,7 @@ int prof_chat_set_outgoing_char(char *barejid, char *ch);
 * prof_chat_unset_outgoing_char("david@example.com");
 * @endcode
 */
-int prof_chat_unset_outgoing_char(char *barejid);
+int prof_chat_unset_outgoing_char(char* barejid);

 /**
 * Sets the titlebar encryption indicator text for a room.
@@ -619,10 +630,10 @@ int prof_chat_unset_outgoing_char(char *barejid);
 * prof_room_set_titlebar_enctext("generalchat@conference.service.com", "secret");
 * @endcode
 */
-int prof_room_set_titlebar_enctext(char *roomjid, char *enctext);
+int prof_room_set_titlebar_enctext(char* roomjid, char* enctext);

 /**
- * Resets the titlebar encryption indicator for a room to CProof’s default.
+ * Resets the titlebar encryption indicator for a room to CProof's default.
 * @param roomjid Jabber ID of the room.
 * @return 1 on success, 0 on failure.
 *
@@ -631,7 +642,7 @@ int prof_room_set_titlebar_enctext(char *roomjid, char *enctext);
 * prof_room_unset_titlebar_enctext("generalchat@conference.service.com");
 * @endcode
 */
-int prof_room_unset_titlebar_enctext(char *roomjid);
+int prof_room_unset_titlebar_enctext(char* roomjid);

 /**
 * Sets the message prefix character for a room.
@@ -644,7 +655,7 @@ int prof_room_unset_titlebar_enctext(char *roomjid);
 * prof_room_set_message_char("ohnoes@conference.example.com", "^");
 * @endcode
 */
-int prof_room_set_message_char(char *roomjid, char *ch);
+int prof_room_set_message_char(char* roomjid, char* ch);

 /**
 * Resets the message prefix character for a room.
@@ -656,7 +667,7 @@ int prof_room_set_message_char(char *roomjid, char *ch);
 * prof_room_unset_message_char("ohnoes@conference.example.com");
 * @endcode
 */
-int prof_room_unset_message_char(char *roomjid);
+int prof_room_unset_message_char(char* roomjid);

 /**
 * Shows a message in a chat window.
@@ -669,7 +680,7 @@ int prof_room_unset_message_char(char *roomjid);
 * prof_chat_show("bob@server.org", "From a plugin in the chat window");
 * @endcode
 */
-int prof_chat_show(char *barejid, char *message);
+int prof_chat_show(char* barejid, char* message);

 /**
 * Shows a message in a chat window with a theme and prefix character.
@@ -687,7 +698,7 @@ int prof_chat_show(char *barejid, char *message);
 * prof_chat_show_themed("bob@server.org", "myplugin", "text", NULL, "!", "Themed message");
 * @endcode
 */
-int prof_chat_show_themed(char *barejid, char *group, char *item, char *def, char *ch, char *message);
+int prof_chat_show_themed(char* barejid, char* group, char* item, char* def, char* ch, char* message);

 /**
 * Shows a message in a chat room window.
@@ -700,7 +711,7 @@ int prof_chat_show_themed(char *barejid, char *group, char *item, char *def, cha
 * prof_room_show("chat@conference.example.com", "From a plugin in the chat room");
 * @endcode
 */
-int prof_room_show(char *roomjid, char *message);
+int prof_room_show(char* roomjid, char* message);

 /**
 * Shows a message in a chat room window with a theme and prefix character.
@@ -718,4 +729,4 @@ int prof_room_show(char *roomjid, char *message);
 * prof_room_show_themed("chat@conference.example.com", "myplugin", "text", NULL, "!", "Themed message");
 * @endcode
 */
-int prof_room_show_themed(char *roomjid, char *group, char *item, char *def, char *ch, char *message);
+int prof_room_show_themed(char* roomjid, char* group, char* item, char* def, char* ch, char* message);
--- a/apidocs/python/src/prof.py
+++ b/apidocs/python/src/prof.py
@@ -830,6 +830,22 @@ def get_current_recipient() -> str | None:
    """
    pass

+def get_current_window() -> str:
+    """Retrieves the title of the current window as shown in the titlebar.
+
+    Returns the title of the currently active window, matching the titlebar display.
+    Special cases:
+    - For MUC configuration windows, includes "config" and an asterisk if modified (e.g., "room@example.com config \*").
+    - For vCard windows, includes the bare JID and an asterisk if modified (e.g., "vCard user@example.com \*").
+
+    :return: The window title as a string.
+
+    Example::
+
+        title = prof.get_current_window()
+        prof.cons_show(f"Current window: {title}")
+    """
+
 def get_current_muc() -> str | None:
    """Retrieves the Jabber ID of the current chat room.

--- a/src/plugins/api.c
+++ b/src/plugins/api.c
@@ -54,6 +54,7 @@
 #include "plugins/settings.h"
 #include "plugins/disco.h"
 #include "ui/ui.h"
+#include "ui/win_types.h"
 #include "ui/window_list.h"
 #include "xmpp/roster_list.h"

@@ -205,6 +206,13 @@ api_get_current_recipient(void)
    }
 }

+gchar*
+api_get_current_window(void)
+{
+    ProfWin* current = wins_get_current();
+    return win_get_title(current);
+}
+
 char*
 api_get_current_muc(void)
 {
--- a/src/plugins/api.h
+++ b/src/plugins/api.h
@@ -46,6 +46,7 @@ void api_notify(const char* message, const char* category, int timeout_ms);
 void api_send_line(char* line);

 char* api_get_current_recipient(void);
+gchar* api_get_current_window(void);
 char* api_get_current_muc(void);
 gboolean api_current_win_is_console(void);
 char* api_get_current_nick(void);
--- a/src/plugins/c_api.c
+++ b/src/plugins/c_api.c
@@ -165,6 +165,12 @@ c_api_get_current_recipient(void)
    return api_get_current_recipient();
 }

+static char*
+c_api_get_current_window(void)
+{
+    return api_get_current_window();
+}
+
 static char*
 c_api_get_current_muc(void)
 {
@@ -477,6 +483,7 @@ c_api_init(void)
    prof_notify = c_api_notify;
    prof_send_line = c_api_send_line;
    prof_get_current_recipient = c_api_get_current_recipient;
+    prof_get_current_window = c_api_get_current_window;
    prof_get_current_muc = c_api_get_current_muc;
    prof_current_win_is_console = c_api_current_win_is_console;
    prof_get_current_nick = c_api_get_current_nick;
--- a/src/plugins/profapi.c
+++ b/src/plugins/profapi.c
@@ -62,6 +62,7 @@ void (*prof_notify)(const char* message, int timeout_ms, const char* category) =
 void (*prof_send_line)(char* line) = NULL;

 char* (*prof_get_current_recipient)(void) = NULL;
+char* (*prof_get_current_window)(void) = NULL;
 char* (*prof_get_current_muc)(void) = NULL;
 int (*prof_current_win_is_console)(void) = NULL;
 char* (*prof_get_current_nick)(void) = NULL;
--- a/src/plugins/profapi.h
+++ b/src/plugins/profapi.h
@@ -71,6 +71,7 @@ void (*prof_notify)(const char* message, int timeout_ms, const char* category);
 void (*prof_send_line)(char* line);

 char* (*prof_get_current_recipient)(void);
+char* (*prof_get_current_window)(void);
 char* (*prof_get_current_muc)(void);
 int (*prof_current_win_is_console)(void);
 char* (*prof_get_current_nick)(void);
--- a/src/plugins/python_api.c
+++ b/src/plugins/python_api.c
@@ -415,6 +415,15 @@ python_api_get_current_recipient(PyObject* self, PyObject* args)
    }
 }

+static PyObject*
+python_api_get_current_window(PyObject* self, PyObject* args)
+{
+    allow_python_threads();
+    auto_gchar gchar* recipient = api_get_current_window();
+    disable_python_threads();
+    return Py_BuildValue("s", recipient);
+}
+
 static PyObject*
 python_api_get_current_muc(PyObject* self, PyObject* args)
 {
@@ -1530,6 +1539,7 @@ static PyMethodDef apiMethods[] = {
    { "send_line", python_api_send_line, METH_VARARGS, "Send a line of input." },
    { "notify", python_api_notify, METH_VARARGS, "Send desktop notification." },
    { "get_current_recipient", python_api_get_current_recipient, METH_VARARGS, "Return the jid of the recipient of the current window." },
+    { "get_current_window", python_api_get_current_window, METH_VARARGS, "Return title of the current window." },
    { "get_current_muc", python_api_get_current_muc, METH_VARARGS, "Return the jid of the room of the current window." },
    { "get_current_nick", python_api_get_current_nick, METH_VARARGS, "Return nickname in current room." },
    { "get_name_from_roster", python_api_get_name_from_roster, METH_VARARGS, "Return nickname in roster of barejid." },