RAGS

https://notashelf.github.io/rags
Admin
RAGS (raf's AGS) is a GJS library that provides a declarative way to define GTK 3 widgets with...
Tokens:761,932
Snippets:5,233
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Example of Installing and Notifying Properties - C

Source: https://notashelf.github.io/rags/classes/service_audio.Audio

Demonstrates how to install a property using g_param_spec_int and g_object_class_install_property, storing the GParamSpec in an array. It then shows how to use g_object_notify_by_pspec to signal a change to that property.

```c
typedef enum 
{
  PROP_FOO = 1,
  PROP_LAST
} MyObjectProperty;

static GParamSpec *properties[PROP_LAST];

static void 
my_object_class_init (MyObjectClass *klass)
{
  properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                     0, 100,
                                     50,
                                     G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
  g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
}

// ... later in code ...
g_object_notify_by_pspec (self, properties[PROP_FOO]);
```

--------------------------------

### Static Install Properties

Source: https://notashelf.github.io/rags/classes/widgets_box.Box

Installs an array of properties.

```APIDOC
## Static_install_properties

### Description
Installs an array of properties.

### Method
`install_properties`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pspecs** (ParamSpec<unknown>[]) - Required - An array of ParamSpec objects to install.

### Request Example
```json
{
  "pspecs": [
    "ParamSpec<unknown>"
  ]
}
```

### Response
#### Success Response (void)
This function does not return a value.

#### Response Example
None
```

--------------------------------

### C Example: Install and Notify Property

Source: https://notashelf.github.io/rags/classes/service_audio.Stream

Demonstrates how to install a property using GParamSpec and then notify changes to that property using g_object_notify_by_pspec. This pattern is efficient for notifying property updates from within the class.

```c
static GParamSpec *properties[PROP_LAST];

static void
my_object_class_init (MyObjectClass *klass)
{
  properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                             0, 100,
                                             50,
                                             G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
  g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
}

// ... later in code ...
g_object_notify_by_pspec (self, properties[PROP_FOO]);
```

--------------------------------

### C Example: Installing and Notifying Properties

Source: https://notashelf.github.io/rags/classes/service_mpris.Mpris

This C code snippet demonstrates how to install a property using `g_object_class_install_property` and then notify changes to that property using `g_object_notify_by_pspec`. It shows storing `GParamSpec` pointers in an array for efficient access.

```c
typedef enum {
    PROP_FOO = 1,
    PROP_LAST
} MyObjectProperty;

static GParamSpec *properties[PROP_LAST];

static void
my_object_class_init (MyObjectClass *klass)
{
    properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                             0, 100,
                                             50,
                                             G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
    g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
}

// To notify a change:
g_object_notify_by_pspec (self, properties[PROP_FOO]);
```

--------------------------------

### Property Installation

Source: https://notashelf.github.io/rags/classes/service_applications.Applications

Static functions for installing property specifications.

```APIDOC
## `Static`install_properties

### Description
Static function to install multiple property specifications.

### Method
`void`

### Endpoint
N/A (Static Method)

### Parameters
* **pspecs** (ParamSpec<unknown>[]) - Required - An array of property specifications to install.

### Response
#### Success Response (void)
Returns void.
```

```APIDOC
## `Static`install_property

### Description
Static function to install a single property specification.

### Method
`void`

### Endpoint
N/A (Static Method)

### Parameters
* **property_id** (number) - Required - The ID of the property.
* **pspec** (ParamSpec) - Required - The property specification to install.

### Response
#### Success Response (void)
Returns void.
```

--------------------------------

### Static Install Property

Source: https://notashelf.github.io/rags/classes/widgets_box.Box

Installs a single property.

```APIDOC
## Static_install_property

### Description
Installs a single property.

### Method
`install_property`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **property_id** (number) - Required - The ID of the property.
- **pspec** (ParamSpec) - Required - The ParamSpec object for the property.

### Request Example
```json
{
  "property_id": 0,
  "pspec": "ParamSpec"
}
```

### Response
#### Success Response (void)
This function does not return a value.

#### Response Example
None
```

--------------------------------

### GLib Object Class Initialization Example

Source: https://notashelf.github.io/rags/classes/service_battery.Battery

An example C code snippet demonstrating how to initialize a GLib object class, install properties, and store GParamSpec pointers for later use with `g_object_notify_by_pspec()`.

```c
#include <glib-object.h>

typedef enum {
    PROP_FOO = 1,
    PROP_LAST
} MyObjectProperty;

static GParamSpec *properties[PROP_LAST];

static void
my_object_class_init (MyObjectClass *klass)
{
    properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                         0, 100,
                                         50,
                                         G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
    g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
}

// Example usage within the class:
// g_object_notify_by_pspec (self, properties[PROP_FOO]);
```

--------------------------------

### Class and Property Initialization: _classInit, install_properties, install_property

Source: https://notashelf.github.io/rags/classes/service_notifications.Notification

These functions are related to the initialization and setup of classes and their properties. `_classInit` is likely called during class initialization, `install_properties` installs multiple property specifications, and `install_property` installs a single property specification. They are fundamental for defining the structure and behavior of objects in a type system.

```c
any _classInit(any klass);
void install_properties(ParamSpec<unknown>[] pspecs);
void install_property(int property_id, ParamSpec pspec);
```

--------------------------------

### GObject Static Property Installation (C)

Source: https://notashelf.github.io/rags/classes/service_greetd.Greetd

The `install_properties` static function installs an array of `ParamSpec` structures, effectively defining the properties for a GObject type. This is typically called during class initialization.

```c
static void
install_properties (GObjectClass *gobject_class, guint last_property)
{
  gobject_class->properties = g_malloc0 (sizeof (GParamSpec *) * (last_property + 1));

  gobject_class->properties[last_property] =
    g_param_spec_string (
      "my-property",
      "My Property",
      "Description of my property",
      "default value",
      G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);

  /* ... */
}
```

--------------------------------

### Install Properties (C)

Source: https://notashelf.github.io/rags/classes/service_audio.Audio

Static install_properties installs an array of property specifications. It takes an array of ParamSpec<unknown> as input and returns void.

```c
void install_properties (ParamSpec<unknown>[] pspecs)
```

--------------------------------

### Static Install Style Property

Source: https://notashelf.github.io/rags/classes/widgets_box.Box

Installs a style property.

```APIDOC
## Static_install_style_property

### Description
Installs a style property.

### Method
`install_style_property`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pspec** (ParamSpec) - Required - The ParamSpec object for the style property.

### Request Example
```json
{
  "pspec": "ParamSpec"
}
```

### Response
#### Success Response (void)
This function does not return a value.

#### Response Example
None
```

--------------------------------

### Creating a Widget using setup property

Source: https://notashelf.github.io/rags/documents/Widgets

Illustrates how to use the 'setup' property for incorporating imperative code directly within declarative widget definitions. This simplifies the structure for adding custom logic.

```javascript
const MyWidget = () =>
  Widget.Button({
    setup: (self) => {
      // imperative code
    },
  });
```

--------------------------------

### Install Style Property

Source: https://notashelf.github.io/rags/classes/widgets_calendar.Calendar

Installs a style property specification. It takes a pspec (ParamSpec) as input and returns void.

```GObject Introspection
install_style_property(pspec: ParamSpec): void
```

--------------------------------

### Static Install Child Properties

Source: https://notashelf.github.io/rags/classes/widgets_box.Box

Installs an array of child properties.

```APIDOC
## Static_install_child_properties

### Description
Installs an array of child properties.

### Method
`install_child_properties`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pspecs** (ParamSpec<unknown>[]) - Required - An array of ParamSpec objects to install.

### Request Example
```json
{
  "pspecs": [
    "ParamSpec<unknown>"
  ]
}
```

### Response
#### Success Response (void)
This function does not return a value.

#### Response Example
None
```

--------------------------------

### Property Installation

Source: https://notashelf.github.io/rags/classes/service_audio.Audio

Documentation for `install_properties` and `install_property` static methods used for installing property specifications.

```APIDOC
## `Static`install_properties

### Description
Installs multiple property specifications.

### Method
`install_properties(pspecs: ParamSpec<unknown>[])`

### Parameters
* **pspecs** (ParamSpec<unknown>[]) - Description

### Returns
`void`

---

## `Static`install_property

### Description
Installs a single property specification.

### Method
`install_property(property_id: number, pspec: ParamSpec)`

### Parameters
* **property_id** (number) - Description
* **pspec** (ParamSpec) - Description

### Returns
`void`
```

--------------------------------

### Install Multiple Properties

Source: https://notashelf.github.io/rags/classes/service_applications.Applications

The `install_properties` static method is used to install an array of `ParamSpec` objects. This is typically done during class initialization to define the properties of an object.

```javascript
static install_properties(pspecs) {
  // ... implementation ...
}
```

--------------------------------

### Install Properties: install_properties

Source: https://notashelf.github.io/rags/classes/service_hyprland.Hyprland

Static method to install multiple properties defined by `ParamSpec` objects.

```javascript
function install_properties(pspecs: ParamSpec<unknown>[]): void
```

--------------------------------

### Install GObject Properties

Source: https://notashelf.github.io/rags/classes/service_network.Wifi

Installs properties for a GObject. The `install_properties` method takes an array of ParamSpec objects, while `install_property` takes a property ID and a single ParamSpec. These are used to define and register properties with GObject.

```typescript
Service.install_properties(paramSpecsArray);
Service.install_property(propertyId, paramSpec);
```

--------------------------------

### Install Multiple GObject Properties

Source: https://notashelf.github.io/rags/classes/service_notifications.Notifications

Installs multiple GObject property specifications for a class. This function takes an array of ParamSpec structures and applies them to the class.

```c
void install_properties(ParamSpec **pspecs, unsigned int n_pspecs);
```

--------------------------------

### Static Install Child Property

Source: https://notashelf.github.io/rags/classes/widgets_box.Box

Installs a single child property.

```APIDOC
## Static_install_child_property

### Description
Installs a single child property.

### Method
`install_child_property`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **property_id** (number) - Required - The ID of the property.
- **pspec** (ParamSpec) - Required - The ParamSpec object for the property.

### Request Example
```json
{
  "property_id": 0,
  "pspec": "ParamSpec"
}
```

### Response
#### Success Response (void)
This function does not return a value.

#### Response Example
None
```

--------------------------------

### Install Single Property (C)

Source: https://notashelf.github.io/rags/classes/service_audio.Audio

Static install_property installs a single property specification. It takes a property_id (number) and a ParamSpec as input and returns void.

```c
void install_property (number property_id, ParamSpec pspec)
```

--------------------------------

### Static Single Property Installation (GObject)

Source: https://notashelf.github.io/rags/classes/service_applications.Application

The `install_property` static function installs a single `ParamSpec` for a given property ID. This is a more granular way to define properties compared to `install_properties`.

```c
static void
install_property (guint property_id, GParamSpec *pspec)
{
  // Logic to install a single property
}
```

--------------------------------

### Static Property Installation (GObject)

Source: https://notashelf.github.io/rags/classes/service_applications.Application

The `install_properties` static function installs an array of `ParamSpec` objects, effectively defining the properties for a type. This is typically called during class initialization.

```c
static void
install_properties (GParamSpec **pspecs, guint n_pspecs)
{
  // Logic to install properties
}
```

--------------------------------

### Start Authenticated Session

Source: https://notashelf.github.io/rags/classes/service_greetd.Greetd

Starts an authenticated session with the greetd service using the provided command and optional environment variables. Returns a Promise that resolves with the greetd Response.

```typescript
startSession(cmd: string | string[], env?: string[]): Promise<Response>;
```

--------------------------------

### Install Single Property

Source: https://notashelf.github.io/rags/classes/service_applications.Applications

The `install_property` static method installs a single property defined by its `property_id` and `ParamSpec`. This method is used to add properties to a class or object.

```javascript
static install_property(property_id, pspec) {
  // ... implementation ...
}
```

--------------------------------

### Build and Install RAGS from Source

Source: https://notashelf.github.io/rags/documents/Installation

This sequence of commands clones the RAGS repository, installs its Node.js dependencies, configures the build using Meson, and then installs the project. This method is suitable when Nix is not preferred or available.

```bash
git clone --recursive https://github.com/Aylur/ags.git
cd ags
npm install
meson setup build
meson install -C build
```

--------------------------------

### GObject Static Single Property Installation (C)

Source: https://notashelf.github.io/rags/classes/service_greetd.Greetd

The `install_property` static function installs a single `ParamSpec` for a given property ID. This is a more granular way to add properties compared to `install_properties` and is often used in conjunction with it.

```c
static void
install_property (GObjectClass *gobject_class, guint property_id, GParamSpec *pspec)
{
  gobject_class->properties[property_id] = pspec;
}
```

--------------------------------

### Greetd._init Method

Source: https://notashelf.github.io/rags/classes/service_greetd.Greetd

Initializes the Greetd service with provided arguments.

```APIDOC
## Greetd._init Method

### Description
Initializes the Greetd service with provided arguments.

### Method
METHOD

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **...args** (any[]) - Arguments to initialize the service.

### Request Example
```json
{
  "example": "_init(...args)"
}
```

### Response
#### Success Response (200)
- **void** - This method does not return a value.

#### Response Example
```json
{
  "example": "void"
}
```
```

--------------------------------

### Install RAGS using Nix Profile

Source: https://notashelf.github.io/rags/documents/Installation

This command installs the RAGS package directly into your Nix profile, making the 'ags' command available in your system's PATH. It's a convenient way to manage the installation without manual compilation.

```bash
nix profile install github:Aylur/ags
```

--------------------------------

### Install Properties (C)

Source: https://notashelf.github.io/rags/classes/service_network.Vpn

install_properties is a static method used to install multiple property specifications for a type. It takes an array of ParamSpec objects and returns void. This is typically called during class initialization.

```c
void install_properties (ParamSpec<unknown>[] pspecs);
```

--------------------------------

### Run RAGS without Installation using Nix

Source: https://notashelf.github.io/rags/documents/Installation

This command allows you to execute the 'ags' command directly from its GitHub repository without a formal installation. It's useful for testing or temporary usage.

```bash
nix run github:Aylur/ags
```

--------------------------------

### Install RAGS Dependencies from Source (Fedora)

Source: https://notashelf.github.io/rags/documents/Installation

This command installs the required development packages for building RAGS from source on a Fedora system using dnf. It lists dependencies such as typescript, npm, meson, and GTK/GObject related packages.

```bash
sudo dnf install typescript npm meson gjs-devel gtk3-devel gtk-layer-shell gnome-bluetooth upower NetworkManager pulseaudio-libs-devel libdbusmenu-gtk3 libsoup3
```

--------------------------------

### Get Ancestor Widget

Source: https://notashelf.github.io/rags/classes/widgets_separator.Separator

Gets the first ancestor of a widget that matches a given `widget_type`. For example, finding the first `GtkBox` ancestor. The returned widget is not referenced. Note that a widget is considered an ancestor of itself.

```c
Widget | null get_ancestor(GType widget_type);

```

--------------------------------

### Install RAGS Dependencies from Source (Ubuntu)

Source: https://notashelf.github.io/rags/documents/Installation

This command installs the necessary development packages for building RAGS from source on an Ubuntu system using apt. It includes dependencies like node-typescript, npm, meson, and various GTK, GObject, and Bluetooth libraries.

```bash
sudo apt install node-typescript npm meson libgjs-dev gjs libgtk-layer-shell-dev libgtk-3-dev libpulse-dev network-manager-dev libgnome-bluetooth-3.0-dev libdbusmenu-gtk3-dev libsoup-3.0-dev
```

--------------------------------

### _init Method

Source: https://notashelf.github.io/rags/classes/widgets_separator.Separator

Internal initialization method for widgets.

```APIDOC
## POST /_init

### Description
Performs internal initialization for the widget.

### Method
POST

### Endpoint
/_init

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **args** (any[]) - Variable number of arguments for initialization.

### Request Example
```json
{
  "args": ["arg1", 123, { "key": "value" }]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates completion of initialization.

#### Response Example
```json
{
  "status": "initialized"
}
```
```

--------------------------------

### Install RAGS Dependencies from Source (Arch Linux)

Source: https://notashelf.github.io/rags/documents/Installation

This command installs the necessary development packages for building RAGS from source on an Arch Linux system using pacman. It includes dependencies like typescript, npm, meson, and various GTK and GObject libraries.

```bash
sudo pacman -S typescript npm meson gjs gtk3 gtk-layer-shell gnome-bluetooth-3.0 upower networkmanager gobject-introspection libdbusmenu-gtk3 libsoup3
```

--------------------------------

### Greetd Login Example using JavaScript

Source: https://notashelf.github.io/rags/documents/Greetd

A JavaScript example demonstrating how to use the greetd service to create a login interface. It includes input fields for username and password, and handles the login process and potential errors.

```javascript
// /etc/greetd/greeter.js
const greetd = await Service.import("greetd");

const name = Widget.Entry({
  placeholder_text: "Username",
  on_accept: () => password.grab_focus(),
});

const password = Widget.Entry({
  placeholder_text: "Password",
  visibility: false,
  on_accept: () => {
    greetd.login(name.text || "", password.text || "", "Hyprland")
      .catch((err) => response.label = JSON.stringify(err));
  },
});

const response = Widget.Label();

const win = Widget.Window({
  css: "background-color: transparent;",
  anchor: ["top", "left", "right", "bottom"],
  keymode: "exclusive",
  child: Widget.Box({
    vertical: true,
    hpack: "center",
    vpack: "center",
    hexpand: true,
    vexpand: true,
    children: [
      name,
      password,
      response,
    ],
  }),
});

App.config({ windows: [win] });
```

--------------------------------

### Property Management

Source: https://notashelf.github.io/rags/classes/service_bluetooth.Bluetooth

Functions for getting, setting, and installing properties on objects.

```APIDOC
## vfunc_get_property

### Description
Provides a generic getter for all properties of an object type. Should be overridden for types with properties.

### Method
Virtual Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **property_id** (number) - Required - The ID of the property to get.
- **value** (any) - Required - The value to set for the property.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Request Example
N/A

### Response
#### Success Response (void)
Returns void.

#### Response Example
N/A

## vfunc_set_property

### Description
Provides a generic setter for all properties of an object type. Should be overridden for types with properties. The type system implicitly handles notification if not explicitly emitted.

### Method
Virtual Function

### Endpoint
N/A

### Parameters
#### Path Parameters
- **property_id** (number) - Required - The ID of the property to set.
- **value** (any) - Required - The value to set for the property.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Request Example
N/A

### Response
#### Success Response (void)
Returns void.

#### Response Example
N/A

## Static.find_property

### Description
Finds a property specification by its name.

### Method
Static Method

### Endpoint
N/A

### Parameters
#### Query Parameters
- **property_name** (string) - Required - The name of the property to find.

### Request Example
N/A

### Response
#### Success Response (ParamSpec)
Returns the ParamSpec for the found property.

#### Response Example
```json
{
  "example": "ParamSpec"
}
```

## Static.install_properties

### Description
Installs multiple property specifications for an object type.

### Method
Static Method

### Endpoint
N/A

### Parameters
#### Query Parameters
- **pspecs** (ParamSpec<unknown>[]) - Required - An array of property specifications to install.

### Request Example
N/A

### Response
#### Success Response (void)
Returns void.

#### Response Example
N/A

## Static.install_property

### Description
Installs a single property specification for an object type.

### Method
Static Method

### Endpoint
N/A

### Parameters
#### Query Parameters
- **property_id** (number) - Required - The ID of the property.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Request Example
N/A

### Response
#### Success Response (void)
Returns void.

#### Response Example
N/A

## Static.interface_find_property

### Description
Finds a property specification by name for a given interface.

### Method
Static Method

### Endpoint
N/A

### Parameters
#### Query Parameters
- **g_iface** (TypeInterface) - Required - The interface vtable.
- **property_name** (string) - Required - The name of the property to look up.

### Request Example
N/A

### Response
#### Success Response (ParamSpec)
Returns the ParamSpec for the found property.

#### Response Example
```json
{
  "example": "ParamSpec"
}
```
```

--------------------------------

### Greetd Constructor

Source: https://notashelf.github.io/rags/classes/service_greetd.Greetd

Initializes a new instance of the Greetd service.

```APIDOC
## Greetd Constructor

### Description
Initializes a new instance of the Greetd service.

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
None

### Request Example
```json
{
  "example": "new Greetd()"
}
```

### Response
#### Success Response (200)
- **Greetd** (Greetd) - A new instance of the Greetd service.

#### Response Example
```json
{
  "example": "Greetd instance"
}
```
```

--------------------------------

### Static Methods for Property and Style Management

Source: https://notashelf.github.io/rags/classes/widgets_separator.Separator

Provides documentation for static methods related to class initialization, property installation, and style property management.

```APIDOC
## Static Methods for Property and Style Management

### Description
This section details static methods for initializing classes, binding template callbacks and children, controlling compatibility, finding properties, and installing properties and style properties.

### Methods

#### `Static`_classInit

##### Description
Initializes a class.

##### Parameters
- **klass** (any) - The class to initialize.

##### Returns
any

#### `Static`bind_template_callback_full

##### Description
Binds a callback to a template.

##### Parameters
- **callback_name** (string) - The name of the callback.
- **callback_symbol** (Callback) - The callback symbol.

##### Returns
void

#### `Static`bind_template_child_full

##### Description
Binds a child to a template.

##### Parameters
- **name** (string) - The name of the child.
- **internal_child** (boolean) - Whether the child is internal.
- **struct_offset** (number) - The offset of the struct.

##### Returns
void

#### `Static`compat_control

##### Description
Controls compatibility settings.

##### Parameters
- **what** (number) - The compatibility setting to control.
- **data** (any) - Optional data for compatibility control.

##### Returns
number

#### `Static`find_property

##### Description
Finds a property by its name.

##### Parameters
- **property_name** (string) - The name of the property to find.

##### Returns
ParamSpec

#### `Static`find_style_property

##### Description
Finds a style property by its name.

##### Parameters
- **property_name** (string) - The name of the style property to find.

##### Returns
ParamSpec

#### `Static`install_properties

##### Description
Installs multiple properties for a class.

##### Parameters
- **pspecs** (ParamSpec<unknown>[]) - An array of ParamSpec objects to install.

##### Returns
void

#### `Static`install_property

##### Description
Installs a single property for a class.

##### Parameters
- **property_id** (number) - The ID of the property.
- **pspec** (ParamSpec) - The ParamSpec object for the property.

##### Returns
void

#### `Static`install_style_property

##### Description
Installs a style property.

##### Parameters
- **pspec** (ParamSpec) - The ParamSpec object for the style property.

##### Returns
void
```

--------------------------------

### Install RAGS Permanently on NixOS

Source: https://notashelf.github.io/rags/documents/Installation

This Nix code snippet demonstrates how to add RAGS as a flake input and include its package in your NixOS system configuration. This ensures RAGS is available system-wide after a NixOS rebuild.

```nix
{inputs,
 pkgs,
 ...
}:
let  
  ragsPkg = inputs.rags.packages.${pkgs.hostPlatform.system}.ags;  
in {
  environment.systemPackages = [ragsPkg];
}
```

--------------------------------

### Show Widget Immediately

Source: https://notashelf.github.io/rags/classes/widgets_separator.Separator

Shows a widget immediately, potentially entering the main loop for toplevel windows.

```APIDOC
## POST /widgets/show_now

### Description
Shows a widget immediately. If the widget is an unmapped toplevel window, this function will enter the main loop and wait for the window to be mapped. Use with caution as this can lead to unexpected behavior.

### Method
POST

### Endpoint
/widgets/show_now

### Parameters
No parameters required for this action.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Widget shown immediately"
}
```
```

--------------------------------

### Property Management Functions

Source: https://notashelf.github.io/rags/classes/service_mpris.Mpris

Functions for managing properties of objects, including getting, setting, and installing properties.

```APIDOC
## vfunc_get_property

### Description
The generic getter for all properties of this type. Should be overridden for every type with properties.

### Method
`vfunc_get_property`

### Parameters
#### Path Parameters
- **property_id** (number) - Required - The ID of the property to get.
- **value** (any) - Required - The current value of the property.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Returns void

## vfunc_set_property

### Description
The generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of `set_property` don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time.

### Method
`vfunc_set_property`

### Parameters
#### Path Parameters
- **property_id** (number) - Required - The ID of the property to set.
- **value** (any) - Required - The new value for the property.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Returns void

## vfunc_install_properties

### Description
Installs multiple property specifications.

### Method
`install_properties`

### Parameters
#### Path Parameters
- **pspecs** (ParamSpec<unknown>[]) - Required - An array of parameter specifications to install.

### Returns void

## vfunc_install_property

### Description
Installs a single property specification.

### Method
`install_property`

### Parameters
#### Path Parameters
- **property_id** (number) - Required - The ID of the property to install.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Returns void
```

--------------------------------

### Property Management Functions

Source: https://notashelf.github.io/rags/classes/service_hyprland.ActiveID

Functions for managing properties of objects, including getting, setting, and installing properties.

```APIDOC
## vfunc_get_property /api/vfunc_get_property

### Description
The generic getter for all properties of this type. Should be overridden for every type with properties.

### Method
(Not specified, likely internal)

### Endpoint
(Not specified, likely internal)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **property_id** (number) - Required - The ID of the property to get.
- **value** (any) - Required - The value to set for the property.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Request Example
```json
{
  "property_id": 1,
  "value": "some_value",
  "pspec": {}
}
```

### Response
#### Success Response (200)
- **void** - This function does not return a value.

#### Response Example
(No specific example, as it returns void)

## vfunc_set_property /api/vfunc_set_property

### Description
The generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of `set_property` don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time.

### Method
(Not specified, likely internal)

### Endpoint
(Not specified, likely internal)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **property_id** (number) - Required - The ID of the property to set.
- **value** (any) - Required - The value to set for the property.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Request Example
```json
{
  "property_id": 1,
  "value": "new_value",
  "pspec": {}
}
```

### Response
#### Success Response (200)
- **void** - This function does not return a value.

#### Response Example
(No specific example, as it returns void)

## install_properties /api/install_properties

### Description
Installs multiple properties for a type.

### Method
(Not specified, likely internal)

### Endpoint
(Not specified, likely internal)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **pspecs** (Array<ParamSpec<unknown>>) - Required - An array of parameter specifications to install.

### Request Example
```json
{
  "pspecs": [
    { "name": "prop1", "type": "string" },
    { "name": "prop2", "type": "number" }
  ]
}
```

### Response
#### Success Response (200)
- **void** - This function does not return a value.

#### Response Example
(No specific example, as it returns void)

## install_property /api/install_property

### Description
Installs a single property for a type.

### Method
(Not specified, likely internal)

### Endpoint
(Not specified, likely internal)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **property_id** (number) - Required - The ID of the property to install.
- **pspec** (ParamSpec) - Required - The parameter specification for the property.

### Request Example
```json
{
  "property_id": 1,
  "pspec": { "name": "my_property", "type": "boolean" }
}
```

### Response
#### Success Response (200)
- **void** - This function does not return a value.

#### Response Example
(No specific example, as it returns void)

## interface_find_property /api/interface_find_property

### Description
Find the #GParamSpec with the given name for an interface. Generally, the interface vtable passed in as `g_iface` will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().

### Method
(Not specified, likely internal)

### Endpoint
(Not specified, likely internal)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **g_iface** (TypeInterface) - Required - Any interface vtable for the interface, or the default vtable for the interface.
- **property_name** (string) - Required - Name of a property to look up.

### Request Example
```json
{
  "g_iface": "some_interface_vtable",
  "property_name": "interface_prop"
}
```

### Response
#### Success Response (200)
- **ParamSpec** - The parameter specification for the found property.

#### Response Example
```json
{
  "name": "interface_prop",
  "type": "string"
}
```

## interface_install_property /api/interface_install_property

### Description
Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property. This function is meant to be called from the interface's default vtable initialization function (the `class_init` member of #GTypeInfo.) It must not be called after after `class_init` has been called for any object types implementing this interface. If `pspec` is a floating reference, it will be consumed.

### Method
(Not specified, likely internal)

### Endpoint
(Not specified, likely internal)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **g_iface** (TypeInterface) - Required - The interface vtable.
- **pspec** (ParamSpec) - Required - The parameter specification for the property to install.

### Request Example
```json
{
  "g_iface": "some_interface_vtable",
  "pspec": { "name": "new_interface_prop", "type": "integer" }
}
```

### Response
#### Success Response (200)
- **void** - This function does not return a value.

#### Response Example
(No specific example, as it returns void)
```

--------------------------------

### Class Initialization (C)

Source: https://notashelf.github.io/rags/classes/service_network.Vpn

The _classInit static method is used for class initialization. It takes a klass parameter and returns any. This is a common pattern for setting up class-level properties or methods.

```c
any _classInit (any klass);
```

--------------------------------

### DBusProxy Method: Get Name

Source: https://notashelf.github.io/rags/interfaces/dbus_types.PlayerProxy

Retrieves the unique name of the D-Bus service that this proxy is connected to. This name usually starts with 'org.' or ':'.

```typescript
get_name(): string | null;
```

--------------------------------

### Static GObject Initialization and Property Lookup

Source: https://notashelf.github.io/rags/classes/service_network.Wifi

Contains static methods for class initialization and property lookup. `_classInit` is called during class initialization, and `find_property` retrieves a `ParamSpec` for a given property name.

```javascript
/**
 * @param klass
 * @returns any
 */
static _classInit(klass: any): any;

/**
 * @param what
 * @param Optional data
 * @returns number
 */
static compat_control(what: number, data?: any): number;

/**
 * @param property_name
 * @returns ParamSpec
 */
static find_property(property_name: string): ParamSpec;
```

--------------------------------

### Static Class Initialization and Compatibility Control

Source: https://notashelf.github.io/rags/classes/service_systemtray.SystemTray

These static methods handle class-level initialization and compatibility controls. `_classInit` is likely for setting up class-specific data or methods, while `compat_control` manages compatibility features based on a given 'what' identifier.

```javascript
/**
 * _classInit(klass: any): any
 * @param {any} klass
 * @returns {any}
 */

/**
 * compat_control(what: number, data?: any): number
 * @param {number} what
 * @param {any} [data]
 * @returns {number}
 */
```

--------------------------------

### C Object Property Notification Example

Source: https://notashelf.github.io/rags/classes/service_applications.Application

Illustrates how to use `g_object_notify_by_pspec` in C to emit a notification signal for a property change. It shows the setup of `GParamSpec` and its usage within an object's class initialization.

```c
typedef enum {
    PROP_FOO = 1,
    PROP_LAST
} MyObjectProperty;

static GParamSpec *properties[PROP_LAST];

static void
my_object_class_init (MyObjectClass *klass)
{
    properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                             0, 100,
                                             50,
                                             G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
    g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
}

// ... later in a method ...
g_object_notify_by_pspec (self, properties[PROP_FOO]);
```

--------------------------------

### Display RAGS Help Information

Source: https://notashelf.github.io/rags/documents/Installation

This command invokes the RAGS executable with the '--help' flag, displaying a list of available commands, options, and their descriptions. It's the standard way to understand the functionality of the 'ags' command-line tool.

```bash
ags --help
```

--------------------------------

### GObject Static Class Initialization (C)

Source: https://notashelf.github.io/rags/classes/service_greetd.Greetd

The `_classInit` static function is part of the GObject class initialization process. It receives the class structure as an argument and is used to set up class-wide data or methods.

```c
static void
_classInit (gpointer klass, gpointer data)
{
  GObjectClass *gobject_class = klass;

  gobject_class->constructed = constructed;
  gobject_class->dispose = dispose;
  gobject_class->finalize = finalize;
  gobject_class->get_property = get_property;
  gobject_class->set_property = set_property;
  gobject_class->dispatch_properties_changed = dispatch_properties_changed;
  gobject_class->notify = notify;
}
```

--------------------------------

### Create a Gtk CenterBox Layout

Source: https://notashelf.github.io/rags/documents/Widgets

Shows how to create a Gtk CenterBox widget, which is a type of Box used for arranging widgets in start, center, and end positions. The example demonstrates setting spacing, orientation, and assigning child widgets to each position.

```javascript
const centerBox = Widget.CenterBox({
  spacing: 8,
  vertical: false,
  startWidget: Widget.Label("left widget"),
  centerWidget: Widget.Label("center widget"),
  endWidget: Widget.Label("right widget"),
});
```

--------------------------------

### System Tray Widget Example (JavaScript)

Source: https://notashelf.github.io/rags/documents/System_Tray

This example demonstrates how to create a widget that displays system tray items. It imports the system tray service, defines a `SysTrayItem` component for individual items, and binds the widget's children to the system tray's items property. It handles primary and secondary clicks for activation and menu opening.

```javascript
const systemtray = await Service.import("systemtray");  
  
/** @param {import('types/service/systemtray').TrayItem} item */  
const SysTrayItem = (item) =>  
  Widget.Button({
    child: Widget.Icon().bind("icon", item, "icon"),  
    tooltipMarkup: item.bind("tooltip_markup"),  
    onPrimaryClick: (_, event) => item.activate(event),  
    onSecondaryClick: (_, event) => item.openMenu(event),  
  });  
  
const sysTray = Widget.Box({
  children: systemtray.bind("items").as((i) => i.map(SysTrayItem)),  
});
```

--------------------------------

### Hyprland Active Property Binding Example

Source: https://notashelf.github.io/rags/documents/Hyprland

Demonstrates how to bind and hook into Hyprland's 'active' property and its sub-properties (monitor, workspace, client) using a Widget setup. This allows for dynamic updates in UI elements based on changes in the Hyprland state.

```javascript
const widget = Widget({
  setup: (self) =>
    self
      .hook(hyprland, (self) => {}) 
      .hook(hyprland.active, (self) => {}) 
      .hook(hyprland.active.monitor, (self) => {}) 
      .hook(hyprland.active.workspace, (self) => {}) 
      .hook(hyprland.active.client, (self) => {}) 
      .bind("prop", hyprland, "active", (active) => {}) 
      .bind("prop", hyprland.active, "monitor", (monitor) => {}) 
      .bind("prop", hyprland.active, "workspace", (ws) => {}) 
      .bind("prop", hyprland.active, "client", (client) => {}) 
      .bind("prop", hyprland.active.monitor, "id", (id) => {}) 
      .bind("prop", hyprland.active.workspace, "id", (id) => {}) 
      .bind("prop", hyprland.active.client, "address", (address) => {}),
});
```

--------------------------------

### Install Multiple Properties

Source: https://notashelf.github.io/rags/classes/service.default

Installs an array of property specifications. This is a static utility function for batch property installation.

```c
void install_properties(ParamSpec<unknown>[] pspecs) {
  // Implementation details...
}
```

--------------------------------

### init_async (Promise Version)

Source: https://notashelf.github.io/rags/interfaces/dbus_types.PlayerProxy

Starts asynchronous initialization of the object. This method is intended for language bindings and returns a Promise that resolves to a boolean indicating success.

```APIDOC
## POST /websites/notashelf_github_io_rags/init_async

### Description
Starts asynchronous initialization of the object implementing the interface. This must be done before any real use of the object after initial construction. If the object also implements #GInitable you can optionally call g_initable_init() instead.

### Method
POST

### Endpoint
/websites/notashelf_github_io_rags/init_async

### Parameters
#### Query Parameters
- **io_priority** (number) - Required - the I/O priority of the operation
- **cancellable** (Cancellable | null) - Optional - optional #GCancellable object, %NULL to ignore.

### Response
#### Success Response (200)
- **result** (boolean) - Indicates if the initialization was successful.

#### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### login

Source: https://notashelf.github.io/rags/classes/service_greetd.Greetd

Performs a complete login flow, including session creation, authentication, and session startup. Supports custom environment variables.

```APIDOC
## POST /login

### Description
Performs a complete login flow, including session creation, authentication, and session startup. Supports custom environment variables.

### Method
POST

### Endpoint
/login

### Parameters
#### Request Body
- **username** (string) - Required - The user to log in as
- **password** (string) - Required - The authentication password
- **cmd** (string | string[]) - Required - Command to start (string is shell-parsed, array used directly)
- **env** (string[]) - Optional - Optional environment variables for the session

### Request Example
```json
{
  "username": "testuser",
  "password": "password123",
  "cmd": "/bin/bash",
  "env": ["VAR1=value1", "VAR2=value2"]
}
```

### Response
#### Success Response (200)
- **void** - Indicates successful login and session establishment.
```

--------------------------------

### Set Widget Start Margin

Source: https://notashelf.github.io/rags/classes/widgets_box.Box

Sets the start margin for a widget. This property defines the spacing at the logical start of the widget. The margin size is provided as a numerical value.

```c
void gtk_widget_set_margin_start (GtkWidget *widget, gint margin);
```

--------------------------------

### List All Properties

Source: https://notashelf.github.io/rags/classes/service_bluetooth.BluetoothDevice

Lists all available properties.

```APIDOC
## GET /gobject/list_properties

### Description
Lists all available GObject properties.

### Method
GET

### Endpoint
/gobject/list_properties

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **ParamSpec<unknown>[]** - An array of GParamSpec objects for all properties.

#### Response Example
```json
[
  { "name": "property1", "type": "string", "access": "rw" },
  { "name": "property2", "type": "number", "access": "r" }
]
```
```

--------------------------------

### Create a Circular Progress Bar

Source: https://notashelf.github.io/rags/documents/Widgets

Illustrates the creation of a CircularProgress widget, which displays progress in a circular form. The example shows how to style the widget using CSS, set its start and end points, define rounded ends, and bind its value to a dynamic source like battery percentage. It also shows how to embed another widget, like an icon, within the progress bar.

```javascript
const progress = Widget.CircularProgress({
  css: "min-width: 50px;" + // its size is min(min-height, min-width)  
    "min-height: 50px;" +  
    "font-size: 6px;" + // to set its thickness set font-size on it  
    "margin: 4px;" + // you can set margin on it  
    "background-color: #131313;" + // set its bg color  
    "color: aqua;", // set its fg color  
  rounded: false,
  inverted: false,
  startAt: 0.75,
  value: battery.bind("percent").as((p) => p / 100),
  child: Widget.Icon({
    icon: battery.bind("icon-name"),
  }),
});
```
Tokens:
Raw