1. Introduction
    1.1. Project/Component Working Name:
	 Hot Key Based Display Device Switch (dispswitch)
    1.2. Name of Document Author/Supplier:
	 Author:  Henry Zhao
    1.3  Date of This Document:
	 Aug 7, 2008

4. Technical Description

   4.1 With the integration of RandR 1.2 into Xorg, it is possible to dynamically
       add and remove display devices and adjust display modes while X window system
       is running. However only a command line interface is currently available.
       Therefore a user needs to type several lengthy commands to add display
       devices, and possibly another series of commands to adjust the modes for
       each device. This project allows the use of a "hotkey" to probe for display 
       devices, turn on or off display devices, and in the case of more than one 
       device being turned on, automatically adjust modes to the best shared 
       resolution. This feature is especially useful in applications such as 
       connecting a laptop to a projector. 

   4.2 dispswitch is an X client application that uses Xrandr library functions 
       XRRGetScreenResources() to gather display output information, 
       XRRGetScreenSizeRange() and XRRSetCrtcConfig() to switch display devices 
       and set modes. Switching is triggered by a predefined key stroke - the
       "hotkey".  If a "hotkey" stroke is 5 seconds or longer after the previous 
       switch, system output configuration is re-probed so that any output 
       configuration changes, such as adding or removing display devices, can be 
       detected and adapted to. When two display devices are turned on, the 
       largest common resolution for both devices will be automatically used. The 
       project allows switching among up to three display outputs with one or two 
       of them being turned on at a time (Currently most graphics hardware 
       supports up to two simultaneous displays). For example, in a system with 
       three devices connected to LCD, VGA and DVI outputs, 6 different states 
       (excluding states of all on and all off) of them will be cycled through 
       with consecutive "hotkey" stroke. Side-by-side views are included in the 
       state cycling when two devices are connected.

   4.3 The application works on systems where both X server and driver support
       RandR (1.2 or above). It will be added to the Gnome's launcher.

   4.4 "Hotkey" interface

       When the project is completed, two "hotkey" interfaces will be provided:
       ACPI "hotkey" and user defined "hotkey". ACPI "hotkey" uses keyboard defined
       "display device switch function key". Since not all laptops have ACPI 
       notification support for ACPI "hotkey", we also provide user defined
       "hotkey". This review only covers the first phase of the project, i.e.
       the part with user defined "hotkey" interface.
 
       The application allows user to use command line options (-key <keysym> 
       -mod <modifier>) to define a "hotkey" that may use for display device 
       switch. This may cover desktops, and laptops where ACPI "hotkey" notification 
       mechanism is not working.  The default is "Shift+F5".

   4.5 Usage: dispswitch [options]

       where options are:

      -display <display>
      -key <keysym>
      -mod <modifier> 
      -help
      -nosideview
      -verbose
      -testrun

      -key <keysym> -mod <modifier> will let user define "hotkey":
      <keysym> is any keysym defined in /usr/X11/include/X11/keysymdef.h, with 
      prefix XK_ removed, such as F5, F8, Escape.  <modifier> is any or 
      combination of modifiers on the system. User can run /usr/X11/bin/xmodmap to 
      find all available modifiers on the system. They can be shift, control, 
      mod1, mod3, mod4, mod5, any. Examples:

      -key Escape -mod shift  defines the "hotkey" to be 'shift + Esc'
      -key F2 -mod "shift+control" defines the "hotkey" to be 'shift + control + F2'

      -help		Prints out a summary of the usage
      -nosideview 	Skips side-by-side views in two device cycling.
      -testrun 	Switches repeatedly without hotkey strokes
      -verbose 	Prints debug messages


Imported Interfaces:
--------------------
RandR 1.2					Volatile
(http://www.x.org/wiki/Projects/XRandR)

Exported Interfaces:
--------------------
/usr/X11/bin/dispswitch				Uncommitted       


6. Resources and Schedule
    6.1. Projected Availability
	The project is to be available in two phases:
	6.1.1  Phase 1:
	       Putback of implementation of user defined "hotkey" interface 
	       Aug 2008
	6.1.2  Phase 2:
	       Putback of implementation of ACPI "hotkey" interface 
	       Oct 2008
    6.4. Steering Committee requested information
   	6.4.1. Consolidation C-team Name:
		X Consolidation (Desktop C-Team)
    6.5. ARC review type: FastTrack
    6.6. ARC Exposure: open