agism: (D-Bus) API for GNOME Input Source Manager

NAME

agism - (D-Bus) API for GNOME Input Source Manager

SYNOPSIS

# Bus type: session
# Bus name: org.gnome.Shell
# (gdbus notation used below)
node /org/gnome/Shell/Extensions/Agism {
    interface io.sourceforge.Agism {
        methods:
            GetInputSources(out a(ussss) result);
            GetCurrentSource(out (ussss) result);
            ActivateInputSource(in u index, in b interactive, in s bell, out b result);
        signals:
        properties:
            readonly a(ussss) InputSources;
            readonly (ussss) CurrentSource;
      };
};

DESCRIPTION

Agism is a GNOME Shell extension providing a D-Bus API for the GNOME Input Source Manager. It allows 3-rd party applications to enumerate and activate input sources in a GNOME session.

Note: When the user locks the screen, the GNOME Shell disables all the extensions. When the user unlocks the screen, Agism is disabled and cannot activate input sources. If at the moment the input source is not the one required for typing the password, then the user may be in a trouble due to the inability to enter the password. To avoid this problem, Agism activates the first input source before turning off, so make sure the first input source is the one you use to type passwords.

Input source structure

An input source is described by a structure with signature (ussss), which includes:

Zero-based input source index (the first input source has index 0, the second — 1, etc).
Id. TODO
Short input source name, like "En" or "Ru".
Long input source name (aka display name), like "English (US)" or "Russian (typewriter)".
Input source type, "xkb" or "ibus".

‘`ActivateInputSource`’ method

Input source to activate is specified by zero-based index (the first input source has index 0, the second — 1, etc). If interactive is true, GNOME Input Source Manager will update the list of most recently used input sources. If bell is non-empty, the sound with the given name from the current theme will be played.

The method returns true if input source with the given index exists, and false otherwise.

‘`GetCurrentSource`’ method

The method returns value of ‘CurrentSource’ property.

‘`GetInputSources`’ method

The method returns value of ‘InputSources’ property.

‘`CurrentSource`’ property

Read only. Value is input source structure, describing the current input source. When the property is changed, Agism sends ‘org.freedesktop.DBus.Properties.PropertiesChanged’ signal.

‘`InputSources`’ property

Read only. Value is array of input sources structures, describing all input sources. When the property is changed, Agism sends ‘org.freedesktop.DBus.Properties.PropertiesChanged’ signal.

EXAMPLES

List all input sources:

$ gdbus call -e -d org.gnome.Shell \
    -o /org/gnome/Shell/Extensions/Agism \
    -m io.sourceforge.Agism.GetInputSources
([(uint32 0, 'en', 'En', 'English (US)', 'xkb'), (1, 'ru+typewriter', 'Ru', 'Russian (typewriter)', 'xkb')],)

Get current input source:

$ gdbus call -e -d org.gnome.Shell \
    -o /org/gnome/Shell/Extensions/Agism \
    -m io.sourceforge.Agism.GetCurrentSource
((uint32 0, 'en', 'En', 'English (US)', 'xkb'),)

Do the same by getting the CurrentSource property:

$ gdbus call -e -d org.gnome.Shell \
    -o /org/gnome/Shell/Extensions/Agism \
    -m org.freedesktop.DBus.Properties.Get io.sourceforge.Agism CurrentSource
(<(uint32 0, 'en', 'En', 'English (US)', 'xkb')>,)

Activate the first input source, do not update MRU list, do not play any sound:

$ gdbus call -e -d org.gnome.Shell \
    -o /org/gnome/Shell/Extensions/Agism \
    -m io.sourceforge.Agism.ActivateInputSource 0 false ""
(true,)

Activate the second input source, update MRU list, play "bell" sound:

$ gdbus call -e -d org.gnome.Shell \
    -o /org/gnome/Shell/Extensions/Agism \
    -m io.sourceforge.Agism.ActivateInputSource 1 true bell
(true,)

Monitor signals sent by Agism:

$ gdbus monitor -e -d org.gnome.Shell \
    -o /org/gnome/Shell/Extensions/Agism
Monitoring signals on object /org/gnome/Shell/Extensions/Agism owned by org.gnome.Shell
The name org.gnome.Shell is owned by :1.2953
/org/gnome/Shell/Extensions/Agism: org.freedesktop.DBus.Properties.PropertiesChanged ('io.sourceforge.Agism', {'CurrentSource': <(uint32 1, 'ru+typewriter', 'Ru', 'Russian (typewriter)', 'xkb')>}, @as [])
/org/gnome/Shell/Extensions/Agism: org.freedesktop.DBus.Properties.PropertiesChanged ('io.sourceforge.Agism', {'CurrentSource': <(uint32 0, 'en', 'En', 'English (US)', 'xkb')>}, @as [])

The two signals shown above are caused by switching keyboard layout to Russian and then back to English. If the user adds, remove, or reorder input sources using GNOME Settings application, it will cause a signal like this:

/org/gnome/Shell/Extensions/Agism: org.freedesktop.DBus.Properties.PropertiesChanged ('io.sourceforge.Agism', {'InputSources': <[(uint32 0, 'us', 'en', 'English (US)', 'xkb'), (1, 'ru+typewriter', 'ru', 'Russian (typewriter)', 'xkb')]>, 'CurrentSource': <(uint32 0, 'us', 'en', 'English (US)', 'xkb')>}, @as [])

AUTHORS

Van de Bugger, van.de.bugger@gmail.com.

BUGS

If you are a newbie, read Simon Tatham’s essay “How to Report Bugs Effectively”. The essay is available in several languages.

A bug report or help request must include:

Brief description of your system. Run the following commands and show me their exact output:
```
$ cat /etc/os-release
$ uname -m
```
How you installed Agism:
1. If you installed a prebuilt RPM from Tapper’s Copr repository: Provide the exact name of the installed RPM package: rpm -q gnome-shell-extension-agism.
2. If you installed a prebuilt extension pack: Provide the exact URL you used.
3. If you built Agism from sources: Provide the exact name of the source tarball and tell what you built and installed — RPM, extension pack, or used traditional make install.
In case of build problem: Exact build commands and their exact output.

In case of run time problem: Run the following commands and show me their exact output:

$ echo $XDG_SESSION_TYPE
$ echo $XDG_SESSION_DESKTOP
$ gnome-shell --version
$ gnome-extensions show agism@agism.sourceforge.io
$ gdbus introspect -e -d org.gnome.Shell -o /org/gnome/Shell/Extensions/Agism

Then describe your actions, the actual Agism behavior, and your expectations.

Collect all the requested information and send the bug report to van.de.bugger@gmail.com.

COPYRIGHT AND LICENSE

Copyright 🄯 2022, 2023 Van de Bugger. License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

NAME

SYNOPSIS

DESCRIPTION

Input source structure

‘ActivateInputSource’ method

‘GetCurrentSource’ method

‘GetInputSources’ method

‘CurrentSource’ property

‘InputSources’ property