merge main

.github/ISSUE_TEMPLATE/1-bug.yaml

@@ -1,34 +1,12 @@
 name: Bug Report
-description: Something is not working right
+description: Something is not working as expected
 labels: ["bug"]
 body:
-  - type: checkboxes
-    attributes:
-      label: Already reported ? *
-      description: Before opening a new bug report, please take a moment to search through the current open and closed issues to check if it already exists.
-      options:
-      - label: I have searched the existing open and closed issues.
-        required: true
-
-  - type: dropdown
-    id: type
-    attributes:
-      label: Regression?
-      description: |
-        Regression means that something used to work but no longer does.
-      multiple: false
-      options:
-        - "Yes"
-        - "No"
-    validations:
-      required: true
-
   - type: textarea
-    id: sysinfo
     attributes:
       label: System Information
       description: |
-        Paste the output of `ignis systeminfo` here.
+        Paste the output of `ignis systeminfo` below.
 
       value: "
         ```
@@ -40,25 +18,22 @@ body:
       required: true
 
   - type: textarea
-    id: desc
     attributes:
       label: Description
-      description: "What went wrong?"
+      description: "Provide a clear and concise description of the issue you encountered"
     validations:
       required: true
 
   - type: textarea
-    id: repro
     attributes:
       label: How to reproduce
-      description: "How can someone else reproduce the issue?"
+      description: "List the steps to reproduce the issue. Be as detailed as possible to help replicate the problem"
     validations:
       required: true
 
   - type: textarea
-    id: logs
     attributes:
-      label: Logs, images, videos, config files, CSS/SCSS files
+      label: Additional Information
       description: |
-        Anything that can help. Please always ATTACH and not paste them.
-        The log file is stored in ``~/.ignis/ignis.log``
+        Anything that can help (Logs, Images, Videos, Configs, etc.). Please avoid pasting large text directly.
+        Logs can be found at `~/.ignis/ignis.log`.

.github/ISSUE_TEMPLATE/2-feature.yaml

@@ -1,18 +1,10 @@
 name: Feature Request
-description: I'd like to request additional functionality
+description: Suggest a new feature or improvement
 labels: ["enhancement"]
 body:
-  - type: markdown
-    attributes:
-      value: |
-        Before opening a new issue, take a moment to search through the current open ones.
-
-        ---
-
   - type: textarea
-    id: desc
     attributes:
-      label: Description
-      description: "Describe your idea"
+      label: Feature Description
+      description: "Clearly describe the feature or improvement you'd like to see"
     validations:
       required: true

.github/ISSUE_TEMPLATE/3-docs.yaml

@@ -1,18 +1,10 @@
 name: Documentation
-description: Improvements or additions to documentation
+description: Suggest improvements or additions to the documentation
 labels: ["documentation"]
 body:
-  - type: markdown
-    attributes:
-      value: |
-        Before opening a new issue, take a moment to search through the current open ones.
-
-        ---
-
   - type: textarea
-    id: desc
     attributes:
       label: Description
-      description: "Describe your idea"
+      description: "Clearly describe your suggestion for improving the documentation"
     validations:
       required: true

.github/ISSUE_TEMPLATE/4-question.yaml

@@ -2,15 +2,7 @@ name: Question
 description: I'd like to ask a question
 labels: ["question"]
 body:
-  - type: markdown
-    attributes:
-      value: |
-        Before opening a new issue, take a moment to search through the current open ones.
-
-        ---
-
   - type: textarea
-    id: desc
     attributes:
       label: Question
       description: "Describe your question"

.github/ISSUE_TEMPLATE/5-nix.yaml

@@ -0,0 +1,17 @@
+name: Nix/NixOS
+description: Related to the Nix package manager or NixOS
+labels: ["nix"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please note that I (linkfrg) don't maintain the Nix flake for Ignis, any help or pull request would be highly appreciated.
+
+        ---
+
+  - type: textarea
+    attributes:
+      label: Description
+      description: "Describe the issue"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/6-other.yaml

@@ -0,0 +1,9 @@
+name: Other
+description: Something else? if the options above do not suit
+body:
+  - type: textarea
+    attributes:
+      label: Description
+      description: "Provide a description of your issue"
+    validations:
+      required: true

README.md

@@ -5,15 +5,13 @@
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Linting: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
-<div align="center">
-<strong>A widget framework for building desktop shells, written and configurable in Python.</strong>
-</div>
+A widget framework for building desktop shells, written and configurable in Python.
 
-## Features
 - Configurable in Python
-- Uses GTK4
-- Batteries Included
-- Simplified work with widgets
+- Easy to use
+- GTK4-based
+- Batteries Included (a lot of built-in Services and Utilities!)
+- Flexible work with widgets
 
 > [!NOTE]
 > Ignis is mostly stable, but still a work in progress.
@@ -32,6 +30,12 @@ See the [Documentation](https://linkfrg.github.io/ignis)
 
 ...and all other compositors that implement the Layer Shell protocol.
 
+Ignis __is not supported__ on:
+- GNOME Wayland
+- X11
+
+...because they don't support the Layer Shell protocol.
+
 ## Examples
 * A simple bar, see [examples](./examples/bar)
 ![simple-bar](./examples/bar/simple-bar.png)
@@ -43,5 +47,4 @@ See the [Documentation](https://linkfrg.github.io/ignis)
 Check out the [Developer Guide](https://linkfrg.github.io/ignis/latest/dev/index.html)
 
 ## Special Thanks
-
 [AGS](https://github.com/aylur/ags) - for inspiration

docs/examples/code_snippets.rst

@@ -0,0 +1,61 @@
+Code Snippets
+==============
+
+This page provides useful code snippets to help you implement additional functionality. 
+
+Clicking outside of a window
+----------------------------
+
+A common use case is to close a window.
+
+.. code-block:: python
+
+    Widget.Window(
+        namespace="my-window",
+        anchor=["left", "right", "top", "bottom"],  # to make a window fullscreen
+        child=Widget.Overlay(
+            child=Widget.Button(
+                vexpand=True,
+                hexpand=True,
+                can_focus=False,
+                on_click=lambda x: CALLBACK, # e.g., app.close_window("my-window")
+            ),
+            overlays=[ACTUAL_CONTENT],
+        ),
+    )
+
+Replace ``ACTUAL_CONTENT`` with the actual widgets you want to put in the window.
+
+.. warning::
+    If ``ACTUAL_CONTENT`` fills all of the screen, 
+    set ``valign`` and ``halign`` with values other than ``fill`` (e.g., ``center``).
+
+
+Listen for key events
+----------------------
+
+Currently Ignis doesn't have a convenient API for this.
+But you can always use GTK directly.
+
+Use :class:`Gtk.EventControllerKey`:
+
+.. code-block:: python
+
+    from gi.repository import Gtk
+
+    def handle_key_press(
+        event_controller_key: Gtk.EventControllerKey,
+        keyval: int,
+        keycode: int,
+        state: Gdk.ModifierType,
+    ) -> None:
+        print(keyval)
+
+    key_controller = Gtk.EventControllerKey()
+    WIDGET.add_controller(key_controller)
+    # Listen for the pressed event
+    # Gtk.EventControllerKey has other signals, e.g., "key-released"
+    # Check out PyGObject docs for more info
+    key_controller.connect("key-pressed", handle_key_press)
+
+Replace ``WIDGET`` with the widget on which you want to listen for key events.

docs/examples/configurations.rst

@@ -0,0 +1,12 @@
+Configurations
+=================
+
+This page contains some configurations that you can use as an example.
+
+`A simple bar <https://github.com/linkfrg/ignis/tree/main/examples/bar>`_
+---------------------------------------------------------------------------------
+.. image:: https://github.com/linkfrg/ignis/blob/main/examples/bar/simple-bar.png?raw=true
+
+`My own configuration <https://github.com/linkfrg/dotfiles/>`_
+---------------------------------------------------------------------------------
+.. image:: https://github.com/linkfrg/dotfiles/blob/main/assets/1.png?raw=true

