Main features

Supported browsers

Introduction

Scope of the document

This document describes dhtmlxWindows system, defines its methods and global parameters.

Target readers

Target readers are project architects, development and QA staff.

What is dhtmlxWindows

dhtmlxWindows is a windowing system that enables user to work with several windows and their content at the same time.

This system allows windows to overlap, and provides means for the user to perform standard operations such as moving/resizing a window, sending a window to the foreground/background, minimizing/maximizing a window, changing window’s position, making a window modal and sticking a window.

Work with this system involves:

• Managing windows and their content;

• Applying built-in or user created skins to a window;

• Attaching content as External URL (Web-Page) or HTML-object to a window;

• Manipulating with window/buttons setting;

• Adding user defined buttons;

• Event handling.

Working with dhtmlxWindows

Initializing dhtmlxWindows

What files you need

Before writing any script commands related to window creation on page, you need to add some js and css files to your page. Exactly: <link rel="stylesheet" type="text/css" href="codebase/dhtmlxwindows.css"> <link rel="stylesheet" type="text/css" href="codebase/skins/dhtmlxwindows_[skin name].css"> <script src="codebase/dhtmlxcommon.js"></script> <script src="codebase/dhtmlxwindows.js"></script> If you need more then one skin to use, then add related css files also (in most cases one skin requires one css file).

Minimal initialization

A base for set of new windows can be created in the following way:

dhxWins= new dhtmlXWindows();

imagePath

Sets the full path to directory where necessary image files are located. Method setImagePath() should be used here:

dhxWins.setImagePath(String);

New window creation

While creating a new window with minimal initialization, a user should use createWindow() method and pass the following values:

• Window Id;

• Window position (x & y);

• Window width & height.

dhxWins.createWindow(String id,int x,int y,int width,int height);

User can set the header text to the newly created window using the command setText:

dhxWins.window(String id).setText(String text);

Default values

Default values in dhtmlxWindows are:

• Window control buttons (buttons “Park”, “Maximize” and “Close” are enabled and visible by default);

• Window icon (default icon is defined by the skin);

• Window maxDimension (default value is “auto”) and minDimension parameters (default value is 200x140px);

• The possibility to resize window (default value is “true”);

• The possibility to move window (default value is “true”);

• Window default skin (default value is “standard”).

Extended initialization

When creating a new window with extended initialization, a user should call the same commands described in Minimal initialization.

Additional parameters which can be defined are:

• Header icon;

• Allow/Deny resize;

• Allow/Deny move;

• Allow/Deny park;

• Hide/disable buttons.

Header icon

There is also the opportunity to specify any header icon if default icon is not suitable for user. This can be done in the following way:

dhxWins.window(id).setIcon(String iconEnabled, String iconDisabled)

Along with setting header icon user can choose to clear/remove it. In this case there will be just empty space instead of any header icon. To do this user should do the following:

dhxWins.window(id).clearIcon();

It is also possible to restore default window icon according the loaded skin:

dhxWins.window(id).restoreIcon();

Enable/Disable Resizing

By default window resizing is allowed.

Extended initialization allows user to deny window resizing by calling method denyResize():

dhxWins.window(id).denyResize();

Resizing of a window can be allowed again with the help of the following method:

dhxWins.window(id).allowResize();

Enable/Disable Moving

By default window moving is allowed.

User can deny window moving by calling the following method:

dhxWins.window(id).denyMove();

Window moving can be allowed again if user calls method allowMove():

dhxWins.window(id).allowMove();

Enable/Disable Parking

By default window parking is allowed.

User can choose to deny window parking using the following method:

dhxWins.window(id).denyPark();

Window parking can be allowed again with the help of the following method:

dhxWins.window(id).allowPark();

Hide/disable buttons

All default buttons are enabled. User can hide some of/all these buttons or disable them.

In order to hide/disable these buttons use the following methods:

dhxWins.window(id).button(“close”).hide();
dhxWins.window(id).button(“park”).disable();

Attach object

dhtmlxWindows allows users to attach objects to any window by method attachObject():

dhxWins.window(id).attachObject = function(objId, changeDisp);

Besides, user can set “display” property to “none” and pass changeDisp=true to attached element before attaching it to window.

