Widget module (last update 30/06/02)

Description:

The widgetManager object provides a means to create and manipulate window objects. This module also includes the constructors for cascading menus and statusbars which can be attached to windows. The Menubars can also be attached to the page as floating items! The windows can be totally reskinned very easily, and the behaviour of the gui elements can be altered by the use of a config file.

Please be aware that this module is for DOM2 browsers only. This is currently Internet Explorer 5/6, Netscape 6 and Mozilla. As always, Opera is not supported (and never will be) due to its substandard Javascript/DOM implementation, but hopefully Konqueror will soon be fully supported.

To use:

<script language="Javascript" src="gamelib_widgets.js"></script>

Unlike the rest of Gamelib, you do not need the gamelib_core module to use this module. It's totally self contained. You also don't need the gamelib_mouse module unless you need mouse events for other elements like sprites and layers. The WidgetManager also uses a separate config file called "setup.html" that it uses to set up numerous switches and values that control its look and feel, as well as a couple of directories that hold the images for window decorations and menu icons. The directory that holds these must be passed to the WidgetManager when it is initialised as follows:

InitWidgetManager('style/0','Init2()');

As you can see, we use the convenience function "InitWidgetManager" to handle the initialisation. It creates an instance of "WidgetManager" called "widgetManager" (notice the capitalisation). It then loads in the setup.html file from the directory passed as the first parameter (here it's "style/0" - no trailing slash). Finally it calls the function passed to it as the second parameter ("Init2()" here). Be aware that it takes a few seconds to load in the setup.html file, so you cannot use the widgetManager immediately after this statement. In this case, you would start the script that uses widgetManager from the function "Init2()".

You then create a window (called "myWindow" in this example):

var myWindow=widgetManager.createWindow(500,400,"A Test!",null,null,"test.html",200,100);

The above creates a Gl_Window object. The 8 values passed to the Gl_Window creation function are as follows:

(1) width of window
(2) height of window
(3) Text for the title bar
(4) X position (optional)
(5) Y position (optional)
(6) Page to load into window as it's created (optional)
(7) Zoom X position. This is the X position from which the "Zoom" animation will start. (optional)
(8) Zoom Y position. This is the Y position from which the "Zoom" animation will start. (optional)

Now we have a window, we can add a menuBar object to it if we wish (see menuBar docs for an example of creating a menuBar object):

myWindow.addMenuBar(myMenuBar);

If we wish, we can also add a status bar!

myWindow.addStatusBar('Hi there!');

A couple of last points: The directory given when the widgetManager is initialised must contain the setup.html file and 2 subdirectories. One subdirectory is called window_decorations, and the other is called menu_icons.

The images in window_decorations have fixed names, and are used to construct the Gl_Window objects. There is an example in the gamelib.zip file. The icons for menu items go into the menu_icons subdirectory. These can be called anything you like, but should be gif files, not jpegs! Please read through the setup.html file, it's very well documented, and must be edited if you intend to create new skins, or if you wish to alter the behaviour and style of the Widget objects!

List of Objects managed by WidgetManager

Gl_Window
Gl_MenuBar

List of public methods for WidgetManager

addEvent
createWindow
destroyWindow
doWindowPrint
doWindowSearch
forwardResizeEvents

List of public properties for WidgetManager

activeWindowIX
browserHeight
browserWidth
windowsOnScreen

Descriptions of public methods for WidgetManager

Method Parameters Description
addEvent DOM object, String, Function Reference, Boolean A generic method for adding event listeners to DOM objects. This includes a fallback for the Mac version of Internet Explorer, which doesn't actually have a proper method for doing this. The first parameter is a reference to a DOM object, next is a string representing the type of event to listen for. So, for a mouseover event, this would be "mouseover" (no "on" prefix). The third parameter is a reference to the function that will handle the event. The last parameter should be true if the event should not bubble to the next listener (if there is one for this event).
createWindow Numeric, Numeric, String, Numeric, Numeric, String, Numeric, Numeric The WidgetManager should always be used to create and destroy Gl_Window objects, as it needs to manage the desktop and all windows in use upon the desktop. Use this method to create a new Gl_Window. There is a maximum of 8 arguments for this method. Only the first 3 are required, all others are optional. The list of arguments is given below:
  • Width of window.
  • Height of window.
  • Title text.
  • Initial X position.
  • Initial Y position.
  • URL of page to load as window is created.
  • X position that window should "zoom" out from.
  • Y position that window should "zoom" out from.
destroyWindow Numeric This will destroy a Gl_Window. The parameter should be the index of the window in the widgetManager's windows[] array. If no parameter is used then current active window will be destroyed. All Widgets have destroy() methods which cascade down, so when a window is destroyed all its child objects, including statusBar and menuBar will also be destroyed. You should never call a Gl_Window's destroy method directly.
doWindowPrint none With MS Windows with Explorer, this will send the contents of the current active window to the printer. With other browser/Operating systems it will pop up a new window containing the contents of the active window ready for printing.
doWindowSearch none This will pop up a search dialog box. Once filled out and the submit button is pressed a search will be perfomed on the contents of the active window. Any matches will be highlighted in the window itself.
forwardResizeEvents String When the widgetManager is initialised, it automatically traps window resize events for internal use. If you need another function called whenever a resize event occurs, this method can be used. The parameter passed is a string containing the function to be called.

Descriptions of public properties for WidgetManager

Property Data Type Read/Write Description
activeWindowIX Numeric R The index of the current active window. This is the window's position in the widgetManager's windows[] array.
browserHeight Numeric R Height of the browser window.
browserWidth Numeric R Width of the browser window.
windowsOnScreen Numeric R Number of windows currently on screen. This includes shaded windows.