RFC: idle protocol

[Peter Hutterer]

On Tue, Dec 08, 2015 at 02:12:01PM +0100, Martin Graesslin wrote:
> Hi Wayland-developers,
> 
> at KDE we developed a protocol for our framework kidletime [1]. The idea is to 
> notify Wayland clients when a wl_seat has been idle for a specified time. We 
> use this for example for power management, screen locking etc. But a common 
> use case is also setting a user as away in a chat application.
> 
> We think that this protocol can be in general useful for all Wayland based 
> systems. Our current protocol is attached to this mail. Of course for 
> integration into wayland protocols the namespace needs adjustments (I'm open 
> for suggestions).
> 
> The reference implementation of the protocol can be found in the KWayland 
> repository (client at [2], server at [3]).
> 
> Best Regards
> Martin Gräßlin
> 
> [1] http://inqlude.org/libraries/kidletime.html
> [2] git://anongit.kde.org/kwayland (path src/client/idle.h and src/client/
> idle.cpp)
> [3] git://anongit.kde.org/kwayland (path src/server/idle_interface.h and src/
> server/idle_interface.cpp)

> <?xml version="1.0" encoding="UTF-8"?>
> <protocol name="idle">
>   <copyright><![CDATA[
>     Copyright (C) 2015 Martin Gr????lin
> 
>     This program is free software: you can redistribute it and/or modify
>     it under the terms of the GNU Lesser General Public License as published by
>     the Free Software Foundation, either version 2.1 of the License, or
>     (at your option) any later version.
> 
>     This program is distributed in the hope that it will be useful,
>     but WITHOUT ANY WARRANTY; without even the implied warranty of
>     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>     GNU Lesser General Public License for more details.
> 
>     You should have received a copy of the GNU Lesser General Public License
>     along with this program.  If not, see <http://www.gnu.org/licenses/>.
>   ]]></copyright>
>   <interface  name="org_kde_kwin_idle" version="1">
>       <description summary="User idle time manager">
>         This interface allows to monitor user idle time on a given seat. The interface
>         allows to register timers which trigger after no user activity was registered
>         on the seat for a given interval. It notifies when user activity resumes.

you need to describe what classifies as "user activity".

> 
>         This is useful for applications wanting to perform actions when the user is not
>         interacting with the system, e.g. chat applications setting the user as away, power
>         management features to dim screen, etc..
>       </description>
>       <request name="get_idle_timeout">
>         <arg name="id" type="new_id" interface="org_kde_kwin_idle_timeout"/>
>         <arg name="seat" type="object" interface="wl_seat"/>
>         <arg name="timeout" type="uint" description="The idle timeout in msec"/>
>       </request>
>   </interface>
>   <interface name="org_kde_kwin_idle_timeout" version="1">
>       <request name="release" type="destructor">
>         <description summary="release the timeout object"/>
>       </request>
>       <request name="simulate_user_activity">
>           <description summary="Simulates user activity for this timeout, behaves just like real user activity on the seat"/>
>       </request>

please rename this to "reset_timeout", because "user activity" includes a
lot more than resetting a timeout under certain condition. You can still
make it clear in the documentation when it will trigger, what the context
is, etc., but naming this simulate_user_activity is a bad idea IMO.

>       <event name="idle">
>           <description summary="Triggered when there has not been any user activity in the requested idle time interval"/>
>       </event>

what happens when the idle time has been exceeded by the time the request is
processed? or does it only trigger from time-of-request + idletime?
if the former, you need to detail how the compositor is supposed to keep
track of this.

>       <event name="resumed">
>           <description summary="Triggered on the first user activity after an idle event"/>
>       </event>

same here, more information is needed, can this be triggered before an idle
event?

Cheers,
   Peter

>   </interface>
> </protocol>