In this case “display: none;” will be removed and the object will be shown immediately after attaching.

Attach url

There is the possibility to attach any external page to window with the help of method attachURL():

dhxWins.window(id).attachURL = function(url);

Global dhtmlxWindows parameters

Global parameters affect the entire system. Global parameters enable features, control information displayed in the graphical user interface.

Viewport (working area)

This parameter sets the invisible area that limits windows movements. Windows can’t be completely moved outside the viewport.

Users can specify the size of the viewport. By default the size of the viewport occupies the document.body and automatically changes its size when document.body’s size changes.

To enable user-defined viewport evoke the following code:

dhxWins.enableAutoViewport(false);
dhxWins.setViewport(10, 10, 1260, 500);

keepInViewport() method, when is set to “true”, permanently locates a window within the viewport (the window can’t be moved outside the viewport).

window(id).keepInViewport(true/false);

By default this method is set to “false”. Thus, all windows can be moved outside the vieport in such a way that only a tiny part of window’s header will be seen.

Skins

This parameter allows users to change dhtmlxWindows skins. There is a set of default skins among which user can choose one with the help of method setSkin():

dhxWins.setSkin(String skin);

Skins are able to be changed “on the fly”, i.e. user can change them very easily in the process of work. There is no need of any other actions except calling of setSkin() method.

There is also the possibility for users to create their own skins.

The following built-in skins are available in dhtmlxWindows:

• web

• aqua_dark

• aqua_orange

• aqua_sky

• modern_red

• modern_black

• modern_blue

• clear_blue

• clear_silver

• clear_green

• standard

Accessing single window

User can access window in the two following ways:

• Using direct link to object that will be returned by the createWindow() function:

var dhxWins = new dhtmlXWindows();
var win = dhxWins.createWindow(id,…);

• Through the global scope calling window() function:

var dhxWins = new dhtmlXWindows();
dhxWins.window(id);

Thus, user can access this window using “win” variable or by calling window() function.

Regardless of the way the window is accessed, the content of “win” variable and windows.window(id) will be equal.

Window iterator

Method forEachWindow() calls user-defined function for every existing window passing window handler into it.

forEachWindow(function(winHandler){winHandler.show();})

Changing window dimension

Default min- and max Dimensions are set in dhtmlxWindows.

The user has the possibility to set his own min and max Dimension parameters to a window by calling methods setMaxDimension() and setMinDimension():

dhxWins.window(id).setMaxDimension(int width, int height);
dhxWins.window(id).setMinDimension(int width, int height);

Also if the user wants to change window dimension, he/she should use the command setDimension() and pass width & height values:

dhxWins.window(id).setDimension(int width, int height);

There is also a method to get window dimension (will return array (width, height)):

dhxWins.window(id).getDimension();

The following methods can also be used to get min and max Dimensions:

dhxWins.window(id).getMaxDimension();
dhxWins.window(id).getMinDimension();

Notice: window will be able to occupy the whole viewport after minimizing if user sets maxDimension to “auto”:

dhxWins.window(id).setMaxDimension(“auto”, “auto”);

In this case the window becomes not resizable (only in maximized state).

Notice: if user changes window dimension in such a way that it cannot display the whole title text, the text will be cut.

Changing window position

As with window Dimension, it is available to change window Position. In order to do this method setPosition() must be called with values x and y:

dhxWins.window(id).setPosition(int x, int y);

There is also a command to get window position (will return Array(x, y)):

dhxWins.window(id).getPosition();

Window parking

If user wants to park window, he/she should use the command park().

If the window was parked up, this command makes it park down and vice versa:

dhxWins.window(id).park();

Window minimizing/maximizing

To minimize/maximize a window user should call the following methods:

• maximize();

• minimize();

dhxWins.window(id).maximize();
dhxWins.window(id).minimize();

Bringing window to top/bottom

User can bring any window to top with the help of method bringToTop():

dhxWins.window(id). bringToTop ();

In this case the window will be automatically focused.

Method bringToBottom() brings any window to bottom:

dhxWins.window(id). bringToBottom ();

In the situation when this method was applied to the top window, the window that lies right after the top one occupies its position and becomes the top window.

Some peculiarities of these two methods are revealed dealing with sticked/unsticked windows.

