screensaver widgets

[Chani]

I'm pretty sure I'm not going to be awake for tomorrow morning's meeting, 
so I decided to write up some information instead.

first of all, like I mentioned on my blog, I'm not going to have time to 
implement any features for 4.2 - so if anyone is interested in my tasks on 
the feature plan, please take them. :)

I mentioned the current status of my soc project at the bottom of my last 
blog post: http://chani.wordpress.com/2008/10/17/not-dead-yet/

I'm really interested in code review. as in, I didn't really get any and I 
*know* some of what I wrote is bad.
during soc I added a bunch of stuff to krunner/lock/lockprocess.cc (where 
most of the scaryness is), and created all of plasma/shells/screensaver. 
I also touched the kcm (kcontrol/screensaver/scrnsave.cpp iirc) but that 
module could do with a complete UI review, so I won't care about the little 
bit I added until someone does that. ;)
right now I'm mostly concerned with LockProcess::startPlasma() - it's full of 
weirdness and I know it, but I don't know how to make it better.

now... I'm going to list what still needs doing to really complete screensaver 
widgets, and then dump all the documentation I've written so far. this will 
probably turn into a rather long email. :) it'd be longer if I hadn't lost a 
couple of weeks of this information with my laptop.

===========================================

so, stuff that needs doing that I'm planning to do soon:
-plasma-overlay should tell lockprocess when it's done loading and not show 
its view by default. then lockprocess can either tell it to show or tell it to 
quit, eliminating hte flicker if you dismiss the screensaver before it finishes 
loading plasma.
-Plasma::Dialogs are being tagged the same way as config dialogs, when 
they are supposed to be treated like contextmenus (iirc). something has 
changed here - my funny hacks used to catch all the right windows but they 
don't any more. I could adjust the hacks, or I could make another try at 
finding a real solution. I also need to change the tagging to use proper x 
atomy thingies instead of magic numbers.
-the containment contextmenu should have the quit action
-it'd be nice if I could always get plasma-overlay's winid from the mapnotify 
xevent and eliminate the dbus functions for that. I'm just not sure what to 
do if plasma-overlay is somehow already running
-containment, iirc, is still painting its own black background. I'm hoping 
htat if I get rid of that, the wallpaper plugin will automagically shine 
through. but I'll need someone with composite to help me test to make sure 
I don't break that (it shouldn't, though. should be fine, like the dashboard)
-the containment settings dialog doesn't show. I need to find out why, and 
then merge it with the desktop shell's config to get wallpaper stuff (but *not* 
ctmt swapping).

stuff that needs doing that I probably won't get to for a while:
-there's some silly showevent stuff in the view that would be really easy to 
clean up, and I knew how to do it in.. probably june. but I keep forgetting to 
do it.
-eventually I need to write some stuff, probably in libplasma, to let applets 
know which security constraints are in effect so that they can attempt to 
comply. this goes with the planned security enforcement that hasn't made it 
into appletbrowser yet. aaron, if you can find that piece of paper with the 
appletbrowser stuff, please scan it in so I can have a copy :)
-in the kcm, if you turn on widgets and then hit the setup button before you 
hit apply... well, widgets are still disabled, so you just get a screensaver 
that vanishes when you move the mouse. I'm not sure what *should* 
happen, but I'll probably ignore that until the whole kcm gets some 
attention.


stuff that I don't really know how to solve:
-the tab key no longer works in the applet browser. it works in every other 
part of plasma-overlay, and it works in hte dashboard's appletbrowser, and 
it was fine during akademy, so I have no idea what's going on here.
-I never managed to focus the filter widget when showing the appletbrowser
-I still have to click once on plasma-overlay before keyboard shortcuts start 
working. iirc dashboard has the same issue. it's a tiny little issue I'd like 
to squish if possible.
-plasma-overlay makes no attempt to handle multiple screens, although a lot 
of the code relating to it is simply commented out (I should probably delete 
that so that if anyone decides to tackle this they go look at the desktop 
shell instead of the bitrotting commented code).

...I feel like there should be more than that. :) maybe there are things I 
lost and forgot, maybe I really am that close to being done.

===========================================

as for documentation.... it took me a while to understand how the 
screensaver system fits together. I'll have to redraw my diagram sometime. 
for now, I have a pile of unfinished notes I was working on; it'd be good to 
actually have them backed up this time ;P

aaand I am really tired, so I'm just going to unceremoniously dump them in 
now with no editing.

