Skip to content

Commit

Permalink
Documentation updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@Eeems
Eeems committed Feb 7, 2024
1 parent 850cf0a commit aa17ea1
Show file tree
Hide file tree
Showing 6 changed files with 125 additions and 230 deletions.
1 change: 1 addition & 0 deletions web/src/documentation/01_usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,7 @@ ____
system
screen
notification
compositor
name Signal to listen to.
arguments Arguments to pass to the method using the following format: <QVariant>:<Value>. e.g. QString:Test
Expand Down
11 changes: 11 additions & 0 deletions web/src/documentation/02_oxide-utils.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@ update-desktop-database

https://man.archlinux.org/man/update-desktop-database.1.en

xclip
=====

https://man.archlinux.org/man/xclip.1.en

xdg-desktop-menu
================

Expand Down Expand Up @@ -77,3 +82,9 @@ Example usage:
EV_SYN SYN_MT_REPORT
EV_SYN SYN_REPORT
EOF
fbinfo
======
This application will output information about the framebuffer in a human readable format.
312 changes: 113 additions & 199 deletions web/src/documentation/03_application_registration_format.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,204 +34,118 @@ Below is an example file:
Properties
==========

+------------------+--------------+----------+-----------------------+
| Property | Type | Required | Description |
+==================+==============+==========+=======================+
| bin | string | Yes | The path to the |
| | | | application. If |
| | | | this file doesn't |
| | | | exist, the |
| | | | application will |
| | | | not be registered. |
+------------------+--------------+----------+-----------------------+
| type | string | Yes | The type of |
| | | | application this |
| | | | is. |
| | | | |
| | | | ``"background"``: |
| | | | This application |
| | | | runs in the |
| | | | background and |
| | | | does not display |
| | | | anything on the |
| | | | screen. |
| | | | |
| | | | ``"foreground"``: |
| | | | This application |
| | | | runs in the |
| | | | foreground and |
| | | | must be paused |
| | | | when it's not the |
| | | | active |
| | | | application. |
| | | | |
| | | | ``"backgroundable"``: |
| | | | This application |
| | | | runs in both the |
| | | | foreground and the |
| | | | background and |
| | | | supports being |
| | | | notified with |
| | | | ``SIGUSR1`` and |
| | | | ``SIGUSR2`` when |
| | | | being swapped |
| | | | between the two |
| | | | states by the |
| | | | user. |
+------------------+--------------+----------+-----------------------+
| flags | string array | No | An array of flags |
| | | | for the |
| | | | application. |
| | | | |
| | | | ``"hidden"``: |
| | | | Do not display |
| | | | this application |
| | | | to the |
| | | | user. |
| | | | |
| | | | ``"autoStart"``: |
| | | | Start this |
| | | | application |
| | | | automatically when |
| | | | tarnish starts up. |
| | | | Should only be |
| | | | used on |
| | | | applications with |
| | | | a type of |
| | | | ``"backgroundable"`` |
| | | | or |
| | | | ``"background"``. |
| | | | |
| | | | ``"chroot"``: |
| | | | Run this |
| | | | application in a |
| | | | chroot. |
| | | | |
| | | | ``"system"``: |
| | | | This is a system |
| | | | application and |
| | | | cannot be removed |
| | | | by the user. This |
| | | | is set by default |
| | | | as applications |
| | | | using an |
| | | | application |
| | | | registration file |
| | | | are intended to be |
| | | | removed by a |
| | | | package manager. |
+------------------+--------------+----------+-----------------------+
| displayName | string | No | The human readable |
| | | | name to display to |
| | | | the user. |
+------------------+--------------+----------+-----------------------+
| description | string | No | Description of the |
| | | | app meant to be |
| | | | displayed to the |
| | | | user. |
+------------------+--------------+----------+-----------------------+
| icon | string | No | Path to an image |
| | | | file to use as the |
| | | | icon for this |
| | | | application. Or an |
| | | | icon spec. |
+------------------+--------------+----------+-----------------------+
| splash | string | No | Path to an image |
| | | | file to use as the |
| | | | splash screen for |
| | | | this application. Or |
| | | | an icon spec. |
+------------------+--------------+----------+-----------------------+
| user | string | No | User to run this |
| | | | application as. |
| | | | Default is |
| | | | ``root``. |
+------------------+--------------+----------+-----------------------+
| group | string | No | Group to run this |
| | | | application in. |
| | | | Default is |
| | | | ``root``. |
+------------------+--------------+----------+-----------------------+
| workingDirectory | string | No | Directory to set |
| | | | as the current |
| | | | working directory |
| | | | of the |
| | | | application. |
| | | | Default is ``/``. |
+------------------+--------------+----------+-----------------------+
| directories | string array | No | When an |
| | | | application is |
| | | | running in a |
| | | | chroot, also map |
| | | | these directories |
| | | | into the chroot |
| | | | with read/write |
| | | | privileges. |
+------------------+--------------+----------+-----------------------+
| permissions | string array | No | API permissions to |
| | | | grant this |
| | | | application. |
| | | | Without these, any |
| | | | calls to the API |
| | | | will be refused or |
| | | | return incorrect |
| | | | results. |
| | | | |
| | | | ``"permissions"``: |
| | | | Application can |
| | | | modify |
| | | | applications |
| | | | se |
| | | | ttings/permissions |
| | | | in the Apps API. |
| | | | |
| | | | ``"apps"``: |
| | | | Apps API |
| | | | access |
| | | | |
| | | | ``"notification"``: |
| | | | Notification API |
| | | | access |
| | | | |
| | | | ``"power"``: |
| | | | Power API |
| | | | access |
| | | | |
| | | | ``"screen"``: |
| | | | Screen API |
| | | | access |
| | | | |
| | | | ``"system"``: |
| | | | System API |
| | | | access |
| | | | |
| | | | ``"wifi"``: |
| | | | Wifi API access |
+------------------+--------------+----------+-----------------------+
| environment | string map | No | Extra environment |
| | | | variables to set |
| | | | before running the |
| | | | application. |
+------------------+--------------+----------+-----------------------+
| events | string map | No | Custom commands to |
| | | | run on an |
| | | | event. |
| | | | |
| | | | ``"resume"``: |
| | | | Run when the |
| | | | application is |
| | | | resumed |
| | | | |
| | | | ``"pause"``: |
| | | | Run when the |
| | | | application is |
| | | | pause |
| | | | |
| | | | ``"stop"``: |
| | | | Run when the |
| | | | application is |
| | | | stopped |
+------------------+--------------+----------+-----------------------+
bin
---
Required string

