NAME
    Widget.PairedMultiSelect - A widget based on a pair of multiple select
    elements

SYNOPSIS
      <select name="wpms1" id="wpms-first" multiple="1">
       <option value="1">One</option>
       <option value="2">Two</option>
       <option value="3">Three</option>
      </select>

      <a href="#" id="wpms-selected-first-to-second"><img src="/src/a/au/autarch/WidgetPairedMultiSelect_011/README/left_to_right.png" /></a>
      <a href="#" id="wpms-selected-second-to-first"><img src="/src/a/au/autarch/WidgetPairedMultiSelect_011/README/right_to_left.png" /></a>

      <select name="wpms1" id="wpms-second" multiple="1">
       <option value="1">One</option>
       <option value="2">Two</option>
       <option value="3">Three</option>
      </select>

      <script type="text/javascript">
       Widget.PairedMultiSelect.newFromPrefix("wpms");
       # or ...
       new Widget.PairedMultiSelect( { firstId: "wpms-from",
                                       secondId:   "wpms-to",
                                       selectedFirstToSecondId: "wpms-selected-from-to",
                                       selectedSecondToFirstId: "wpms-selected-to-from" } );
      </script>

DESCRIPTION
    This library ties together two multiple `<select>' elements and some
    controls to provide a more user-friendly way to handle selection of
    multiple items from lists, as opposed to single multiple `<select>' or a
    group of checkboxes.

    It expects to find these elements already on the page, and will add the
    appropriate event listeners for them.

METHODS
    * new Widget.PairedMultiSelect( { ... } )
        Expects an object with the following properties, some of which are
        optional:

          { firstId: "first",
            secondId: "second",
            selectedToSecondId, "move-selected-to-second",
            selectedToFirstId, "move-selected-to-first",
            allToSecondId, "move-all-items-to-second",
            allToFirstId, "move-all-items-to-first",
            sortFunction: sortByNumber }

        Given an object with the specified properties, the constructor
        creates a new widget and attaches the appropriate event handlers to
        the specified elements.

        The only required properties are "firstId" and "secondId", which
        should be the ids of two multiple select form elements.

        The other properties, except for "sortFunction", specify element ids
        for elements that should have onclick events added which do the
        appropriate action. The event handler will move either the selected
        options for all options to one of the two select lists.

        In addition, an onsubmit event listener will be added to the form
        containing the select elements. This event listener will select all
        of the options in *both* select lists before the form is submitted.

        The two lists of options will be sorted after each move. The default
        sort function sorts by the *string* representation of each options
        `value' property. If you provide a "sortFunction" parameter, it will
        be used instead. Your function will be passed two *Option* objects
        for comparison.

        When the object is first created, it will call
        `moveSelectedFirstToSecond()' on itself in order to move selected
        elements from the first list to the second.

    * Widget.PairedMultiSelect.newFromPrefix(prefix)
    * Widget.PairedMultiSelect.newFromPrefix( prefix, sort_func )
        This method greatly simplifies creating a new widget, but you have
        to follow a specific id name pattern to use it. The prefix is used
        to create a set of element ids, based on this formula:

          firstId:             prefix + "-first"
          secondId:            prefix + "-second"
          selectedToSecondId:  prefix + "-to-second"
          selectedToFirstId:   prefix + "-to-first"
          allToSecondId:       prefix + "-all-to-second"
          allToFirstId:        prefix + "-all-to-first"

        This method also accepts an optional sort function as its second
        parameter.

    * moveSelectedFirstToSecond()
    * moveSelectedSecondToFirst()
        Move selected options in one select list to the other.

    * moveAllFirstToSecond()
    * moveAllSecondToFirst()
        Move all options in one select list to the other.

AUTHOR
    Dave Rolsky, <autarch@urth.org>.

COPYRIGHT
    Copyright (c) 2005 Dave Rolsky. All rights reserved.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as the Perl programming language (your choice of
    GPL or the Perl Artistic license).

</html>