===================================================
===================================================
== bangvwm.dll - Who needs a GUI? Not I. ==========
===================================================
===================================================
====== Written by: ================================
================== Chris Rempel (jugg) ============
===================================================
================== http://www.jugg.net/ ===========
================== jugg@hotmail.com ===============
===================================================
===================================================
= Version: 0.42 = Release Date: 2009.03.21 ========
===================================================
===================================================

-=ToC=-
I. Introduction
II. Installation
III. Information
 A} Commands
 B} Changes
 C} Notes
IV. Tips & Tricks
V. Disclaimer


=====================
== I. Introduction ==
=====================
===================================================

bangvwm.dll is a Virtual Desktop Manager for Win32
Shells that support the LiteStep module standard.
bangvwm.dll is based off of the idea of LiteStep's
VWM modules, but is purely controlled via !bang
commands and has no built in visual interface. This
gives an extremely fast and simple VWM without the
overhead of other similar modules.

And as RabidCow says the "W" in VWM is actually a
"D" that looks like a "W".  Because this is, as
stated above, a Virtual "Desktop" Manager, as is
every other VWM module out there.  Others call
these modules a "Virtaul Workspace Manager". So you
can take your pick. It isn't a big deal.  They were
originally named as a "Virtaul Window Manager".

BangVWM is distributed under the GPL.
See the COPYING file.

=Credits/Thanks:=
=================
Thanks to other VWM module authors, particularly
Visigoth and Chaku. Their VWM modules (sysVWM and
ckVWM respectively) were a great reference point
and code snippet source for me to work with.


=Developers:=
=============
See the end of "common.h" in the source code for
development information.


======================
== II. Installation ==
======================
===================================================

Extract "bangvwm.dll" to your Shell module folder
(eg. c:\litestep\modules\). Open up your Shell
configuration file and find the section where all
of your "LoadModule" lines are located. Remove any
"LoadModule" lines that are loading "sysvwm.dll" or
other VWM module. Now, add a new line that looks
like this:

LoadModule c:\litestep\modules\bangvwm.dll

Of course, adjust the path as necessary. Refer to
the "Commands" section and configure your new VWM.
Then save your shell configuration file(s) and
issue the Shell's Recycle command (!Recycle).


======================
== III. Information ==
======================
===================================================
= A} Commands =
===============
NOTES:
------
Items surrounded in square brackets [] are optional.

The use of <value> as a parameter means that it is
a custom string or, in some cases, an integer may
be used as well.  Each section explains what
<value> means, so please read and don't assume.  :)

Use quotation marks "" around any parameter that
has spaces in it.


bVWMDesks 2
  - Purpose: Sets the number of Virtual Desktops

  - Parameters: <integer>

    <integer> - The number of Virtual Desktops to
    be created. Minimum value is 2.

  - Defaults to: 2


bVWMFocusLast
  - Purpose: When switching Desktops, this will
    cause the last active application on the
    restored Desktop to receive focus.

  - Top most windows will not be given focus via
    this mechanism, even if it was a top most
    window that last had the focus on the virtual
    desktop.

  - Parameters: none

  - Boolean value: true if set, otherwise false.


bVWMSwitchOnFocus
  - Purpose: When focus is given to a window, the
    virtual desktop that contains the window will
    automatically be made the active desktop.

  - Parameters: none

  - Boolean value: true if set, otherwise false.


bVWMKeepMaximized
  - Purpose: When switching Desktops, this will
    keep Maximized Windows in their current
    maximized state.  By default maximized windows
    are restored to their normal size when
    switching Desktops.

  - Parameters: none

  - Boolean value: true if set, otherwise false.


bVWMStrictGather
  - Purpose: Enables "strict" gathering of windows
    so that the exact window placement is kept
    instead of the default forcing of all window
    boundaries to be inside of the current Virtual
    Desktop when the gather command is completed.
    If the window size is greater then the desktop
    the top-left borders are always assured to be
    within the desktop when this is not set.

  - Parameters: none

  - Boolean value: true if set, otherwise false.


bVWMVertical
  - Purpose: Sets the VWM layout to Vertical,
    instead of the default horizontal layout.

  - Parameters: none

  - Boolean value: true if set, otherwise false.


