From 306e64998c1bf1fb997c1098ae92d6edfef31cd2 Mon Sep 17 00:00:00 2001 From: Aylur Date: Wed, 23 Oct 2024 20:37:32 +0000 Subject: docs: astal3 and io comments --- lib/astal/gtk3/src/application.vala | 65 +++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) (limited to 'lib/astal/gtk3/src/application.vala') diff --git a/lib/astal/gtk3/src/application.vala b/lib/astal/gtk3/src/application.vala index 1210d88..82ee797 100644 --- a/lib/astal/gtk3/src/application.vala +++ b/lib/astal/gtk3/src/application.vala @@ -6,15 +6,28 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { private string _instance_name = "astal"; private string socket_path { get; private set; } + /** + * Emitted when a new monitor is added to [class@Gdk.Display]. + */ [DBus (visible=false)] public signal void monitor_added(Gdk.Monitor monitor); + /** + * Emitted when a monitor is disconnected from [class@Gdk.Display]. + */ [DBus (visible=false)] public signal void monitor_removed(Gdk.Monitor monitor); + /** + * Emitted when a window that has been added using + * [method@Gtk.Application.add_window] changes its visibility . + */ [DBus (visible=false)] public signal void window_toggled(Gtk.Window window); + /** + * Get all monitors from [class@Gdk.Display]. + */ [DBus (visible=false)] public List monitors { owned get { @@ -30,6 +43,11 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { } } + /** + * A unique instance name. + * + * This is the identifier used by the AstalIO package and the CLI. + */ [DBus (visible=false)] public string instance_name { owned get { return _instance_name; } @@ -39,6 +57,9 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { } } + /** + * Windows that has been added to this app using [method@Gtk.Application.add_window]. + */ [DBus (visible=false)] public List windows { get { return get_windows(); } @@ -52,24 +73,36 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { get { return Gdk.Screen.get_default(); } } + /** + * Shortcut for [property@Gtk.Settings:gtk_theme_name] + */ [DBus (visible=false)] public string gtk_theme { owned get { return settings.gtk_theme_name; } set { settings.gtk_theme_name = value; } } + /** + * Shortcut for [property@Gtk.Settings:gtk_icon_theme_name] + */ [DBus (visible=false)] public string icon_theme { owned get { return settings.gtk_icon_theme_name; } set { settings.gtk_icon_theme_name = value; } } + /** + * Shortcut for [property@Gtk.Settings:gtk_cursor_theme_name] + */ [DBus (visible=false)] public string cursor_theme { owned get { return settings.gtk_cursor_theme_name; } set { settings.gtk_cursor_theme_name = value; } } + /** + * Remove all [class@Gtk.StyleContext] providers. + */ [DBus (visible=false)] public void reset_css() { foreach(var provider in css_providers) { @@ -78,10 +111,17 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { css_providers = new List(); } + /** + * Shortcut for [func@Gtk.Window.set_interactive_debugging]. + */ public void inspector() throws DBusError, IOError { Gtk.Window.set_interactive_debugging(true); } + /** + * Get a window by its [property@Gtk.Widget:name] that has been added to this app + * using [method@Gtk.Application.add_window]. + */ [DBus (visible=false)] public Gtk.Window? get_window(string name) { foreach(var win in windows) { @@ -93,6 +133,10 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { return null; } + /** + * Toggle the visibility of a window by its [property@Gtk.Widget:name] + * that has been added to this app using [method@Gtk.Application.add_window]. + */ public void toggle_window(string window) throws Error { var win = get_window(window); if (win != null) { @@ -102,6 +146,11 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { } } + /** + * Add a new [class@Gtk.StyleContext] provider. + * + * @param style Css string or a path to a css file. + */ [DBus (visible=false)] public void apply_css(string style, bool reset = false) { var provider = new Gtk.CssProvider(); @@ -124,6 +173,9 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { css_providers.append(provider); } + /** + * Shortcut for [method@Gtk.IconTheme.prepend_search_path]. + */ [DBus (visible=false)] public void add_icons(string? path) { if (path != null) { @@ -131,11 +183,21 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { } } + /** + * Handler for an incoming request. + * + * @param msg Body of the message + * @param conn The connection which expects the response. + */ [DBus (visible=false)] public virtual void request(string msg, SocketConnection conn) { AstalIO.write_sock.begin(conn, @"missing response implementation on $application_id"); } + /** + * Attempt to acquire the astal socket for this app identified by its [property@AstalIO.Application:instance_name]. + * If the socket is in use by another app with the same name an [error@AstalIO.AppError.NAME_OCCUPIED] is thrown. + */ [DBus (visible=false)] public void acquire_socket() throws Error { string path; @@ -159,6 +221,9 @@ public class Astal.Application : Gtk.Application, AstalIO.Application { ); } + /** + * Quit and stop the socket if it was acquired. + */ public new void quit() throws DBusError, IOError { if (service != null) { service.stop(); -- cgit v1.2.3