Window sticking/unsticking

The user has the opportunity to stick/unstick window - to place it always on top. To do this a user should use methods stick() or unstick().

dhxWins.window(id).stick();
dhxWins.window(id).unstick();

If there is any window that was made “sticked” in the system, global window behavior will be the following:

• All windows will be divided into 2 groups: sticked and unsticked;

• Sticked windows (even unfocused ones) will always be positioned over the unsticked ones;

• Method bringToTop() will place sticked window on top among the other sticked ones. As for unsticked window (in case there is at least one sticked window) it will be placed on top of all unsticked windows but below sticked ones;

• Method bringToBottom() will work the following way with sticked window: it will be brought to bottom but will be placed over any unsticked window;

• Any sticked/unsticked window will always be placed under any modal window.

Modal/modeless window

There is the possibility to make window modal calling method setModal():

dhxWins.window(id).setModal(Boolean state);

Any modal window has the following features:

• Only one modal window is allowed at a time;

• If user wants to set modal option to any other window, this option should be removed from the current modal window. Or current modal window itself should be removed;

• Any modal window will always be placed over any other window (even sticked ones);

• Modal window requires the user to interact with it before he/she can return to operating any other windows (i.e. this window is always focused).

The value “true” in method setModal() makes a window modal while the value “false” makes it modeless.

Topmost/Bottommost Window

User is able to get handler of the topmost window with the help of the following method:

dhxWins.window(id).getTopmostWindow();

To get handler of the bottommost window user should call the following method:

dhxWins.window(id).getBottommostWindow();

Buttons settings manipulating

Accessing the button

Button can be accessed in the following way:

var btn = dhxWins.window(id).button(id);

Default buttons ids are:

• “park” for “park” button;

• “close” for “close” button;

• “help” for “help” button;

• “stick” for “stick” button;

• “sticked” for “sticked” button (pressed “stick”, used for “unstuck” action);

• “minmax1” for “maximize” button;

• “minmax2” for “minimize” button.

Showing/hiding buttons

There is the possibility to show/hide a button by calling the following methods:

dhxWins.window(id).button(id).show();
dhxWins.window(id).button(id).hide();

User buttons also inherit these methods.

Button enabling/disabling

The button can be enabled/disabled by user:

dhxWins.window(id).button(id).enable();
dhxWins.window(id).button(id).disable();

User buttons also inherit these methods.

Notice: in some cases button enabling/disabling is determined by Object.

For example, when the window is Parked Up, resize buttons are inactive/disabled. But they become active/enabled when the window is Parked Down. Thus resize buttons are disabled by the Object.

Creating user buttons

Making set of button images

This example will show user how to create their own buttons for a window.

1. To get started user should decide for which skin the button will be created. Take, for example, the skin “Web”.

2. Then user should get to know the dimension of buttons for the chosen skin.

3. Each button can be divided into “active” & “inactive”. Besides, all buttons have the following states: “default”, “over_default”, “over_pressed”, “disabled”.

Thus, there must be 8 skins for each single user button:

• Active:

• Default;

• Over default;

• Over pressed;

• Disabled.

• Inactive:

• Default;

• Over default;

• Over pressed;

• Disabled.

4. Next user should name the newly created button. For example, the name of the button can be “tray”.

5. The next step is to create the main folder for the new button (for example, “tray_button”) and 2 subfolders in it called “active” and “inactive”.

6. Then user is to create 4 subfolders in both “active” and “inactive” folders:

• btns_default;

• btns_disabled;

• btns_over_default;

• btns_over_pressed.

As a result there will be the following tree:

tray/

active/

btns_default/

btns_disabled/

btns_over_default/

btns_over_pressed/

inactive/

btns_default/

btns_disabled/

btns_over_default/

btns_over_pressed/

7. Now user should create 8 GIF files with button skins for each button state. Then each GIF file should be placed to each folder according to state. Single file name should be used for each skin, for example: “btn_tray.gif”.

8. After this the tree will be presented in the following way:

tray/

active/

btns_default/

btn_tray.gif

btns_disabled/

btn_tray.gif

btns_over_default/

btn_tray.gif

btns_over_pressed/

btn_tray.gif

inactive/

btns_default/