bVWMIgnoreDesktopUpdate
  - Purpose: Ignores desktop updates (screen
    resolution or workarea changes).  If set then
    all old desktop values are kept and continued
    to be used.  If set then the related command
    bVWMNoWindowReposition is set automatically, so
    no window updates take place.  This command
    does not affect the bVWMOnDesktopUpdate command
    which is always executed on a desktop update.

  - Parameters: none

  - Boolean value: true if set, otherwise false.


bVWMNoWindowReposition
  - Purpose: Setting this will disable auto sizing
    and positioning of windows. By default, windows
    are moved, and sized if necessary, so that they
    are kept on their virtual desktop when the work
    area or screen resolution changes.

  - Parameters: none

  - Boolean value: true if set, otherwise false.


bVWMAllowModuleControl
  - Purpose: It allows other modules to use window
    messages to control the virtual desktops. For
    example it allows other modules to request that
    the virtual desktop containing a specified
    window is made the active desktop.

  - Currently, various task managers such as
    tasks.dll utilize this interface so that when
    a task is clicked on, the desktop is changed to
    where that application is located.

  - Parameters: none

  - Boolean value: true if set, otherwise false.


bVWMOnInit ""
  - Purpose: Sets a command to execute when
    loading the module. So, this will happen
    during a recycle as well (but not a refresh).

  - Parameters: <command>

    <command> - Accepts any !bang command or
                program that can be executed.

  - Defaults to: No Default


bVWMOnQuit ""
  - Purpose: Sets a command to execute when
    unloading the module. So, this will happen
    during a recycle as well (but not a refresh).
    If this command is not set, then the first
    desktop will be restored when quiting. It is
    suggested to use !bVWMGather or !bVWMSwitchTo 0
    so that windows are not 'lost'.

  - Parameters: <command>

    <command> - Accepts any !bang command or
                program that can be executed.

  - Defaults to: No Default


bVWMOnDesktopUpdate ""
  - Purpose: Sets a command to execute when the
    screen resolution or work area changes

  - Parameters: <command>

    <command> - Accepts any !bang command or
                program that can be executed.

  - Defaults to: No Default


*bVWMExec
  - Purpose: Sets a command to execute when
    switching to the specified Virtual Desktop

  - Parameters: <integer> <command>

    <integer> - The Virtual Desktop number.
                The VD list is zero base, meaning
                the first VD is "0".

    <command> - Accepts any !bang command or
                program that can be executed.

  - Multiple settings of this command are allowed
    up to the number of Virtual Desktops created
    (value of bVWMDesks). Also, there may not be
    two commands with the same VD number.


