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 ++++++++++++++++++++++++ lib/astal/gtk3/src/meson.build | 57 +++++++++++++++------ lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi | 5 +- lib/astal/gtk3/src/widget/box.vala | 3 ++ lib/astal/gtk3/src/widget/button.vala | 18 +++++-- lib/astal/gtk3/src/widget/centerbox.vala | 3 ++ lib/astal/gtk3/src/widget/circularprogress.vala | 26 ++++++++++ lib/astal/gtk3/src/widget/eventbox.vala | 9 ++++ lib/astal/gtk3/src/widget/icon.vala | 12 ++++- lib/astal/gtk3/src/widget/label.vala | 6 +++ lib/astal/gtk3/src/widget/levelbar.vala | 3 ++ lib/astal/gtk3/src/widget/overlay.vala | 8 +++ lib/astal/gtk3/src/widget/scrollable.vala | 8 +++ lib/astal/gtk3/src/widget/slider.vala | 27 +++++++++- lib/astal/gtk3/src/widget/stack.vala | 14 +++++ lib/astal/gtk3/src/widget/window.vala | 50 +++++++++++++++++- 16 files changed, 287 insertions(+), 27 deletions(-) (limited to 'lib/astal/gtk3/src') 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(); diff --git a/lib/astal/gtk3/src/meson.build b/lib/astal/gtk3/src/meson.build index c8c7df2..bf8f72a 100644 --- a/lib/astal/gtk3/src/meson.build +++ b/lib/astal/gtk3/src/meson.build @@ -60,8 +60,7 @@ foreach protocol : protocols client_protocol_srcs += [client_header, code] endforeach -sources = [ - config, +vala_sources = [config] + files( 'widget/box.vala', 'widget/button.vala', 'widget/centerbox.vala', @@ -77,31 +76,47 @@ sources = [ 'widget/widget.vala', 'widget/window.vala', 'application.vala', - 'idle-inhibit.h', 'idle-inhibit.c', -] + client_protocol_srcs +) + +sources = vala_sources + client_protocol_srcs + files( + 'idle-inhibit.h', +) lib = library( meson.project_name(), sources, dependencies: deps, - vala_args: ['--pkg', 'AstalInhibitManager'], + vala_args: ['--vapi-comments', '--pkg', 'AstalInhibitManager'], vala_header: meson.project_name() + '.h', vala_vapi: meson.project_name() + '-' + api_version + '.vapi', - vala_gir: gir, version: meson.project_version(), install: true, - install_dir: [true, true, true, true], + install_dir: [true, true, true], ) -import('pkgconfig').generate( - lib, - name: meson.project_name(), - filebase: meson.project_name() + '-' + api_version, - version: meson.project_version(), - subdirs: meson.project_name(), - requires: pkgconfig_deps, - install_dir: libdir / 'pkgconfig', +pkgs = [] +foreach dep : pkgconfig_deps + pkgs += ['--pkg=' + dep.name()] +endforeach + +gir_tgt = custom_target( + gir, + command: [ + find_program('python3'), + girpy, + meson.project_name(), + gir + ':src/' + gir, + ] + + pkgs + + vala_sources + + [meson.project_source_root() / 'src' / 'vapi' / 'AstalInhibitManager.vapi'], + + input: sources, + depends: lib, + output: gir, + install: true, + install_dir: get_option('datadir') / 'gir-1.0', ) custom_target( @@ -114,7 +129,17 @@ custom_target( ], input: lib, output: typelib, - depends: lib, + depends: [lib, gir_tgt], install: true, install_dir: libdir / 'girepository-1.0', ) + +import('pkgconfig').generate( + lib, + name: meson.project_name(), + filebase: meson.project_name() + '-' + api_version, + version: meson.project_version(), + subdirs: meson.project_name(), + requires: pkgconfig_deps, + install_dir: libdir / 'pkgconfig', +) diff --git a/lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi b/lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi index 6232a3c..b2b3b34 100644 --- a/lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi +++ b/lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi @@ -5,9 +5,8 @@ namespace Astal { public static unowned InhibitManager? get_default(); public Inhibitor inhibit (Gtk.Window window); } - + [CCode (cheader_filename = "idle-inhibit.h", free_function = "zwp_idle_inhibitor_v1_destroy")] [Compact] - public class Inhibitor { - } + public class Inhibitor { } } diff --git a/lib/astal/gtk3/src/widget/box.vala b/lib/astal/gtk3/src/widget/box.vala index d23a799..d049161 100644 --- a/lib/astal/gtk3/src/widget/box.vala +++ b/lib/astal/gtk3/src/widget/box.vala @@ -1,4 +1,7 @@ public class Astal.Box : Gtk.Box { + /** + * Corresponds to [property@Gtk.Orientable :orientation]. + */ [CCode (notify = false)] public bool vertical { get { return orientation == Gtk.Orientation.VERTICAL; } diff --git a/lib/astal/gtk3/src/widget/button.vala b/lib/astal/gtk3/src/widget/button.vala index bc10577..2d3095a 100644 --- a/lib/astal/gtk3/src/widget/button.vala +++ b/lib/astal/gtk3/src/widget/button.vala @@ -1,3 +1,9 @@ +/** + * This button has no extra functionality on top if its base [class@Gtk.Button] class. + * + * The purpose of this Button subclass is to have a destructable + * struct as the argument in GJS event handlers. + */ public class Astal.Button : Gtk.Button { public signal void hover (HoverEvent event); public signal void hover_lost (HoverEvent event); @@ -39,9 +45,9 @@ public enum Astal.MouseButton { FORWARD = 5, } -// these structs are here because gjs converts every event -// into a union Gdk.Event, which cannot be destructured -// and are not as convinent to work with as a struct +/** + * Struct for [struct@Gdk.EventButton] + */ public struct Astal.ClickEvent { bool release; uint time; @@ -59,6 +65,9 @@ public struct Astal.ClickEvent { } } +/** + * Struct for [struct@Gdk.EventCrossing] + */ public struct Astal.HoverEvent { bool lost; uint time; @@ -78,6 +87,9 @@ public struct Astal.HoverEvent { } } +/** + * Struct for [struct@Gdk.EventScroll] + */ public struct Astal.ScrollEvent { uint time; double x; diff --git a/lib/astal/gtk3/src/widget/centerbox.vala b/lib/astal/gtk3/src/widget/centerbox.vala index 89bf50b..d74a2c4 100644 --- a/lib/astal/gtk3/src/widget/centerbox.vala +++ b/lib/astal/gtk3/src/widget/centerbox.vala @@ -1,4 +1,7 @@ public class Astal.CenterBox : Gtk.Box { + /** + * Corresponds to [property@Gtk.Orientable :orientation]. + */ [CCode (notify = false)] public bool vertical { get { return orientation == Gtk.Orientation.VERTICAL; } diff --git a/lib/astal/gtk3/src/widget/circularprogress.vala b/lib/astal/gtk3/src/widget/circularprogress.vala index dd7c97b..a3ecdf1 100644 --- a/lib/astal/gtk3/src/widget/circularprogress.vala +++ b/lib/astal/gtk3/src/widget/circularprogress.vala @@ -1,8 +1,34 @@ +/** + * CircularProgress is a subclass of [class@Gtk.Bin] which provides a circular progress bar + * with customizable properties such as starting and ending points, + * progress value, and visual features like rounded ends and inversion of progress direction. + */ public class Astal.CircularProgress : Gtk.Bin { + /** + * The starting point of the progress circle, + * where 0 represents 3 o'clock position or 0° degrees and 1 represents 360°. + */ public double start_at { get; set; } + + /** + * The cutoff point of the background color of the progress circle. + */ public double end_at { get; set; } + + /** + * The value which determines the arc of the drawn foreground color. + * Should be a value between 0 and 1. + */ public double value { get; set; } + + /** + * Inverts the progress direction, making it draw counterclockwise. + */ public bool inverted { get; set; } + + /** + * Renders rounded ends at both the start and the end of the progress bar. + */ public bool rounded { get; set; } construct { diff --git a/lib/astal/gtk3/src/widget/eventbox.vala b/lib/astal/gtk3/src/widget/eventbox.vala index 611da2a..0b588e9 100644 --- a/lib/astal/gtk3/src/widget/eventbox.vala +++ b/lib/astal/gtk3/src/widget/eventbox.vala @@ -1,3 +1,9 @@ +/** + * EventBox is a [class@Gtk.EventBox] subclass which is meant to fix an issue with its + * [signal@Gtk.Widget::enter_notify_event] and [signal@Gtk.Widget::leave_notify_event] when nesting EventBoxes + * + * Its css selector is `eventbox`. + */ public class Astal.EventBox : Gtk.EventBox { public signal void hover (HoverEvent event); public signal void hover_lost (HoverEvent event); @@ -49,6 +55,9 @@ public class Astal.EventBox : Gtk.EventBox { } } +/** + * Struct for [struct@Gdk.EventMotion] + */ public struct Astal.MotionEvent { uint time; double x; diff --git a/lib/astal/gtk3/src/widget/icon.vala b/lib/astal/gtk3/src/widget/icon.vala index f2d59a2..9a20359 100644 --- a/lib/astal/gtk3/src/widget/icon.vala +++ b/lib/astal/gtk3/src/widget/icon.vala @@ -1,10 +1,20 @@ +/** + * [class@Gtk.Image] subclass meant to be used only for icons. + * + * It's size is calculated from `font-size` css property. + * Its css selector is `icon`. + */ public class Astal.Icon : Gtk.Image { private IconType type = IconType.NAMED; private double size { get; set; default = 14; } public new Gdk.Pixbuf pixbuf { get; set; } + public GLib.Icon g_icon { get; set; } + + /** + * Either a named icon or a path to a file. + */ public string icon { get; set; default = ""; } - public GLib.Icon g_icon {get; set;} public static Gtk.IconInfo? lookup_icon(string icon) { var theme = Gtk.IconTheme.get_default(); diff --git a/lib/astal/gtk3/src/widget/label.vala b/lib/astal/gtk3/src/widget/label.vala index 4063b6f..899cba9 100644 --- a/lib/astal/gtk3/src/widget/label.vala +++ b/lib/astal/gtk3/src/widget/label.vala @@ -1,11 +1,17 @@ using Pango; public class Astal.Label : Gtk.Label { + /** + * Shortcut for setting [property@Gtk.Label:ellipsize] to [enum@Pango.EllipsizeMode.END] + */ public bool truncate { set { ellipsize = value ? EllipsizeMode.END : EllipsizeMode.NONE; } get { return ellipsize == EllipsizeMode.END; } } + /** + * Shortcut for setting [property@Gtk.Label:justify] to [enum@Gtk.Justification.FILL] + */ public new bool justify_fill { set { justify = value ? Gtk.Justification.FILL : Gtk.Justification.LEFT; } get { return justify == Gtk.Justification.FILL; } diff --git a/lib/astal/gtk3/src/widget/levelbar.vala b/lib/astal/gtk3/src/widget/levelbar.vala index 9b61957..3e98afb 100644 --- a/lib/astal/gtk3/src/widget/levelbar.vala +++ b/lib/astal/gtk3/src/widget/levelbar.vala @@ -1,4 +1,7 @@ public class Astal.LevelBar : Gtk.LevelBar { + /** + * Corresponds to [property@Gtk.Orientable :orientation]. + */ [CCode (notify = false)] public bool vertical { get { return orientation == Gtk.Orientation.VERTICAL; } diff --git a/lib/astal/gtk3/src/widget/overlay.vala b/lib/astal/gtk3/src/widget/overlay.vala index 603ee66..ed5f03b 100644 --- a/lib/astal/gtk3/src/widget/overlay.vala +++ b/lib/astal/gtk3/src/widget/overlay.vala @@ -1,6 +1,11 @@ public class Astal.Overlay : Gtk.Overlay { public bool pass_through { get; set; } + /** + * First [property@Astal.Overlay:overlays] element. + * + * WARNING: setting this value will remove every overlay but the first. + */ public Gtk.Widget? overlay { get { return overlays.nth_data(0); } set { @@ -14,6 +19,9 @@ public class Astal.Overlay : Gtk.Overlay { } } + /** + * Sets the overlays of this Overlay. [method@Gtk.Overlay.add_overlay]. + */ public List overlays { owned get { return get_children(); } set { diff --git a/lib/astal/gtk3/src/widget/scrollable.vala b/lib/astal/gtk3/src/widget/scrollable.vala index 57afb6e..57a440c 100644 --- a/lib/astal/gtk3/src/widget/scrollable.vala +++ b/lib/astal/gtk3/src/widget/scrollable.vala @@ -1,3 +1,11 @@ +/** + * Subclass of [class@Gtk.ScrolledWindow] which has its policy default to + * [enum@Gtk.PolicyType.AUTOMATIC]. + * + * Its css selector is `scrollable`. + * Its child getter returns the child of the inner + * [class@Gtk.Viewport], instead of the viewport. + */ public class Astal.Scrollable : Gtk.ScrolledWindow { private Gtk.PolicyType _hscroll = Gtk.PolicyType.AUTOMATIC; private Gtk.PolicyType _vscroll = Gtk.PolicyType.AUTOMATIC; diff --git a/lib/astal/gtk3/src/widget/slider.vala b/lib/astal/gtk3/src/widget/slider.vala index 466275b..97cfb69 100644 --- a/lib/astal/gtk3/src/widget/slider.vala +++ b/lib/astal/gtk3/src/widget/slider.vala @@ -1,12 +1,20 @@ +/** + * Subclass of [class@Gtk.Scale] which adds a signal and property for the drag state. + */ public class Astal.Slider : Gtk.Scale { + /** + * Corresponds to [property@Gtk.Orientable :orientation]. + */ [CCode (notify = false)] public bool vertical { get { return orientation == Gtk.Orientation.VERTICAL; } set { orientation = value ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL; } } - // emitted when the user drags the slider - public signal void dragged (); + /** + * Emitted when the user drags the slider or uses keyboard arrows and its value changes. + */ + public signal void dragged(); construct { draw_value = false; @@ -45,23 +53,38 @@ public class Astal.Slider : Gtk.Scale { }); } + /** + * `true` when the user drags the slider or uses keyboard arrows. + */ public bool dragging { get; private set; } + /** + * Value of this slider. Defaults to `0`. + */ public double value { get { return adjustment.value; } set { if (!dragging) adjustment.value = value; } } + /** + * Minimum possible value of this slider. Defaults to `0`. + */ public double min { get { return adjustment.lower; } set { adjustment.lower = value; } } + /** + * Maximum possible value of this slider. Defaults to `1`. + */ public double max { get { return adjustment.upper; } set { adjustment.upper = value; } } + /** + * Size of step increments. Defaults to `0.05`. + */ public double step { get { return adjustment.step_increment; } set { adjustment.step_increment = value; } diff --git a/lib/astal/gtk3/src/widget/stack.vala b/lib/astal/gtk3/src/widget/stack.vala index 02f9959..4e856a6 100644 --- a/lib/astal/gtk3/src/widget/stack.vala +++ b/lib/astal/gtk3/src/widget/stack.vala @@ -1,4 +1,12 @@ +/** + * Subclass of [class@Gtk.Stack] that has a children setter which + * invokes [method@Gt.Stack.add_named] with the child's [property@Gtk.Widget:name] property. + */ public class Astal.Stack : Gtk.Stack { + /** + * Same as [property@Gtk.Stack:visible-child-name]. + */ + [CCode (notify = false)] public string shown { get { return visible_child_name; } set { visible_child_name = value; } @@ -23,4 +31,10 @@ public class Astal.Stack : Gtk.Stack { } } } + + construct { + notify["visible_child_name"].connect(() => { + notify_property("shown"); + }); + } } diff --git a/lib/astal/gtk3/src/widget/window.vala b/lib/astal/gtk3/src/widget/window.vala index 2690365..e513242 100644 --- a/lib/astal/gtk3/src/widget/window.vala +++ b/lib/astal/gtk3/src/widget/window.vala @@ -10,7 +10,13 @@ public enum Astal.WindowAnchor { public enum Astal.Exclusivity { NORMAL, + /** + * Request the compositor to allocate space for this window. + */ EXCLUSIVE, + /** + * Request the compositor to stack layers on top of each other. + */ IGNORE, } @@ -22,11 +28,23 @@ public enum Astal.Layer { } public enum Astal.Keymode { + /** + * Window should not receive keyboard events. + */ NONE = 0, // GtkLayerShell.KeyboardMode.NONE + /** + * Window should have exclusive focus if it is on the top or overlay layer. + */ EXCLUSIVE = 1, // GtkLayerShell.KeyboardMode.EXCLUSIVE + /** + * Focus and Unfocues the window as needed. + */ ON_DEMAND = 2, // GtkLayerShell.KeyboardMode.ON_DEMAND } +/** + * Subclass of [class@Gtk.Window] which integrates GtkLayerShell as class fields. + */ public class Astal.Window : Gtk.Window { private static bool check(string action) { if (!is_supported()) { @@ -44,12 +62,18 @@ public class Astal.Window : Gtk.Window { if (check("initialize layer shell")) return; + // If the window has no size allocatoted when it gets mapped. + // It won't show up later either when it size changes by adding children. height_request = 1; width_request = 1; + init_for_window(this); inhibit_manager = InhibitManager.get_default(); } + /** + * When `true` it will permit inhibiting the idle behavior such as screen blanking, locking, and screensaving. + */ public bool inhibit { set { if (inhibit_manager == null) { @@ -74,11 +98,20 @@ public class Astal.Window : Gtk.Window { } } + /** + * Namespace of this window. This can be used to target the layer in compositor rules. + */ public string namespace { get { return get_namespace(this); } set { set_namespace(this, value); } } + /** + * Edges to anchor the window to. + * + * If two perpendicular edges are anchored, the surface will be anchored to that corner. + * If two opposite edges are anchored, the window will be stretched across the screen in that direction. + */ public int anchor { set { if (check("set anchor")) @@ -107,6 +140,9 @@ public class Astal.Window : Gtk.Window { } } + /** + * Exclusivity of this window. + */ public Exclusivity exclusivity { set { if (check("set exclusivity")) @@ -135,6 +171,9 @@ public class Astal.Window : Gtk.Window { } } + /** + * Which layer to appear this window on. + */ public Layer layer { get { return (Layer)get_layer(this); } set { @@ -145,6 +184,9 @@ public class Astal.Window : Gtk.Window { } } + /** + * Keyboard mode of this window. + */ public Keymode keymode { get { return (Keymode)get_keyboard_mode(this); } set { @@ -155,6 +197,9 @@ public class Astal.Window : Gtk.Window { } } + /** + * Which monitor to appear this window on. + */ public Gdk.Monitor gdkmonitor { get { return get_monitor(this); } set { @@ -218,8 +263,9 @@ public class Astal.Window : Gtk.Window { } /** - * CAUTION: the id might not be the same mapped by the compositor - * to reset and let the compositor map it pass a negative number + * Which monitor to appear this window on. + * + * CAUTION: the id might not be the same mapped by the compositor. */ public int monitor { set { -- cgit v1.2.3