XO brightness key operation

[Paul Fox]

i just sent this to the folks working on the current doc sprint, and
then realized it probably deserves a wider audience.  operation of the
brightness keys was enhanced a bit in 11.3.1, based on discussion on
the devel list, but i don't recall that i ever sent out a summary mail.

for convenience, i'm going to refer to the brightness keys as BrUp and
BrDown here.

on all laptops, in all sofware releases to date:
    
    - the unmodified BrUp and BrDown keys adjust the brightness in 15
	steps.  when turning the backlight all the way off (i.e.,
	the lowest setting) the display will switch into the higher
	resolution monochrome mode.

    - using the Alt-BrUp and Alt-BrDown combinations will immediately
	change the backlight to its maximum and off values (including the
	change to monochrome when off).

in release 11.3.1 and later, on all laptops:

    - the Ctrl-BrUp and Ctrl-BrDown combinations don't actually change
	the backlight level, but rather will toggle the screen between
	"normal" mode and the higher resolution monochrome mode.  this
	monochrome mode will be sticky, so further normal use of the
	keys will adjust the brightness but won't restore color.  this
	can be useful if you want the higher resolution, and don't
	currently need to have color displayed.  unfortunately, there
	is currently no way to enter this "semi-permanent monochrome
	mode" via the Sugar user interface -- only Ctrl-BrDown will do it.

and finally, on XO-1.75 only:

    - the backlight may automatically turn off when the laptop is in
	bright sunlight.  when this happens, it is _not_ put into the
	hi-res monochrome mode.  when the light level returns to
	"normal" -- i.e., indoor or shady light -- the backlight will
	be restored to its previous value.
	
	the ambient light sensor shares the opening in the plastic
	with the LED that looks like "(o)" near the lower left corner
	of the screen, so covering that location when outside, or
	shining a bright light on it when inside, may cause the
	backlight level to change.


it's also worth noting that the F9 and F10 keys are, by default, the
brightness keys, and are intercepted by system software before a
running program can receive them.  if the Fn key is pressed at the
same time as F9 or F10, then the keys instead generate the true F9 and
F10 codes, and are available to the current application (or perhaps
the window manager).  this is also true of the volume keys on F11 and
F12 -- on any of our keyboards, holding Fn will force the top row of
keys to generate F1 through F12.

finally:  all of the above functionality is available from the
shell commandline:

    $ olpc-brightness -h
    usage: olpc-brightness [up|down|max|min|<0-15>|color|mono]


paul
=---------------------
 paul fox, pgf at laptop.org