*bVWMSticky
  - Purpose: Sets the regular expression text to
    match against all windows to determine if they
    should be kept on every VD. The <class> text is
    matched against the window class, and the
    <title> text is optional and will be matched
    against the window title.  Use quotes around
    each parameter if they contain spaces.

  - Parameters: <class> [<title>]

    <class> is a text string that is compared to
            window classes. Use "*" to match any
            class, then specify a specific window
            title to search for in the <title>
            parameter.

    <title> [OPTIONAL] is a text string that is
            compared to window titles. If not
            specified, all window titles will be
            valid.  To match only empty window
            titles, use an empty quotation set.

  - Multiple settings of this command are allowed.


  =!Bang Commands=
  ================
   !bVWMSwitchTo
     - parameters: <value>

       <value> can be one of the following:
         home - Goes to initial VD.
         end  - Goes to last VD.
         next - Goes to next VD.
         prev - Goes to previous VD.
         <integer> - Goes to specified VD.

     - Issuing this command will set the current
       Virtual Desktop to the specified <value>. If
       specifying an <integer>, the VD list is zero
       base, meaning the first VD is 0.

     - !VWMDesk can be used instead.

   !bVWMNext
     (Same as: "!bVWMSwitchTo next")
     - parameters: none

     - Issuing this command will switch to the next
       Virtual Desktop.

     - !VWMRight or !VWMDown can be used instead.

   !bVWMPrev
    (Same as: "!bVWMSwitchTo prev")
     - parameters: none

     - Issuing this command will switch to the
       previous Virtual Desktop.

     - !VWMLeft or !VWMUp can be used instead.

   !bVWMGather
     - parameters: [<value>]

       <value> can be one of the following;
         home - Gathers windows to initial VD.
         end  - Gathers windows to last VD.
         next - Gathers windows to next VD.
         prev - Gathers windows to previous VD.
         <integer> - Gathers windows to specified
                     VD if valid.

     - Issuing this command will gather all windows
       to the specified Virtual Desktop. If called
       without any parameters, it will gather the
       windows to the current Virtual Desktop.

     - The current desktop is automatically changed
       to the specified desktop when gathering the
       windows.

     - !VWMGather can be used instead

   !bVWMGatherH
     - SAME AS !bVWMGather, but this only gathers
       the windows Horizontally.  So if you have a
       window that is vertically off of the display
       it will not be gathered vertically when
       executing this command, it will only be
       gathered horizontally.

   !bVWMGatherV
     - SAME AS !bVWMGather, but this only gathers
       the windows Vertically.  So if you have a
       window that is horizontally off of the
       display it will not be gathered horizontally
       when executing this command, it will only be
       gathered vertically.

   !bVWMGatherLost
     - SAME AS !bVWMGather, but this only gathers
       'lost' windows.  'Lost' windows are windows
       that are not on any virtual desktop.

   !bVWMGatherMatched
     - parameters: <value> <class> [<title>]

       <value> can be one of the following:
         home - Gathers windows to initial VD.
         end  - Gathers windows to last VD.
         next - Gathers windows to next VD.
         prev - Gathers windows to previous VD.
         <integer> - Gathers windows to specified
                     VD if valid.

       <class> is a text string that is compared to
               window classes. Use "*" to match any
               class, then specify a specific
               window title to search for in the
               <title> parameter.

       <title> [OPTIONAL] is a text string that is
               compared to window titles. If not
               specified, all window titles will be
               valid.  To match only empty window
               titles, use an empty quotation set.

     - Issuing this command will gather all
       matching windows to the specified Virtual
       Desktop. Use quotes around each parameter if
       they contain spaces.

     - The current desktop is automatically changed
       to the specified desktop when gathering the
       windows.

   !bVWMDesks
     - parameters: <integer>

       <integer> - Number of Virtual Desktops.

     - Issuing this command sets the number of
       Virtual Desktops that is used.
       ^ See "bVWMDesks".

     - This command also reloads the *bVWMExec
       settings if the old and new number of
       Virtual Desktops is different.
       ^ See "*bVWMExec".

   !bVWMEnableFocusLast
     - parameters: none

     - Issuing this command enables the
       "bVWMFocusLast" setting.

   !bVWMDisableFocusLast
     - parameters: none

     - Issuing this command disables the
       "bVWMFocusLast" setting.

   !bVWMMoveWindow
     - parameters: [<value>]

        <value> can be one of the following:
          home - Moves window to initial VD.
          end  - Moves window to last VD.
          next - Moves window to next VD.
          prev - Moves window to previous VD.
          <integer> - Moves window to specified VD.

     - Issuing this command will move the active
       window to the specified Virtual Desktop. If
       called without any parameters, it will move
       the active window to the current Virtual
       Desktop.

     - The current desktop is automatically changed
       to the specified desktop when moving the
       window.

     - !VWMMoveApp can be used instead

   !bVWMExecute
     - parameters: <value> <command>

        <value> can be one of the following:
          home - initial VD.
          end  - last VD.
          next - next VD.
          prev - previous VD.
          <integer> - specified VD.

        <command> - Accepts any !bang command or
                    program that can be executed.

     - Issuing this command switches to the
       specified Virtual Desktop, then executes the
       command.

     - !VWMOpen can be used instead

   !bVWMRefresh
     - parameters: none

     - Issuing this command reloads the settings.
       This is similar to the shell's !Refresh
       command, but specifically for this module.
       Although settings will only be re-read from
       the Shell's configuration buffer.  Any
       changes to the configuration files will not
       take affect, unless first reloaded by the
       shell.

     - !VWMReset can be used instead

   !bVWMShiftOrigin
     - parameters: <value>

        <value> can be either + or - to shift
                the origin back or forward by one.

     - Issuing this command will change the origin
       of the Virtual Desktop by one virtual
       desktop size.  In general this command is
       not useful.  If you can think of its use,
       then it is for you, if not, ignore it.


   ------------------------------------------------
   The rest of these commands are purely for window
   management and have nothing to do with the
   Virtual Desktop Manager, and may be removed at
   some point if I find (or create) another module
   that implements the same functionality.
   ------------------------------------------------
   !bVWMWindowStretch
     - parameters: <value>

        <value> can be one of the following:
          vertical
          horizontal
          both

     - Issuing this command stretches the active
       window to the size of the desktop work area.

   !bVWMWindowAlign
     - parameters: <value>

        <value> can be one of the following:
          left   - align to the left
          right  - align to the right
          top    - align to the top
          bottom - align to the bottom
          center - align to horizontal center
          middle - align to vertical center

     - Issuing this command aligns the active
       window to the specified location, relative
       to the desktop work area.

   !bVWMWindowMaximize
     - parameters: none
     - Maximizes the active window.

   !bVWMWindowMinimize
     - parameters: none
     - Minimizes the active window.

   !bVWMWindowRestore
     - parameters: none
     - Restores the active window.

