Documentation

Requirements

To use the Window object, your project needs to meet the following requirements:

• it is required that the svg root element has a viewBox attribute set (e.g. viewBox="0 0 1024 768")
• set the zoomAndPan="disable" attribute in the svg root element; this is a currently known limitation, that it does not work correctly after zooming and panning manually within the plugin
• you need to link to the following scripts in your SVG header to use the selectionList: helper_functions.js, mapApp.js, timer.js and Window.js; please note, that not all of the functions in these files are needed. The depencies to functions in the file "helper_functions.js" are listed below.
• you need to include the global variable "myMapApp" of type "mapApp" into one of your js files, (e.g. var myMapApp = new mapApp();)
• you should create an empty svg group element with a unique id in an appropriate position of your document tree to hold the graphics of the Window object (e.g. <g "Windows" />), Note that if the given id does not exist, the script will create a new group and append it to the svg root element.
• you need to initialize the Window object with e.g. myMapApp.Windows["navWindow"] = new Window("navWindow","Windows",220,200,800,85,true,0,80,1024,700,true,winPlaceholderStyles,windowStyles,3,true,true,"Navigation Window","Statusbar",true,true,true,titlebarStyles,titlebarHeight,statusbarStyles,statusbarHeight,titletextStyles,statustextStyles,buttonStyles,buttonTextChange); as described below

Features

• Windows are movable and can be constrained to a certain region within the viewBox
• Windows can be minimized, restored and closed
• Windows may have title and status bars
• Windows may be made non-moveable
• Windows may be nested
• the Window content may be hidden during moving, displaying only an extent rectangle instead of the window content (see placeHolderStyles)
• a method exists for appending content to the window
• Window objects may generate events, e.g. after creation, closing, opening, minimizing, moving, removing, resize, etc.
• an activated Window automatically moves to the foreground of the Window group if one clicks on the Window titlebar
• Double Clicking on the Window titlebar minimizes or maximizes the Window (might not work in all SVG viewers)
• Window decorations may be added below or on top of the windows

Dependencies on external functions

1. Window.js:
   • all of the objects and functions in this file are necessary
2. mapApp.js:
   • all of the objects and functions in this file are necessary
3. timer.js:
   • all of the objects and functions in this file are necessary
4. helper_functions.js:
   • all the global variables at the top of the file

Constructor

The following constructor function creates the Window object:

var myWindow = new Window(id,parentId,width,height,transX,transY,moveable,constrXmin,constrYmin,constrXmax,constrYmax,showContent,placeholderStyles,windowStyles,margin,titleBarVisible,statusBarVisible,titleText,statusText,closeButton,minimizeButton,maximizeButton,titlebarStyles,titlebarHeight,statusbarStyles,statusbarHeight,titletextStyles,statustextStyles,buttonStyles,functionToCall);

Example:
//first a few styles
var winPlaceholderStyles = {"fill":"none","stroke":"dimgray","stroke-width":1.5};
var windowStyles = {"fill":"aliceblue","stroke":"dimgray","stroke-width":1};
var titlebarStyles = {"fill":"gainsboro","stroke":"dimgray","stroke-width":1};
var statusbarStyles = {"fill":"aliceblue","stroke":"dimgray","stroke-width":1};
var titletextStyles = {"font-family":"Arial,Helvetica","font-size":14,"fill":"dimgray"};
var statustextStyles = {"font-family":"Arial,Helvetica","font-size":10,"fill":"dimgray"};
var buttonStyles = {"fill":"gainsboro","stroke":"dimgray","stroke-width":1};
var titlebarHeight = 17;
var statusbarHeight = 13;
myMapApp.Windows["navWindow"] = new Window("navWindow","Windows",210,200,810,85,true,0,80,1024,700,true,winPlaceholderStyles,windowStyles,3,true,false,"Navigation Window","",true,true,true,titlebarStyles,titlebarHeight,statusbarStyles,statusbarHeight,titletextStyles,statustextStyles,buttonStyles,buttonTextChange);

The constructor arguments are the following:

1. id (String):
   unique id that represents a window. The outermost newly created group of the Window geometry gets this id. Furthermore, this id is passed to callBack functions when triggering Window events
2. parentId (String or object):
   an existing group id or node reference (<g/> or <svg/> element) where the new Window object will be appended. This group does not need to be empty. The new Window group is appended to this group as last child. If the group id does not exist, the script creates a new empty parent group and appends it to the root element.
3. width (number):
   width of the Window in viewBox coordinates
4. height (number):
   height of the Window (incl. title and status bar) in viewBox coordinates
5. transX (number):
   the position of the left edge of the window in viewBox coordinates
6. transY (number):
   the position of the upper edge of the window in viewBox coordinates
7. moveable (boolean, true|false):
   indicates whether the Window may be moved or not
8. constrXmin (number):
   the left constraint, the constraints define the area where the Window can be moved within
9. constrYmin (number):
   the upper constraint
10. constrXmax (number):
    the right constraint
11. constrYmax (number):
    the lower constraint
