wmhelper Files

PRESENTATION
============

wmhelper is a multi-purposes tool dedicated to window managers like 
fluxbox or  windowmaker, which allows to :

  * Get the class name of a selected window
  * Take a screenshot of the full screen (with/without timeout)
  * Take a screenshot of a selected window
  * Take a screenshot of a rectangular region
  * Displays an information/warning/error message in a dialog-box
  * Ask a yes-no question
  * Displays a calendar dialog
  * Displays a color selection dialog
  * Displays a logout confirmation dialog
  * Suspend the system (with/without confirmation)
  * Hibernate the system (with/without confirmation)
  * Reboot the system (with/without confirmation)
  * Shutdown the system (with/without confirmation)

REQUIREMENTS
============

wmhelper requires :

  * yad (https://github.com/v1cont/yad).
  * libnotify
  * ConsoleKit2 or (e)logind (power operations handling)

TRANSLATION
===========

The translation of messages specified in wmhelper configuration file are
supplied in file(s), stored in /usr/share/wmhelper/locale, that follow
the naming convention below :

    wmhelper-<lang>[_<country>][@modifier].conf

wmhelper loads the 1st available translation file according to the table
below :

    LC_MESSAGES          !       Possible translation files
                         !          in order of matching
    ---------------------+-----------------------------------------
    lang_COUNTRY@MODIFIER! wmhelper-lang_COUNTRY@MODIFIER.conf
                         ! wmhelper-lang_COUNTRY.conf
                         ! wmhelper-lang@MODIFIER.conf
                         ! wmhelper-lang.conf
    ---------------------+-----------------------------------------
    lang_COUNTRY         ! wmhelper-lang_COUNTRY.conf
                         ! wmhelper-lang.conf
    ---------------------+-----------------------------------------
    lang@MODIFIER        ! wmhelper-lang@MODIFIER.conf
                         ! wmhelper-lang.conf
    ---------------------+-----------------------------------------
    lang                 ! wmhelper-lang.conf


Below the progress status of supported locales :

    LOCALE   ! STATUS        ! PROGRESS 
   ----------+---------------+--------------
     de      ! In progress   !  35% (13/37)
     en      ! Done          ! 100% 
     es      ! In progress   !  37% (14/37)
     fr      ! Done          ! 100%     
     it      ! In progress   !  37% (14/37)
     nl      ! In progress   !  37% (14/37)
     pl      ! In progress   !  37% (14/37)
     pt      ! In progress   !  37% (14/37)
     ru      ! In progress   !  32% (12/37)
     sv      ! In progress   !  32% (12/37)
    
Support of any new locale requires to proceed as below :

  1. create the configuration file for the target locale. The easiest
     way is to start from a copy of any supported locale, wmhelper-en.conf
     for instance :
     
     $ cd locale 
     $ cat wmhelper-en.conf wmhelper-en_AU.conf
     
  2. Specify the target locale in the header of the configuration file
     for that locale. 
     
     For instance, in the case of example in (1), at start of file 
     wmhelper-en_AU.conf, it is required to replace :
     
       # wmhelper (Language: en)
       
     With :
     
       # wmhelper (Language: en_AU)
       
  3. Make translation.
  
  4. Rebuild and reinstall wmhelper.

PROGRAM NAME AS USED BY THE WINDOW MANAGER
==========================================

wmhelper sets the program name as used by the window manager (see 
option --name=<NAME>) to one of the following names :

  WmHelperInfo
    When running "wmhelper --info", and each time an information dialog 
    box is displayed by wmhelper.
    
  WmHelperWarning
    When running "wmhelper --warning".
    
  WmHelperError
    When running "wmhelper --error", and each time an error dialog box 
    is displayed by wmhelper.

  WmHelperQuestion
    When running "wmhelper --question", and each time a yes-no question
    dialog box is displayed by wmhelper.
    
  WmHelperCalendar
    When running "wmhelper --calendar".
  
  WmHelperToggleCalendar
    When running "wmhelper --calendar TOGGLE".
  
  WmHelperColor
    When running "wmhelper --color".
    
  WmHelperToggleColor
    When running "wmhelper --color TOGGLE".
    
  WmHelperScreenshot
    When running "wmhelper --screenshot FULL <TIMEOUT>", with TIMEOUT>0.
    
  WmHelperLogout
    When running wmhelper --logout.
  
  WmHelperPower
    When running wmhelper --suspend | --hibernate | --reboot | --shutdown

KNOWN ISSUES
============

  * The yad option --fixed, which can be specified through the configuration
    property YAD_COMMON_OPTS or through the option --yad, must not be used 
    with yad<=0.40 built with gtk+2 as it causes the dialog boxes to be 
    misplaced from time to time (ex. in upper left corner even when the 
    dialog is configured to be centered).

  * This is not encountered with yad built with gtk+3. In this context, 
    this option can be used as a workaround to a bug that causes too high
    dialog boxes when multi-line text is passed to yad.

  * The option --selectable-labels does not work properly with yad<2.0 : 
  
      the dialog label text is already selected (and highlighted) when 
      the dialog is opened because of bug #45 (1) that is fixed by commit
      d24e98c (2)
      
      (1) https://github.com/v1cont/yad/issues/45.
      (2) https://github.com/v1cont/yad/commit/d24e98cc94c6e8b92d610fdfaebf1cc194dc1235

  * yad 0.40 is the latest (known) version which offers color selection
    dialog that includes an eyedropper.
    
    It seems that eydropper feature was depreacted (then removed ?) since
    Gtk+ 3.4.0 (https://lwn.net/Articles/488827/)

TROUBELSHOOTING
===============

  * The dialog-boxes are too large (on X).

    To prevent too large dialog boxes (on X), it is highly recommended 
    to pre-format messages passed to wmhelper, using command 'fold' for
    instance :

      wmhelper --info "$(echo "${LONGTEXT}" | fold -w 80)"