===================================================
= B} Changes =
==============
(+)Added
(-)Removed
(*)Changed
(!)Fixed
(^)MiscNote

- 0.42 -
--------
  ! Fixed bug in !bVWMWindowAlign which caused the
    center and middle values to incorrectly align
    the window.

- 0.41 -
--------
  + Added internal module control for task managers
    to request if a window is on the current
    desktop so that it would be able to display
    only tasks for those windows.

  ! Fixed Win95 support, 0.40 did not run in Win95.
  ! Fixed !bVWMWindowAlign and !bVWMWindowStretch
    from messing with maximized windows.

- 0.40 -
--------
  + Added internal shell communication window, thus
    allowing for most of these additions.
  + Added !About revision information support.
  + Added support for LiteStep 0.24.6+ !Refresh.
  + Added LM_BRINGTOFRONT
          LM_SWITCHTON
          LM_GETDESKTOPOF
          LM_VWMUP, LM_VWMDOWN,
          LM_VWMLEFT, LM_VWMRIGHT
    internal message support for control by other
    modules.
  + Added bVWMSwitchOnFocus
  + Added bVWMIgnoreDesktopUpdate
          bVWMNoWindowReposition
  + Added !bVWMGatherLost
          !bVWMGatherMatched
          !bVWMEnableFocusLast
          !bVWMDisableFocusLast
          !bVWMExecute
          !bVWMRefresh
          !bVWMShiftOrigin
  + Added !VWMDesk
          !VWMRight
          !VWMDown
          !VWMLeft
          !VWMUp
          !VWMGather
          !VWMReset
          !VWMOpen
          !VWMMoveApp
    for compatibility with other VWMs syntax.
  + Added bVWMOnInit and bVWMOnDesktopUpdate

  * Changed bVWMQuitCmd to bVWMOnQuit
  * Changed all !bang command paramters to not have
    a "." prefix.  ie: "!bVWMSwitchTo .next" is now
    "!bVWMSwitchTo next".

  ! Fixed the Virtual Desktops from not resizing
    when the desktop resolution changed. (Needed
    the communication window for this.)
  ! Fixed !bVWMDesks from losing windows if the new
    number of Virtual Desktops is less than the old
    value, and windows were on desktops that no
    longer existed.  All 'lost' windows are now
    moved to the last desktop.

- 0.33 -
--------
  * Changed !bVWMWindowMoveTo to !bVWMMoveWindow
    and documented it (oops).

  ! Fixed *bVWMExec and *bVWMSticky settings from
    not being read under LiteStep, and possibly
    crashing LiteStep. (It only worked in PureLS).
  ! Fixed *bVWMSticky's 'title' param from not
    being optional.  It now is.
  ! Fixed *bVWMSticky not supporting windows that
    did not have a window title.
  ! Fixed a very minor window positioning bug.

- 0.32 -
--------
  + Added bVWMFocusLast to restore the last active
    window on the desktop being returned to.
  + Added bVWMKeepMaximized to keep windows
    maximized when switching desktops. By default
    windows are now restored to their original
    sizes before switching virtual desktops.
  + Added !bVWMWindowMoveTo
          !bVWMWindowStretch
          !bVWMWindowAlign
          !bVWMWindowMaximize
          !bVWMWindowMinimize
          !bVWMWindowRestore

  * Changed bVWMDesk minimum value from 1 to 2.
  * Changed *bVWMSticky to specify both class and
    title to match against.
  * Changed internal window enumeration code to not
    use GetWindow() in a loop, which may have been
    causing problems.
  * Changed Switching/Gathering code to never
    resize windows. bVWMStrictGather now simply
    controls X/Y coordinate behavior during a
    gather window command.

  ^ Lots of source clean up and commenting.