12. showContent (boolean):
    value may hold true or false, indicates whether the Window content should be visible or hidden during window movements
13. placeholderStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the placeholder rectangle; this is the style of the placeholder rectangle that is displayed instead of the window content if showContent is set to true; could include CSS classes; example: var winPlaceholderStyles = {"fill":"none","stroke":"dimgray","stroke-width":1.5};
14. windowStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the Window rectangle; could include CSS classes; example: var windowStyles = {"fill":"aliceblue","stroke":"dimgray","stroke-width":1};
15. margin (number):
    a number in viewBox coordinates describing a margin. Used e.g. for placing text and buttons in statusBar or titleBar
16. titleBarVisible (boolean, true|false):
    indicates whether the Window should have a title bar
17. statusBarVisible (boolean, true|false):
    indicates whether the Window should have a status bar
18. titleText (String or undefined):
    a string specifying the Window title text
19. statusText (String or undefined):
    a string or undefined value specifying the Window status text
20. closeButton (boolean, true|false):
    indicates whether the Window should have a closeButton. The script loooks for an existing symbol with the id "closeButton" or creates a new closeButton in the <defs/> section if a symbol with this id does not exist. Please note that a closed Window still exists and can be opened again using the method .open()
21. minimizeButton (boolean, true|false):
    indicates whether the Window should have a minimizeButton. The script loooks for an existing symbol with the id "minimizeButton" or creates a new minimizeButton in the <defs/> section if a symbol with this id does not exist
22. maximizeButton (boolean, true|false):
    indicates whether the Window should have a maximizeButton. The script loooks for an existing symbol with the id "maximizeButton" or creates a new maximizeButton in the <defs/> section if a symbol with this id does not exist
23. titlebarStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the titlebar rectangle; could include CSS classes; example: var titlebarStyles = {"fill":"gainsboro","stroke":"dimgray","stroke-width":1};
24. titlebarHeight (number):
    a number value specifiying the titleBar height in viewBox coordinates
25. statusbarStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the statusbar rectangle; could include CSS classes; example: var statusbarStyles = {"fill":"aliceblue","stroke":"dimgray","stroke-width":1};
26. statusbarHeight (number):
    a number value specifiying the statusBar height in viewBox coordinates
27. titletextStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the titlebar text; could include CSS classes; should at least include a "font-size" attribute; example: var titletextStyles = {"font-family":"Arial,Helvetica","font-size":14,"fill":"dimgray"};
28. statustextStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the statusbar text; could include CSS classes; should at least include a "font-size" attribute; example: var statustextStyles = {"font-family":"Arial,Helvetica","font-size":10,"fill":"dimgray"};
29. buttonStyles (Array of literals with presentation attributes):
    an array literal containing the presentation attributes of the buttons; could include CSS classes; should at least include a "fill", "stroke" and "stroke-width" attribute; example: var buttonStyles = {"fill":"gainsboro","stroke":"dimgray","stroke-width":1};
30. functionToCall (function, object or undefined):
    a callBack function that is called after a window event occurs. The parameters for the callBack functions are as follows: id of the Window, eventType (string). In case of an object, the method .windowStatusChanged(id,evtType) is called. In case of a undefined value, no callBack function is executed. "evtType" may hold the following values: minimized, maximized, closed, opened, removed, moved, movedTo, resized, moveStart, moveEnd and created. For some event types, the callBack function is executed with a slight delay (200ms) to allow the Window to change state before executing the callback function. The events created and resized can be used to trigger the creation or update of the window decoration.

Methods

• .minimize(fireFunction):
  minimizes a Window, only the titleBar remains visible; parameter fireFunction of type boolean (true|false) specifies whether callBack function should be fired or not
• .maximize(fireFunction):
  maximizes/restores a minimized Window; parameter fireFunction of type boolean (true|false) specifies whether callBack function should be fired or not
• .close(fireFunction):
  closes the Window. The Window and its contents remain in the DOM tree, but are set to display="none"; parameter fireFunction of type boolean (true|false) specifies whether callBack function should be fired or not
• .open(fireFunction):
  opens a previously closed Window; parameter fireFunction of type boolean (true|false) specifies whether callBack function should be fired or not
• .resize(width,height,fireFunction):
  sets the window to a new width and height (number); note that we don't resize the content of the Window!; if a callback function exists, it is notified that the window was resized with the "resized" parameter; parameter fireFunction of type boolean (true|false) specifies whether callBack function should be fired or not
• .moveTo(coordx,coordy,fireFunction):
  moves the Window to the given value, both arguments are of type number; parameter fireFunction of type boolean (true|false) specifies whether callBack function should be fired or not
• .remove(fireFunction):
  removes a Window and all associated content. The attribute .removed is set to true and the Window object cannot be used any more and can't be restored; parameter fireFunction of type boolean (true|false) specifies whether callBack function should be fired or not
• .setTitleText(titleText):
  resets the titleText of a Window, the argument is a string value
• .setStatusText(statusText):
  resets the statusText of a Window, the argument is a string value
