Layer Module (last update 12/05/01)

Description:

The layer object provides a means to create and manipulate layer objects. These have some similarities to sprites, but they are mostly different in their purpose and abilities. Use this object if you require movable layers which can have new content written to them, or loaded in from other files.

To use:

The layer object is included in the core module, and so is available as soon as you link in the gamelib_core.js file:

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

You then create a layer (called "mylayer" in this example):

mylayer=new Gl_layer(0,0,100,'Test');

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

(1) x position of layer
(2) y position of layer
(3) width of layer
(4) Anything you like that you wish to be inserted in the layer's body. This could be text, images, or whatever. If you don't want anything in there, just use "".

List of methods for layers

append
clip
dragType
follow
hide
lockLayer
load
makeDraggable
makeUndraggable
moveTo
resizeTo
setBackground
setBgcolor
setOpacity
setXlimits
setYlimits
setZ
show
stopFollowing
unlockLayer
write

List of properties for layers


clipbottom
clipleft
clipped
clipright
cliptop
draggable
height
innerHTML
lock
lockxoff
lockyoff
ob
onclickdown
onclickup
onmouseout
onmouseover
raw
URL
width
x
xmax
xmin
y
ymax
ymin
z

Descriptions of methods

MethodParametersDescription
appendString, Numeric

Appends new html content (first argument) to the current content of the layer. (only works with Netscape 4 if the previous content was WRITTEN.) The first argument is a string, the second an offset into the original content to add the text. If the second argument is left out, the new content is added to the end of the old.

Remember, if you have html tags in the old content, and corrupt them with new content added in the wrong place, results will be at best unsightly!

clipNumeric, Numeric, Numeric, Numeric Clips the layer, arguments 1 and 2 are the clips in x axis, 3 and 4 are the clips in y axis. * Note: See also clipleft, clipright, cliptop, clipbottom and clipped properties.
dragTypeString/Numeric

How the layer can be dragged (see draggable property below which must be set first). The dragType (if numeric) can range from 0 to 2:

0 or "normal" = normal dragging (default)
1 or "vertical" = Layer can only be dragged in the y axis
2 or "horizontal" = Layer can only be dragged in the x axis

followObject, Numeric, Numeric This method causes a layer to remain a set distance from a gamelib mouse or sprite object (passed as the first argument) wherever it moves around the page. x (second argument) and y (third argument) are the relative distance the layer is from the Object's coordinates. As always though, the layer cannot exceed its Xlimits or Ylimits (see setXlimits() and setYlimits() methods) * Note: If you wish one layer to move in sync with another, you should use the lockLayer() method; it's far more efficient. See also stopFollowing() method
hide(none)Hides the layer
lockLayerObject, Object, [...] This locks other layers (passed as the arguments) to this one. So if this layer moves, then the locked layers will move in unison. Eg, if this layer was at position 100,100 and a layer you lock is at 150,150, then the locked layer will always be 50 pixels to the right and below this layer when it moves. Subsequent calls to this method will add extra layers to the list. Note: layers cannot exceed their x and y limits (see xmin, xmax, ymin, ymax) even if they're locked to another layer. See also unlockLayer().
loadString, Boolean, Numeric Loads an external html file (passed as first argument) into the layer. If the second argument is true, then browser will be forced to load from the server, and not use the cache. The third argument is the maximum time (in seconds) to wait for this page to load before giving up.

Don't try to load framesets into layers, it'll all end in tears :-) The old Gl_loadWait variable is redundant as of version 1.998. It still exists, so as not to break old scripts, but will now always be null, as the gamelib uses an internal queue to manage the loading of multiple layers. Since gamelib uses the queue, you may now start as many layers loading as you wish, and they will be loaded in sequence, and any that fail to load will not cause the script to break.
makeDraggable(none)Makes the layer draggable!
makeUndraggable(none)Stops the layer from being draggable!
moveTo Numeric, NumericMoves the layer to position x,y (passed as the arguments). You cannot move a layer outside its x and y limits (see xmin,xmax,ymin,ymax).
resizeToNumeric, Numeric Resizes the layer to a set width and height (passed as arguments). This fixes the layers size, so any content the layer has, or is added to it in the future will not resize it. The only time it will resize to new content is if it's loaded (using the load() method)
setBackgroundString