- 0.31 -
--------
  + Added bVWMStrictGather to specify whether to
    force keeping exact window positions while
    switching desktops.
  + Added bVWMVertical to use a vertical VWM
    instead of a horizontal one.
  + Added bVWMQuitCmd to specify a command to
    execute when recycling/quiting.
  + Added !bVWMGatherV to gather vertically
          !bVWMGatherH to gather horizontally
  + Added !bVWMDesks to dynamically set the number
    of Virtual Desktops. (Reloads *bVWMExec)
  + Added *bVWMExec to execute a command on switch
    to specified Virtual Desktop
  + Added *bVWMSticky for specifying sticky windows
    to keep in every Virtual Desktop.

  * Changed !bVWMDesk to !bVWMSwitchTo

- 0.30 -
--------
  + Initial release.
  + Supports navigating the VWM by !bang commands


===================================================
= C} Notes =
============

This is NOT a drop in replacement! Things have
changed.  Previous !bang command syntax will not
work for the most part.

You may want to look at the bVWMAllowModuleControl.
It allows other modules to control bangVWM.  This
affects taskmanagers mainly which request that the
VWM switch to the virtual desktop the specified
application is on.  Usually you want to either use
bVWMAllowModuleControl, or bVWMSwitchOnFocus.
For example, tasks.dll which request the VWM to
switch virtual desktops when you click on an
application in a different desktop.

So, if something isn't working the way it did in a
previous version, re-read the description for the
related commands, as there were some updates that
didn't make it into the "Changes" section. Although
I have to assume if you are reading this, then you
most likely have already done so and are looking
for an answer. :)  Ohwell.  Email me.

Enjoy


=====================
= IV. Tips & Tricks =
=====================
===================================================
If entering an integer value in regards to
specifying what Virtual Desktop to access, remember
that the VD index is base zero, meaning the first
VD is "0". So if you created a VWM with 4 Virtual
Desktops, then you can use 0, 1, 2 and 3.

--

Set your configuration to switch Virtual Desktops
via the supplied !bang commands with hotkey's, or
with desktop shortcuts to use your mouse.

--

If using a Dual Monitor desktop, set your VWM
direction to the opposite of your Monitor setup.
Then only use the corresponding !bVWMGather(x) bang
command.  For example if your have a dual monitor
setup which spans horizontally, you will want to
set the bVWMVertical command and only use the
!bVWMGatherV bang command to gather your windows.
Of course you can use the other two gather commands
for advanced uses.

--

*bVWMSticky Notepad
(which is the same as)
*bVWMSticky Notepad *

Will cause all Notepad windows to be sticky,
regardless of the window title.

*bVWMSticky Notepad "*.rc - Notepad"

Will cause all Notepad windows containing an open
LiteStep configuration file to be sticky.

*bVWMSticky SciCalc Calculator

Will cause the standard Calculator to be sticky.

--

If using hotspots to switch Virtual Desktops and
you are also using bVWMFocusLast, then whenever you
are dragging a window between desktops, you may
want to set up your hotspots to execute something
like:

!execute [!bVWMDisableFocusLast][!bVWMNext]

And set your *bVWMExec commands to always include
!bVWMEnableFocusLast.

This way, focus will not be stolen from the window
you are dragging around, and given to another
window.

--

!bVWMDesks command will reload the *bVWMExec.  If
you are on a virtual desktop greater than the value
specified in !bVWMDesks, then it will auto switch
virtual desktops to the last valid one, and execute
the new *bVWMExec command for that desktop.  If you
would rather have the old *bVWMExec command be
executed, then issue !bVWMSwitchTo <new value minus
one> before issuing !bVWMDesks <new value>. So for
example if you are on a desktop greater than 2, and
the new number of virtual desktops is 2, do this:

!execute [!bVWMSwitchTo 1][!bVWMDesks 2]

All of that is irrelevant if the *bVWMExec values
were not updated.



=================
= V. Disclaimer =
=================
===================================================

Copyright (C) 2001-2009, Chris Rempel

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT  WARRANTY
OF ANY KIND, EXPRESS OR  IMPLIED, INCLUDING BUT NOT
LIMITED  TO  THE   WARRANTIES  OF  MERCHANTABILITY,
FITNESS  FOR   A   PARTICULAR   PURPOSE   AND  NON-
INFRINGEMENT.  IN  NO  EVENT  SHALL THE  AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,  DAMAGES
OR  OTHER  LIABILITY,   WHETHER  IN  AN  ACTION  OF
CONTRACT,  TORT OR OTHERWISE,  ARISING FROM, OUT OF
OR IN CONNECTION  WITH  THE  SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
