zoriya/astal
1
0
Fork 0
mirror of https://github.com/zoriya/astal.git synced 2026-06-01 01:38:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

improve docs

Browse Source
This commit is contained in:
kotontrion
2024-07-17 16:57:19 +02:00
parent 8ed44bdd98
commit fea47f78b9
4 changed files with 182 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/astal-river.h
+5 -96
View File
@@ -9,139 +9,48 @@ G_BEGIN_DECLS
G_DECLARE_FINAL_TYPE(AstalRiverOutput, astal_river_output, ASTAL_RIVER, OUTPUT, GObject)
/**
* astal_river_output_get_nid
* @self: the AstalRiverOutput object
*
* Returns: the id of the output
*/
guint astal_river_output_get_id(AstalRiverOutput *self);
/**
* astal_river_output_get_name
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the name of the output
*/
gchar *astal_river_output_get_name(AstalRiverOutput *self);
/**
* astal_river_output_get_layout_name
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the currently used layout name of the output
*/
gchar *astal_river_output_get_layout_name(AstalRiverOutput *self);
/**
* astal_river_output_get_focused_view
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the focused view on the output
*/
gchar *astal_river_output_get_focused_view(AstalRiverOutput *self);
/**
* astal_river_output_get_focused_tags
* @self: the AstalRiverOutput object
*
* Returns: the focused tags of the output
*/
guint astal_river_output_get_focused_tags(AstalRiverOutput *self);
/**
* astal_river_output_get_urgent_tags
* @self: the AstalRiverOutput object
*
* Returns: the urgent tags of the output
*/
guint astal_river_output_get_urgent_tags(AstalRiverOutput *self);
/**
* astal_river_output_get_occupied_tags
* @self: the AstalRiverOutput object
*
* Returns: the occupied tags of the output
*/
guint astal_river_output_get_occupied_tags(AstalRiverOutput *self);
#define ASTAL_RIVER_TYPE_RIVER (astal_river_river_get_type())
G_DECLARE_FINAL_TYPE(AstalRiverRiver, astal_river_river, ASTAL_RIVER, RIVER, GObject)
/**
* astal_river_river_new
*
* Returns: (nullable): a newly created connection to river
*/
AstalRiverRiver *astal_river_river_new();
/**
* astal_river_river_get_default
*
* Returns: (nullable) (transfer none): gets the default River object.
*/
AstalRiverRiver *astal_river_river_get_default();
/**
* astal_river_river_get_outputs
* @self: the AstalRiverRiver object
*
* Returns: (transfer none) (element-type AstalRiver.Output): a list of all outputs
*
*/
AstalRiverRiver *astal_river_get_default();
GList *astal_river_river_get_outputs(AstalRiverRiver *self);
/**
* astal_river_river_get_output
* @self: the AstalRiverRiver object
* @name: the name of the output
*
* Returns: (transfer none) (nullable): the output with the given name or null
*/
AstalRiverOutput *astal_river_river_get_output(AstalRiverRiver *self, gchar *name);
/**
* astal_river_river_get_focused_view
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the currently focused view
*/
gchar *astal_river_river_get_focused_view(AstalRiverRiver *self);
/**
* astal_river_river_get_focused_output
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the name of the currently focused output
*/
gchar *astal_river_river_get_focused_output(AstalRiverRiver *self);
/**
* astal_river_river_get_mode
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the currently active mode
*/
gchar *astal_river_river_get_mode(AstalRiverRiver *self);
/**
* AstalRiverCommandCallback:
* @success: a #gboolean.
* @msg: a string.
* @success: a #gboolean indicating whether the command was executed successfully
* @msg: a string containing the result of the command
*
* A callback function that gets a #GObject, a #gboolean, and a string.
* A callback function that is called after a river command is run.
*/
typedef void (*AstalRiverCommandCallback)(gboolean success, const gchar *msg);
/**
* astal_river_river_run_command_async:
* @self: the AstalRiverRiver object
* @length: the length of the cmd array
* @cmd: (array length=length): the command to execute
* @callback: (scope async) (nullable): the callback to invoke.
*
* Calls the given callback with the provided parameters.
*/
void astal_river_river_run_command_async(AstalRiverRiver *self, gint length, const gchar **cmd,
AstalRiverCommandCallback callback);
include/river-private.h
+2 -2
View File
@@ -3,8 +3,8 @@
#include <wayland-client.h>
#include "river-status-unstable-v1-client.h"
#include "astal-river.h"
#include "river-status-unstable-v1-client.h"
G_BEGIN_DECLS
@@ -13,7 +13,7 @@ AstalRiverOutput *astal_river_output_new(guint id, struct wl_output *wl_output,
struct wl_display *wl_display);
struct wl_output *astal_river_output_get_wl_output(AstalRiverOutput *self);
void astal_river_output_set_focused_view(AstalRiverOutput *self, gchar *focused_view);
void astal_river_output_set_focused_view(AstalRiverOutput *self, const gchar *focused_view);
G_END_DECLS
src/river-output.c
+79 -2
View File
@@ -47,25 +47,67 @@ static GParamSpec* astal_river_output_properties[ASTAL_RIVER_OUTPUT_N_PROPERTIES
NULL,
};
/**
* astal_river_output_get_nid
* @self: the AstalRiverOutput object
*
* Returns: the id of the underlying wl_output object
*/
guint astal_river_output_get_id(AstalRiverOutput* self) { return self->id; }
/**
* astal_river_output_get_name
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the name of the output
*/
gchar* astal_river_output_get_name(AstalRiverOutput* self) { return self->name; }
/**
* astal_river_output_get_layout_name
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the currently used layout name of the output
*/
gchar* astal_river_output_get_layout_name(AstalRiverOutput* self) { return self->layout_name; }
/**
* astal_river_output_get_focused_view
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the focused view on the output
*/
gchar* astal_river_output_get_focused_view(AstalRiverOutput* self) { return self->focused_view; }
void astal_river_output_set_focused_view(AstalRiverOutput* self, gchar* focused_view) {
void astal_river_output_set_focused_view(AstalRiverOutput* self, const gchar* focused_view) {
g_free(self->focused_view);
self->focused_view = g_strdup(focused_view);
g_object_notify(G_OBJECT(self), "focused-view");
g_signal_emit(self, astal_river_output_signals[ASTAL_RIVER_OUTPUT_SIGNAL_CHANGED], 0);
}
/**
* astal_river_output_get_focused_tags
* @self: the AstalRiverOutput object
*
* Returns: the focused tags of the output
*/
guint astal_river_output_get_focused_tags(AstalRiverOutput* self) { return self->focused_tags; }
/**
* astal_river_output_get_urgent_tags
* @self: the AstalRiverOutput object
*
* Returns: the urgent tags of the output
*/
guint astal_river_output_get_urgent_tags(AstalRiverOutput* self) { return self->urgent_tags; }
/**
* astal_river_output_get_occupied_tags
* @self: the AstalRiverOutput object
*
* Returns: the occupied tags of the output
*/
guint astal_river_output_get_occupied_tags(AstalRiverOutput* self) { return self->occupied_tags; }
struct wl_output* astal_river_output_get_wl_output(AstalRiverOutput* self) {
@@ -240,26 +282,61 @@ static void astal_river_output_class_init(AstalRiverOutputClass* class) {
object_class->get_property = astal_river_output_get_property;
object_class->set_property = astal_river_output_set_property;
object_class->finalize = astal_river_output_finalize;
/**
* AstalRiverOutput:focused-tags:
*
* The currently focused tags
*/
astal_river_output_properties[ASTAL_RIVER_OUTPUT_PROP_FOCUSED_TAGS] = g_param_spec_uint(
"focused-tags", "focused-tags", "currently focused tags", 0, INT_MAX, 0, G_PARAM_READABLE);
/**
* AstalRiverOutput:occupied-tags:
*
* The currently occupied tags
*/
astal_river_output_properties[ASTAL_RIVER_OUTPUT_PROP_OCCUPIED_TAGS] =
g_param_spec_uint("occupied-tags", "occupied-tags", "currently occupied tags", 0, INT_MAX,
0, G_PARAM_READABLE);
/**
* AstalRiverOutput:urgent-tags:
*
* The currently tags marked as urgent
*/
astal_river_output_properties[ASTAL_RIVER_OUTPUT_PROP_URGENT_TAGS] = g_param_spec_uint(
"urgent-tags", "urgent-tags", "currently urgent tags", 0, INT_MAX, 0, G_PARAM_READABLE);
/**
* AstalRiverOutput:id:
*
* The id of the underlying wl_output object
*/
astal_river_output_properties[ASTAL_RIVER_OUTPUT_PROP_ID] =
g_param_spec_uint("id", "id", "id of the output object", 0, INT_MAX, 0, G_PARAM_READABLE);
/**
* AstalRiverOutput:layout-name:
*
* The name of active layout
*/
astal_river_output_properties[ASTAL_RIVER_OUTPUT_PROP_LAYOUT_NAME] = g_param_spec_string(
"layout-name", "layout-name", "name of the current layout", NULL, G_PARAM_READABLE);
/**
* AstalRiverOutput:name:
*
* The name of this output
*/
astal_river_output_properties[ASTAL_RIVER_OUTPUT_PROP_NAME] =
g_param_spec_string("name", "name", "name of the output", NULL, G_PARAM_READABLE);
/**
* AstalRiverOutput:focused-view:
*
* The name of currently focused view
*/
astal_river_output_properties[ASTAL_RIVER_OUTPUT_PROP_FOCUSED_VIEW] =
g_param_spec_string("focused-view", "focused-view",
"name of last focused view on this output", NULL, G_PARAM_READABLE);
g_object_class_install_properties(object_class, ASTAL_RIVER_OUTPUT_N_PROPERTIES,
astal_river_output_properties);
astal_river_output_signals[ASTAL_RIVER_OUTPUT_SIGNAL_CHANGED] =
g_signal_new("changed", G_TYPE_FROM_CLASS(class), G_SIGNAL_RUN_FIRST, 0, NULL, NULL, NULL,
G_TYPE_NONE, 0);
src/river.c
+96 -2
View File
@@ -94,16 +94,48 @@ static AstalRiverOutput* find_output_by_name(AstalRiverRiver* self, gchar* name)
return NULL;
}
/**
* astal_river_river_get_outputs
* @self: the AstalRiverRiver object
*
* Returns: (transfer none) (element-type AstalRiver.Output): a list of all outputs
*
*/
GList* astal_river_river_get_outputs(AstalRiverRiver* self) { return self->outputs; }
/**
* astal_river_river_get_output
* @self: the AstalRiverRiver object
* @name: the name of the output
*
* Returns: (transfer none) (nullable): the output with the given name or null
*/
AstalRiverOutput* astal_river_river_get_output(AstalRiverRiver* self, gchar* name) {
return find_output_by_name(self, name);
}
/**
* astal_river_river_get_focused_view
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the currently focused view
*/
gchar* astal_river_river_get_focused_view(AstalRiverRiver* self) { return self->focused_view; }
/**
* astal_river_river_get_focused_output
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the name of the currently focused output
*/
gchar* astal_river_river_get_focused_output(AstalRiverRiver* self) { return self->focused_output; }
/**
* astal_river_river_get_mode
* @self: the AstalRiverOutput object
*
* Returns: (transfer none) (nullable): the currently active mode
*/
gchar* astal_river_river_get_mode(AstalRiverRiver* self) { return self->mode; }
static void astal_river_river_get_property(GObject* object, guint property_id, GValue* value,
@@ -235,6 +267,15 @@ static void astal_river_river_callback_failure(void* data, struct zriver_command
const struct zriver_command_callback_v1_listener cb_listener = {
.success = astal_river_river_callback_success, .failure = astal_river_river_callback_failure};
/**
* astal_river_river_run_command_async:
* @self: the AstalRiverRiver object
* @length: the length of the cmd array
* @cmd: (array length=length): the command to execute
* @callback: (scope async) (nullable): the callback to invoke.
*
* Calls the given callback with the provided parameters.
*/
void astal_river_river_run_command_async(AstalRiverRiver* self, gint length, const gchar** cmd,
AstalRiverCommandCallback callback) {
AstalRiverRiverPrivate* priv = astal_river_river_get_instance_private(self);
@@ -332,6 +373,14 @@ static void astal_river_river_init(AstalRiverRiver* self) {
priv->signal_ids = g_hash_table_new(g_direct_hash, g_direct_equal);
}
/**
* astal_river_river_new
*
* creates a new River object. It is recommended to use the get_default() method
* instead of this method.
*
* Returns: (nullable): a newly created connection to river
*/
AstalRiverRiver* astal_river_river_new() {
return g_initable_new(ASTAL_RIVER_TYPE_RIVER, NULL, NULL, NULL);
}
@@ -343,6 +392,11 @@ static void disconnect_signal(gpointer key, gpointer value, gpointer user_data)
g_signal_handler_disconnect(output, GPOINTER_TO_UINT(value));
}
/**
* astal_river_river_get_default
*
* Returns: (nullable) (transfer none): gets the default River object.
*/
AstalRiverRiver* astal_river_river_get_default() {
static AstalRiverRiver* self = NULL;
@@ -351,6 +405,13 @@ AstalRiverRiver* astal_river_river_get_default() {
return self;
}
/**
* astal_river_get_default
*
* Returns: (nullable) (transfer none): gets the default River object.
*/
AstalRiverRiver* astal_river_get_default() { return astal_river_river_get_default(); }
static void astal_river_river_finalize(GObject* object) {
AstalRiverRiver* self = ASTAL_RIVER_RIVER(object);
AstalRiverRiverPrivate* priv = astal_river_river_get_instance_private(self);
@@ -385,25 +446,58 @@ static void astal_river_river_class_init(AstalRiverRiverClass* class) {
object_class->finalize = astal_river_river_finalize;
object_class->constructed = astal_river_river_constructed;
/**
* AstalRiverRiver:mode:
*
* The currently active mode
*/
astal_river_river_properties[ASTAL_RIVER_RIVER_PROP_MODE] =
g_param_spec_string("mode", "mode", "currently active mode", NULL, G_PARAM_READABLE);
/**
* AstalRiverRiver:focused-view:
*
* The name of the currently focused view
*/
astal_river_river_properties[ASTAL_RIVER_RIVER_PROP_FOCUSED_VIEW] = g_param_spec_string(
"focused-view", "focused-view", "currently focused view", NULL, G_PARAM_READABLE);
/**
* AstalRiverRiver:focused-output:
*
* The name of the currently focused output
*/
astal_river_river_properties[ASTAL_RIVER_RIVER_PROP_FOCUSED_OUTPUT] = g_param_spec_string(
"focused-output", "focused-output", "currently focused-output", NULL, G_PARAM_READABLE);
/**
* AstalRiverRiver:outputs: (type GList(AstalRiverOutput))
*
* A list of AstalRiverOutput objects
*/
astal_river_river_properties[ASTAL_RIVER_RIVER_PROP_OUTPUTS] =
g_param_spec_pointer("outputs", "outputs", "a list of all outputs", G_PARAM_READABLE);
g_object_class_install_properties(object_class, ASTAL_RIVER_RIVER_N_PROPERTIES,
astal_river_river_properties);
/**
* AstalRiverRiver::output-added:
* @river: the object which received the signal.
* @output: the name of the added output
*
* This signal is emitted when a new output was connected
*/
astal_river_river_signals[ASTAL_RIVER_RIVER_SIGNAL_OUTPUT_ADDED] =
g_signal_new("output-added", G_TYPE_FROM_CLASS(class), G_SIGNAL_RUN_FIRST, 0, NULL, NULL,
NULL, G_TYPE_NONE, 1, G_TYPE_STRING);
/**
* AstalRiverRiver::output-removed:
* @river: the object which received the signal.
* @output: the name of the removed output
*
* This signal is emitted when a new output was disconnected
*/
astal_river_river_signals[ASTAL_RIVER_RIVER_SIGNAL_OUTPUT_REMOVED] =
g_signal_new("output-removed", G_TYPE_FROM_CLASS(class), G_SIGNAL_RUN_FIRST, 0, NULL, NULL,
NULL, G_TYPE_NONE, 1, G_TYPE_STRING);
astal_river_river_signals[ASTAL_RIVER_RIVER_SIGNAL_CHANGED] =
g_signal_new("changed", G_TYPE_FROM_CLASS(class), G_SIGNAL_RUN_FIRST, 0, NULL, NULL, NULL,
G_TYPE_NONE, 0);