Sets the layer's background image (passed as a URL in the String argument) like a background of a normal web page.

* Note: I've noticed that IE5 seems unhappy when moving layers which have background images set. This is not a bug with the gamelib, but a bug with the browser's rendering engine. It constantly tries to reload the image, resulting in slowdown. The best work-around I can suggest is to use 2 layers, the backmost one having an image, and the front one transparent. Not ideal, but there... Only set background images with layers that are going to be mostly static.

setBgcolorStringSets the layer's background color. The color argument is a string, so: mylayer.setBgcolor("#000000") would set a black background color.
setOpacityNumeric This sets the opacity of the layer. The number passed as an argument can range from 0 (completely transparent) to 100 (completely opaque). * Note: This method has no effect with Netscape 4 (browser doesn't support transparency)
setXlimitsNumeric, Numeric Limits the layer's x movement. Layer cannot move left furthur than the first argument, or right furthur than the right argument - MINUS its width.
setYlimitsNumeric, Numeric Limits the layer's y movement. Layer cannot move up furthur than the first argument, or down furthur than the second argument MINUS its height. Be aware that loading new content into a layer might well increase its height, and so it might be moved to keep it within its limits after loading...
setZNumericSets the z-index
show(none)Reveals the layer
stopFollowing(none)This method stops the layer following another screen object
unlockLayer Layer Object/null This unlocks one or more layers that are locked to this. If no layers are passed, then all layers locked to this will be unlocked! This is handy when you just need a quick way to unhook things.
writeStringReplaces the content of the layer with new html content

Descriptions of properties

PropertyData TypeRead/WriteDescription
clipbottomNumericRThe amount in pixels the layer is clipped from its bottom edge
clipleftNumericRThe amount in pixels the layer is clipped from its left edge
cliprightNumericRThe amount in pixels the layer is clipped from its right edge
cliptopNumericRThe amount in pixels the layer is clipped from its top edge
clippedBooleanRSet to true if the layer has been clipped. * Note: The resizeTo() method also clips layers
draggableBooleanR/W If set to true, the layer is draggable! There must be a mouse object created before this will work. See also dragType() method. * Note: a layer cannot be dragged beyond its x and y limits. It's also now better to use the new makeDraggable() and makeUndraggable() methods, rather than setting the property yourself
heightNumericRReturns the current height of the layer. Clipping is ignored
innerHTMLStringR Returns the html content of the layer. Works with Netscape 4 but only if you have WRITTEN the content, not loaded it!
lockObjectRReturns the layer object that's locked to this layer
lockxoffNumericRReturns how far away in the x axis the locked layer is
lockyoffNumericRReturns how far away in the y axis the locked layer is
obObjectR/W This is a reference to the layer's style properties. To use this succesfully, a good knowledge of the browser DOMs is necessary.
onclickdownStringR/W A string which contains command(s) to be executed when the mouse button is pressed while the mouse is over the layer.
onclickupStringR/W A string which contains command(s) to be executed when the mouse button is released while the mouse is over the layer.
onmouseoutStringR/W A string which contains command(s) to be executed when the mouse moves away from the layer.
onmouseoverStringR/W A string which contains command(s) to be executed when the mouse moves over the layer.
rawObjectR/W This is a reference to the layer object itself. There are differences from the ob property with IE4/5, but not netscape 4x. A thorough working knowledge of browser DOMs is required to use this.
URLStringRURL the layer has loaded. (see load() method above)
widthNumericRReturns the current width of the layer. Clipping is ignored
xNumericR/WReturns the x position of the layer
yNumericRReturns the y position of the layer
zNumericRReturns the z index of the layer
xminNumericRLowest limit layer can move to or be dragged to in x axis. Default=0
xmaxNumericRHighest limit layer can move to or be dragged to in x axis. Default=1000
yminNumericRLowest limit layer can move to or be dragged to in x axis. Default=0
ymaxNumericRHighest limit layer can move to or be dragged to in x axis. Default=1000