• .appendContent(node,inheritDisplay):
  adds a new node to the Window main group, the argument is either a node reference or a string representing an existing unique id, the second parameter is of type boolean and controls if the display attribute of the appended node should be set to inherit (in case of true) or not.
• .removeContent(node):
  removes an existing childNode from the Window main group, the argument is either a node reference or a string representing an existing unique id
• .insertContentBefore(node,referenceNode,inheritDisplay):
  inserts a new node before an existing childNode from the Window main group, the two arguments are either a node reference or a string representing an existing unique id, the second parameter (inheritDisplay) works as described at the method .appendContent()
• .hideContents():
  hides all content of the windowContentGroup by setting the display="none" attribute
• .showContents():
  shows all content of the windowContentGroup by setting the display="inherit" attribute
• .addWindowDecoration(node,mayTriggerMoving,topOrBottom):
  adds a window decoration to the Window. The first argument is either a String with an id pointing to the group containing the window decoration or a valid node reference. The second argument is of type "boolean" and indicates whether the decoration should allow moving of the Window. The third argument is of type string and may contain the values "top" or "bottom". This indicates whether the decoration is added on top or on bottom of the Window. In any case, it is added below the close, maximize and minimize buttons. After a window resize, the content developer is responsible to update the Window decoration, if necessary. This can be done by using the event types created and resized. See the functions buttonTextChange() and addOrUpdateWindowDecoration() for an example how to do this. If the group of the window decoration contains a group or element with the id "'decoGroupMinimized'+windowId" the element or group will be hidden or made visible during minimizing and maximizing the Window.

Useful Properties

• .windowGroup:
  node reference, the newly created group where the window geometry and subgroupse are appended.
• .windowMainGroup:
  node reference, the group where all the window background and content of the Window resides.
• .parentGroup:
  node reference, the parent group where the newly created window group is appended.
• .windowContentGroup:
  node reference, the group where the window content resides in. All content should be appended or removed to this group node.
• .windowTitlebarGroup:
  node reference, the group where the optional window titlebar and the buttons resides in (incl. closeButton, minimizeButton and maximizeButton)
• .titlebar:
  node reference, the rectangle of the titlebar. If not existing, it returns null
• .closeButtonInstance:
  node reference, the closeButton of the Window, can be used to reposition button for special window decorations.
• .maximizeButtonInstance:
  node reference, the maximizeButton of the Window, can be used to reposition button for special window decorations.
• .minimizeButtonInstance:
  node reference, the minimizeButton of the Window, can be used to reposition button for special window decorations.
• .decorationGroup:
  node reference, group containing the window decoration. If not existing, it returns null
• .decorationGroupMinimized:
  node reference, group containing the window decoration that should be hidden when minimized. If not existing, it returns null
• .width:
  number (viewBox coordinates), the width of the parent group, this property is currently read only. Setting a new value to .width does not automatically change the window size. Use the method .resize() for that purpose.
• .height:
  number (viewBox coordinates), the height of the parent group, this property is currently read only. Setting a new value to .height does not automatically change the window size. Use the method .resize() for that purpose.
• .titleBarVisible:
  boolean (true|false), indicates whether the titlebar is visible or not. Read only.
• .closeButton:
  boolean (true|false), indicates whether the closeButton is visible or not. Read only.
• .maximizeButton:
  boolean (true|false), indicates whether the maximizeButton is visible or not. Read only.
• .minimizeButton:
  boolean (true|false), indicates whether the minimizeButton is visible or not. Read only.
• .minimized:
  boolean (true|false), indicates whether the Window is minimized or not. Read only. To minimize or maximize the Window use the methods .minimize() or .maximize().
• .maximized:
  boolean (true|false), indicates whether the Window is maximized or not. Read only. To minimize or maximize the Window use the methods .minimize() or .maximize().
• .titleText:
  String, contains the current titleText of the Window.
• .statusText:
  String, contains the current statusText of the Window.

Current Limitation

Currently, the Windows cannot be resized by dragging the window corners. They can only be resized by script. This functionality will be added in a later version of the window. Furthermore, no scrollbars are added if the window content is bigger than the window size.

Version history

• 1.0 (2006-02-08): initial version
• 1.0.1 (2006-03-11): changed parameters of constructor (styling system): now an array of literals containing presentation attributes. This allows for more flexibility in Styling. Added check for number of arguments.
• 1.1 (2006-03-13): added additional parameter for .appendContent() and .insertContent(), added a .resize(width,height) method
• 1.1.1 (2006-06-15): added parameter fireFunction (of type boolean) to all methods that change the window state in order to allow script controlled changes without fireing the callback function
• 1.1.2 (2006-06-16): renamed this.parentId to this.parentNode; this.parentNode can now also be of type node reference (<g/> or <svg/> element)
• 1.2 (2006-08-22): added additional event types: moveStart, moveEnd and created, added method .addWindowDecoration(), improved documentation.
• 1.2.1 (2006-08-22): made constructor namespace aware by supporting svg:svg and svg:g as parent elements, fixed bug in .remove() method