GnomeShellGenericMonitor/README.md

167 lines
4.3 KiB
Markdown
Raw Normal View History

2020-03-30 10:45:26 +02:00
Introduction
------------
This GNOME Shell Extension aims to display information to center box. Using DBUS protocol, any application can add or remove text and icons in the upper bar, right after date & clock.
Installation
------------
Create a symbolic link from your _.local_ directory and enable extension
ln -s $PWD/generic-monitor@gnome-shell-extensions/ ~/.local/share/gnome-shell/extensions/
gnome-extensions enable generic-monitor@gnome-shell-extensions
Restart GNOME
DBUS protocol
-------------
All functions read JSON formatted parameters
notify():
{
"group": "groupname",
"items": [
{
2020-11-18 16:20:12 +01:00
"name" : "",
2020-11-25 10:21:44 +01:00
"box" : ["left"|"center"|"right"], // Optional : center by default
2020-11-18 16:20:12 +01:00
"text" : <text_object>, // Optional
"icon" : <icon_object>, // Optional
"popup" : <popup_object>, // Optional
<signals_description>, // Optional
2020-03-30 10:45:26 +02:00
}, ...
]
}
}
deleteItems():
{
"items": ["<itemName>@<groupName>", ...]
}
deleteGroups():
{
"groups": ["<groupName>", ...]
}
2020-11-18 16:20:12 +01:00
openPopup():
{
"item": "<itemName>@<groupName>"
}
closePopup():
{
"item": "<itemName>@<groupName>"
}
togglePopup():
{
"item": "<itemName>@<groupName>"
}
2020-03-30 10:45:26 +02:00
2020-11-18 16:20:12 +01:00
DBUS object
===========
<text_object> is defined as :
2020-11-25 10:21:44 +01:00
"text" : {
2021-01-18 15:53:32 +01:00
"name" : "" // Optional, used with popup nested element
<signals_description>, // Optional, used with popup nested element
2020-11-18 16:20:12 +01:00
"text" : "Text to be displayed",
"style" : "CSS style to be applied", // Optional
}
<icon_object> is defined as :
2020-11-25 10:21:44 +01:00
"icon" : {
2020-11-18 16:20:12 +01:00
"path" : "Icon path",
"style" : "CSS style to be applied", // Optional
}
<picture_object> is defined as :
2020-11-25 10:21:44 +01:00
"picture" : {
2021-01-18 15:53:32 +01:00
"name" : "" // Optional, used with popup nested element
<signals_description>, // Optional, used with popup nested element
2020-11-18 16:20:12 +01:00
"path" : "Icon path",
"width" : XXX, // Optional : Force width in pixels, can be -1 for defaut value
"height" : XXX, // Optional : Force height in pixels, can be -1 for defaut value
}
<popup_object is defuned as :
2020-11-25 10:21:44 +01:00
"popup" : {
2020-11-18 16:20:12 +01:00
"items": [<text_objects> and/or <picture_objects>]
}
Signals description
===================
Signals can be :
"on-click" : ["signal"|"delete"|"open-popup"|"close-popup"|"toggle-popup"]
"on-dblclick" : ["signal"|"delete"|"open-popup"|"close-popup"|"toggle-popup"]
"on-rightclick" : ["signal"|"delete"|"open-popup"|"close-popup"|"toggle-popup"]
"on-rightdblclick" : ["signal"|"delete"|"open-popup"|"close-popup"|"toggle-popup"]
2020-11-25 10:21:44 +01:00
"on-enter" : ["signal"|"delete"|"open-popup"|"close-popup"|"toggle-popup"]
"on-leave" : ["signal"|"delete"|"open-popup"|"close-popup"|"toggle-popup"]
"on-scroll" : ["signal"|"delete"|"open-popup"|"close-popup"|"toggle-popup"]
2020-11-18 16:20:12 +01:00
Targets :
* signal : emit a signal to desktop application
* delete : Delete item
* open-popup : Open the popup if there is one
* close-popup : Close the popup if there is one
* toggle-popup : Toggle (open/close) the popup if there is one
Signal names emit when action "signal" is specified :
2020-05-04 10:08:39 +02:00
* onClick
* onDblClick
2020-11-25 10:21:44 +01:00
* onRightClick
2020-05-04 10:08:39 +02:00
* onRightDblClick
* onEnter
* onLeave
2020-11-12 14:16:17 +01:00
* onScrollUp
* onScrollDown
2020-05-04 10:08:39 +02:00
2020-11-18 16:20:12 +01:00
Each signal is sent with one parameter : "<itemName>@<groupName>"
2021-01-18 15:53:32 +01:00
For popup nested elements, parameter is "<nestedName>@<itemName>@<groupName>"
where nestedName can be empty if not defined by user
2020-11-18 16:20:12 +01:00
Other signals are available when extension is activated/deactivated :
* onActivate
* onDeactivate
2020-05-04 10:08:39 +02:00
2020-03-30 10:45:26 +02:00
Example
-------
You can test it with command line :
2020-11-28 12:14:48 +01:00
gdbus call --session --dest org.gnome.Shell --object-path /com/soutade/GenericMonitor --method com.soutade.GenericMonitor.notify '{"group":"new","items":[{"name":"first","on-click":"toggle-popup","text":{"text":"Hello","style":"color:green"},"popup":{"items":[{"picture":{"path":"/tmp/cat2.jpg"}}]}}]}'
2020-03-30 10:45:26 +02:00
gdbus call --session --dest org.gnome.Shell --object-path /com/soutade/GenericMonitor --method com.soutade.GenericMonitor.deleteGroups '{"groups":["new"]}'
2020-11-25 10:21:44 +01:00
Python examples is available
2020-03-30 10:45:26 +02:00
Development
-----------
After doing code update, you can test it within a nested window. In other cases you have to restart GNOME.
dbus-run-session -- gnome-shell --nested [--wayland]
To see log & errors :
journalctl /usr/bin/gnome-shell
Licence
-------
GNU GPL 3