btn_tray.gif

btns_disabled/

btn_tray.gif

btns_over_default/

btn_tray.gif

btns_over_pressed/

btn_tray.gif

9. Now when button skins are created, user should proceed to CSS file creation.

CSS file creation

This example is going to show user how to create CSS file for buttons.

1. User should find template CSS file dhtmlxwindows_user_button_template.css and save it with a different name. For example, it can be “user_button_tray.css”.

2. Then user should modify this CSS file in the following way:

• Replace %skin% with the skin name (in our example, we chose “web” skin);

• Replace %button_root_folder% with the name of the root folder created by user (in our example it’s “tray”);

• Replace %button_name% with the name of the created button (in our example it’s “tray”);

• Replace %button_filename% with name of the created GIF files (“btn_tray.gif” in out example);

• Link this newly created CSS file from index page.

Adding User Button

To add this newly created button to a window user should use the following method:

dhxWins.window(id).addUserButton(id, position, tooltip, name);

This method takes the following parameters:

• id – id of the newly created button (in our example it can be “tray”);

• position – the type of this parameter is int. This parameter defines the place of the button on the caption bar. (left to right: 0 – the first button, 1 – the second, etc);

• tooltip – this parameter sets the title that appears when user hovers the mouse over the button;

• name – the name of the button (in out example it is “tray”).

Adding event to button

User can attach an event to the newly created button in the following way:

dhxWins.window(id).button(id).attachEvent(“onClick”, handler);

User can also remove an event from any user-created button:

dhxWins.window(id).button(id).detachEvent(“onClick”);

Any user-created button can be removed in the following way:

dhxWins.window(id).button(id).removeUserButton(id);

Besides, all default buttons methods will be available for user-created buttons as well:

dhxWins.window(id).button(id).show();
dhxWins.window(id).button(id).hide();
dhxWins.window(id).button(id).isHidden();
dhxWins.window(id).button(id).enable();
dhxWins.window(id).button(id).disable();
dhxWins.window(id).button(id).isEnabled();

Removing User Button

To remove any user button from the window user should call the following method:

dhxWins.window(id).removeUserButton(id);

Event handling

Default events

Default events signal various actions, such as the user clicking a button to Park window or a window being closed. Default events are usually button events.

Button events can be as follows:

• onClick. The onClick event handler executes the specified JavaScript code or function when the user clicks the left mouse button on the object.

Default events can be redefined by user, who can choose to assign other user-defined events instead. In this case, default events will be ignored until they are restored by user.

Redefine default button event

User can choose to redefine default button event adding any user’s event instead.

To redefine button default event user can use attachEvent() method:

dhxWins.window(id).button(id).attachEvent(eventName, handler);

Adding window events handlers

The entire point of an event is to inform a handler that something has happened to a component in the GUI.

A handler can figure out what exactly happened and respond in a meaningful way.

The list of events to which user-defined handlers can be attached is given below:

• onMoveFinish – occurs when the window movement was finished;

• onResizeFinish – occurs when the window resizing was finished;

• onFocus – occurs when the window was focused by user;

• onParkDown/onParkUp – occurs when the window was parked down/up;

• onMaximize/onMinimize – occurs when the window was maximized/minimized;

• onShow/onHide – occurs when the window was shown/hidden;

• onClose – occurs before the window was closed;

• onHelp – occurs when user clicks the “help” button.

Adding global event handlers for windows

User can add global event handlers for windows. This can be done in the following way:

dhxWins.attachEvent(eventName, handler);

Adding personal window event handler

If there is a window to which user wants to assign a special handler, this can be done by adding the handler to the window directly.

While other windows will be calling global handlers, this window with personal handler will call this personal handler:

dhxWins.window(id).attachEvent(eventName, handler);

Restore global event handlers

User can detach personal event from window.

In this case global event handler will be restored for this window, i.e. when personal handler is removed from the window, the widow will call global handler.

dhxWins.window(id).detachEvent(eventName);

Remove global handlers

Global handlers can be easily removed with the help of the following method:

dhxWins.detachEvent(eventName);

Understanding events handlers priority

In the situation described above windows w2 and w3 will call “globalHandler” when they are focused.

Window w1 will call personal “w1Handler” when it is focused.