docs/examples/index.rst

@@ -1,10 +1,8 @@
 Examples
 =============
 
-`A simple bar <https://github.com/linkfrg/ignis/tree/main/examples/bar>`_
----------------------------------------------------------------------------------
-.. image:: https://github.com/linkfrg/ignis/blob/main/examples/bar/simple-bar.png?raw=true
+.. toctree::
+   :maxdepth: 1
 
-`My own configuration <https://github.com/linkfrg/dotfiles/>`_
----------------------------------------------------------------------------------
-.. image:: https://github.com/linkfrg/dotfiles/blob/main/assets/1.png?raw=true
+   configurations
+   code_snippets

docs/user/expanding_functionality.rst

@@ -2,7 +2,7 @@ Expanding functionality
 ========================
 
 Most of the features you need should be available in the `API Reference <../api/index.html>`_.
-owever, if the feature you are looking for is not there, this page may help you.
+However, if the feature you are looking for is not there, this page may help you.
 
 Since Ignis uses Python, you can take advantage of its many benefits, features, and modules to expand functionality, including the use of native PyGObject.
 

docs/user/first_widgets.rst

@@ -159,19 +159,14 @@ The solution is to create functions that return widget instances.
         return Widget.Window(
             namespace=f"some-window-{monitor}",  # the namespace must be unique
             monitor=monitor,
+            anchor=["left", "top", "right"],  # btw put this window in the top
             child=Widget.Box(
-                vertical=True,
                 spacing=10,
                 child=[
                     Widget.Label(label="Click buttons)))"),
-                    Widget.Box(
-                        spacing=26,
-                        child=[
-                            button1,
-                            button2,
-                            button3,
-                        ],
-                    ),
+                    button1,
+                    button2,
+                    button3,
                 ],
             ),
         )

docs/user/index.rst

@@ -13,6 +13,7 @@ Get started
 
    installation
    first_widgets
+   using_classes
    dynamic_content
    styling
    cli