May 2016

  March 2020. This is mostly-deprecated. We recommend using wsurveyMoveBoxes instead.

Description of wSurvey's wsurveyMoveBox library

These functions will create a moveable/resizeable DIV (or other container) that will work under all browsers.

     For an alternate method of making a moveable container, see wsurveyMoveBox2.txt
     For a simpler method, see wsurveyShowAlert.txt


I. Installing

 wsurveyMoveBox uses  jQuery and a few wSurvey libraries

 Hence, you could use the following in html files:

  <script type="text/javascript" src="/wsurvey/publicLib/jquery-1.11.3.min.js"></script>
  <script type="text/javascript" src="/wsurvey/jsLib/wsurveyMoveBox.js"></script>
  <script type="text/javascript" src="/wsurvey/jsLib/wsurveyUtils1.js"></script>

II. Basic useage

  One creates an element (such as a DIV)  which we call the "moveable box". One then adds sub elements (such as SPANs) that will be treated as small buttons.
  These small buttons can be used to move, resize, or hide the element; with moving and resizing by clicking and dragging the appropriate button
  For simplicity sake, these small buttons can be automatically created for you.

II.a : Manual setup

  The following describes the manual method of creating a moveable box.  You can use defaults if you don't want to bother with
  all of these steps (see below)

   1) Create a DIV (or other element) that will be the moveable box.
      We recommend specifying CSS position (left and top) and size (height and width) attributes, either in an inline style, or using
      a class. The left, top, width, and height can be in pixels (px) or % of current screen size (%).
      For example:
             <div id="moveme" style="position:relative;left:10px;top:10px;width:50%;height:100px;overflow:auto">  ... </div>
     Notes:
         * If you don't specify CSS position and size attributes, not necessarily attractive defaults will be used.
         * If you specify a "static" position, it will be converted to "relative"
         * A "fixed" position can be specified, and moved around/resized (it will retain its new "fixed" location during scrolling)
         * If you do not specify an overflow, the contents may spill out of the moveable box.
         * You can use a class instead of a style. For example, the locateBoxMiddle class (specified in wsurveyMoveBox.css)
           specifies a fixed position (that will not move as the window scrolls)  in the middle of the window (with scrollbars enabled)

   2)  In this DIV, specify a few "buttons": that will be used for moving and resizing and closing
         For example:
            <input type="button" id="moveButton"       value="o"   >
            <input type="button" id="resizeButton"     value="@" >
            <input type="button" id="closeButton"     value="x" >

         Better example (smaller buttons in upper right corner, descriptive titles, better resize icon):
               <span class="moveBoxButtonsUpperRight" >
                  <input type="button" id="moveButton"   title="click and hold to move  "   value="&#9678;"  class="moveBoxButton">
                  <input type="button" id="resizeButton" title="click and hold to resize"  value="&varr;" class="moveBoxButton">
                  <input type="button" id="closeButton" title="click to close"  value="&otimes;" class="moveBoxButton">
               </span>
        where the moveBoxButtonsUpperRight   and moveBoxButton are specified in moveBox.css

        You can create several of each kind of button by specifying elements with unique ids.

      Resize button notes:
         *  Warning
              If you use "right" or "bottom" to specify the position of a resize button, thing won't work properly under older versions of
              Chrome and IE (under Firefox there is no problem). Hence we recommend using "left" and "top" when positioning a "resize button"


   3) In a function (say, that is called by onLoad, or (document.ready()) ) initialize the moveable box using the  setupMoveBox function.
      setupMoveBox is called as:

          setupMoveBox(moveableBoxId,moveButtonId,resizeButtonId,closeButtonId);

     The moveableBoxId  must be the ID of the div (or other container) you want to be able to move.
     The other three arguments should be id(s) of the move button(s), a the resize button(s), and close buttons
     Example:
         If "moveme" is the id of the moveable box,
            "moveButton" the id of  the button to be used for moving the box, and
            "resizeButton" the id of the button used to resize the box
            "closebutton" is the ide of a button used to hide the box
            then include the following in a onLoad (or a document.ready(...))
       setupMoveBox('moveme','movebutton','resizebutton','closebutton');
 
       If you want to use defaults for the move and resize buttons (using the examples specified in step 3), use an argument of 1
       for any of the move, resize, or close button ids. To not enable a button, specify a 0 (or do not specify  the argument).
 
            Examples:  setupMoveBox('moveme',1,1,1);      create default move, resize, and close buttons (in upper right corner)
                       setupMoveBox('moveme','moveThing',1,1);      use an element with moveThing id for the move button, craete a resize button, no close button
                       setupMoveBox('moveme',0,1,1);      no move button, but resize and close button will be created
 
    Notes:

       * By default, clicking & moving a resize button will move the upper right (NE) corner -- "expanding" towards the NE corner (upper right),
         and "shrinking towards the SW (lower left) corner. The SW corner never moves!
           This behavior occurs no matter where you place the resize button. Hence, it is usually best to place a resize button in the
           NE corner of the moveable box.
        * If you wish you can specify which corner of the box will expand (with the diagonal corner fixed)
           This is done using by specifying a "=dd" after a resizeButton id in the call to setupMoveBox
              dd can be one of the 4 values: NE (the default), SE, SW, and NW
           For example:
                setupMoveBox('moveme','1','resizeNW=NW resizeNE=NE resizeSE=SE resizeSW=SW','1');
           which assumes you have appropriately located resizeDD (dd=NW, NE, etc) elements (i.e.; a button with id="resizeNW" in the upper right corner)
           Note: there should be NO spaces before and after the "=" sign(s).

III. Default setups

   If you are willing to accept some defaults, you can save some time and trouble by using automatic settings.
   You can do this in two ways. You will still need to create the <div> (or other element) you wish to
   make moveable box with a known ID.  You can specify styles and classes for it.

   1) Simple:
       setupMoveBox('moveBoxId',1,1,1)
         A resize, move, and close button will be placed in the upper rightcorner of the moveBoxId element.

   2) Not so simple:

        createMyMoveBox(moveBoxId)

      The element (with moveBoxId id) will have a
         * a fixed position in the middle of the screen;
         * close and move button in the   upper right corner.
         * each corner will have an appropriate resize button (directionally correct).
         * scroll bars will be added if an overflow style was not specified
         * a light gray background if a background-color was not specified
         * a black border if a border was not specified

      You can set the size and position of this box by using:
      
          createMyMoveBox(moveBoxId,opts)

       where opts is a space delimited string with the format: 'distanceToTop distanceToRight distanceToBottom distanceToLeft')
       where each distance can be 'xx%' or 'nnpx'
       For example: '20% 25% 50% 20%'
       The moveable box will cover the area of the screen specified using these 'distanceTo' values (you can think of them as
       equivalent to the margin and padding format)