so there are three main bits that I touched: lockprocess, plasma-overlay, 
and hte kcm. the actual screensaver binaries that lockprocess uses are 
none of my business.
the screensaver stuff can be a little hard to grok. krunner has a dbus 
interface that can be used to trigger the screensaver, and also triggers it 
after the idle timeout (?). what's triggered is the krunner/lock/ folder, the 
main part of it being lockprocess. the actual screensaver drawing is done by 
little .kss binaries, and the plasma drawing n'stuff is done by plasma-overlay.
plasma-overlay
plasma-overlay is the plasma shell for the screensaver. it's very basic, with 
a stripped-down corona, view, containment and app.
the containment (SaverDesktop) has different actions, passworded 
unlocking, plus code to co-operate with lockprocess. because of all this 
special code, the user shouldn't be allowed to change hte containment. we 
also need to get SaverDesktop out of the list of desktop containment 
choices. hrrm - should it be a Desktop or Custom containment, anyways? I 
*still* don't understand that
lockprocess
in lockprocess, we have a bunch of code to make sure plasma stuff is 
displayed and sent input properly. to figure out which windows are plasma 
windows, plasmaapp tags them with x11 thingies that need some cleanup.
there's also a tweak to the unlock dialog, to allow plasma to "unlock" itself 
without quitting the screensaver. this is available over dbus.
this stuff could theoretically be used by non-plasma applications, but in 
practice that would probably fail in interesting ways.
there are three basic states lockprocess can be in: idle (showing the 
screensaver and maybe plasma in idle mode), where activity will either show 
the lock dialog or dismiss the screensaver [in the future there might be a 
third possibility, reactivating plasma].
active-plasma (showing the screensaver with plasma on top (assuming you 
have composite)), where all activity will be forwarded to the topmost plasma 
window. the screen may or may not actually be locked.
active-dialog (showing some dialog over the screensaver and plasma), 
where all activity will be forwarded to the dialog. this means stuff like the 
lock dialog, *not* plasma dialogs, so it's a pretty safe bet the screen's 
locked.
transitions between states
there are several timouts that can trigger transitions, as well as user input. 
this can make it a bit confusing. :)
first of all, the screensaver is begun either by a timeout, by the user or a 
program locking the screen, or by the "setup mode" button in hte kcm. the 
first two should start at idle, the third starts at plasma-active.
when idle, movement can lead to a quit or a change to active-dialog 
[possibly active-plasma in future]. if unlocked, a timeout may lead to the 
screen locking.
when active-dialog, user actions depend on what dialog it is. generally, 
clicking cancel or somewhere outside the dialog leads to active-plasma (or 
idle if there is no plasma?), entering a correct password in the standard lock 
dialog leads to quitting, and entering hte password in hte custom lock dialog 
leads to unlocking without quitting (and plasma-overlay being unlocked too). 
other dialogs can lead to spawning new sessions, but that's a bit outside our 
scope.
a ten-second timeout from hte custom lock dialog will lead back to plasma-
active, while hte timeout from any other dialog (afaik) leads back to idle.
when active-plasma, the user can lock hte screen or trigger the custom lock 
dialog. htey can also quit or trigger the standard lock dialog (both depend 
on whether the screen is locked, of course). a timeout (equal to the time it 
takes to start the screensaver) leads back to the idle state [in the future, 
going back to idle from an unlocked plasma might set some flag to lead back 
to plasma-active instead of quitting on activity - ooh. unlock -> setup mode 
on. lock -> setup mode off. or really, hte special case is where we start 
unlocked and idle, that's the only time movement would lead to quit]. a 
plasma crash should also lead back to the idle state ASAP, because active-
plasma without plasma means the user is trapped. (similarly, if plasma-
overlay finds itself running without krunner_lock, it will quit to avoid 
trapping the user.)
input forwarding and window stacking
since lockprocess is grabbing all input and handling window stacking, it 
needs the plasma winid(s). some plasma dialogs need input forwarded 
directly to them, while others will only get input if it's sent to the 
mainwindow. so, we have four classes of window: the main plasma window, 
other plasma windows requiring input, other plasma windows not requiring 
input, and non-plasma windows (which should always stay below the 
screensaver). the main window is really a special case of the second, so I'm 
not certain it should be treated differently... also, we get its winid over 
dbus at the start, which might no longer be necessary.
PlasmaApp tags the windows with some x11 thing (that code needs 
cleaning up), and lockprocess picks this up in its big event function. when a 
window appears or does something, lockprocess might also restack them 
all.
stacking windows happens top-to-bottom. first the dialogs are stacked, 
most-recently-shown on top, then plasma windows are stacked below them 
in the same order, then the lockprocess window (which the screensaver is 
drawing into).
when forwarding input, the dialogs again take precedence over plasma. 
input goes to the topmost window regardless of where you click, with the 
exception that clicking outside a dialog will cancel the dialog.
not all input is forwarded, and there are some weird little problems with 
things not always getting through right now. I'm more and more tempted to 
just use the window manager...
screensaver kcm
I added a checkbox to enable plasma, and a button to start it in "setup 
mode". this whole dialog needs usability attention desperately, so I changed 
as little as possible.
security
the idea is to someday have the ability to filter out stuff in the 
appletbrowser, based both on unwanted categories and on security 
constraints in hte .desktop files. this got stalled pending an appletbrowser 
rewrite that may not happen for a while. I could perhaps put in hte ability 
for applets to query security constraints and change their behaviour... then 
it'd be possible for some applets to obey security, but there'd be no 
indication to the user.

-- 
This message brought to you by eevil bananas and the number 3.
www.chani3.com