The path to the application. If this file doesn't exist, the application will not be registered.

type
----
Required string

The type of application this is.

- ``"background"``: This application runs in the background and does not display anything on the screen.
- ``"foreground"``: This application runs in the foreground and must be paused when it's not the active application.
- ``"backgroundable"``: This application runs in both the foreground and the background and supports being notified with ``SIGUSR1`` and ``SIGUSR2`` when being swapped between the two states by the user.

flags
-----
Optional string array

An array of flags for the application.

- ``"hidden"``: Do not display this application to the user.
- ``"autoStart"``: Start this application automatically when tarnish starts up. Should only be used on applications with a type of ``"backgroundable"`` or ``"background"``.
- ``"system"``: This is a system application and cannot be removed by the user. This is set by default as applications using an application registration file are intended to be removed by a package manager.
- ``"nopreload"``: Do not automatically add any of the preload libraries to ``LD_PRELOAD`` when running this application.
- ``"nopreload.compositor"``: Do not automatically add ``libblight_client.so`` to ``LD_PRELOAD`` when running this application.
- ``"nopreload.sysfs"``: Do not automatically add ``libsysfs_preload.so`` to ``LD_PRELOAD`` when running this application.
- ``"exclusive"``: Application is to be run in exclusive mode. This means that the compositor will not be sending input to the application, or handling displaying anything to the screen while this application is in the foreground.

displayName
-----------

Optional string

The human readable name to display to the user.

description
-----------

Optional string

Description of the app meant to be displayed to the user.

icon
----

Optional string

Path to an image file to use as the icon for this application, or an :ref:`icon-spec`.

user
----

Optional string

User to run this application as.

Default is ``root``.

group
-----

Optional string

Group to run this application in.

Default is ``root``.

workingDirectory
----------------

Optional string

Directory to set as the current working directory of the application.

Default is ``/``.

permissions
-----------

Optional string array

API permissions to grant this application. Without these, any calls to the API will be refused or return incorrect results.

- ``"permissions"``: Application can modify applications settings/permissions in the Apps API.
- ``"apps"``: Apps API access
- ``"notification"``: Notification API access
- ``"power"``: Power API access
- ``"screen"``: Screen API access
- ``"system"``: System API access
- ``"wifi"``: Wifi API access

environment
-----------

Optional string map

Extra environment variables to set before running the application.

events
------

Optional string map

Custom commands to run on an event.

- ``"resume"``: Run when the application is resumed
- ``"pause"``: Run when the application is pause
- ``"stop"``: Run when the application is stopped

.. _icon-spec:

Icon Spec
=========
Expand All @@ -240,7 +154,7 @@ Icon specifications can be in the following format: ``[theme:][context:]{name}-{

Some examples:

- ``oxide:splash:xochitl-702``
- ``oxide:splash:oxide-702``
- ``oxide:apps:xochitl-48``
- ``oxide:xochitl-48``
- ``xochitl-48``
Expand Down
8 changes: 0 additions & 8 deletions web/src/documentation/api/02_apps.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -255,21 +255,13 @@ Application Object
| | | directory for the |
| | | application. |
+----------------------+----------------------+----------------------+
| chroot | ``BOOLEAN`` property | If this application |
| | (read) | should be run in a |
| | | chroot or not. |
+----------------------+----------------------+----------------------+
| user | ``STRING`` property | User the application |
| | (read) | will be run as. |
+----------------------+----------------------+----------------------+
| group | ``STRING`` property | Group the |
| | (read) | application will be |
| | | run as. |
+----------------------+----------------------+----------------------+
| directories | ``ARRAY STRING`` | Directories mapped |
| | property | into the chroot as |
| | (read/write) | read/write. |
+----------------------+----------------------+----------------------+
| launched | signal | Signal sent when the |
| | | application starts. |
+----------------------+----------------------+----------------------+
Expand Down
Loading

0 comments on commit aa17ea1

Please sign in to comment.