JS: Dhtml: The ULMA Powers Subroutines (Javascript)

The scripts I feature here rely on my ULMA approach: therefore you need to load somewhere after your body tag either an external javaScript files which holds all the ULMA core functions, or you have to paste all of them inline with a <script> tag soon after the tag <body> (and preferably also after you've defined your layers): for all the details and the ULMA codes, please do refer to my ULMA [Universal Layer Management Approach] Procedures: you can neither understand nor use these scripts if you are not using ULMA.
So you must have layerManagers, and they must be abilitated:
var foo;
foo=new layerManager("foo", "layerIDhere");
foo.abilitate();

Now the functions we feature here: first the explanations, as for their relative codes, scroll to the test form at bottom of the page and select the name of the function from the menu: in the big textarea would appear its code (you will realize immediately as soon as you scroll there).

distances()

Purpose of the Script

Provided either two layerManagers, whose top/left position coordinates the script can draw on its own, or directly two sets of top/left coordinates of two locations on the screen, the script produces the length of the segment in between the two given points, plus other data relative to the length of this segment.

Arguments

distances(top1, left1, top2, left2)
distances(layerManager1, layerManager2)

LayerManagers, if used, must be the ULMA layerManagers object themselves: that is, not their names in between apex, passed as strings, but the layerManagers object themselves. If your layer managers are, say, foo1, foo2: distances(foo1, foo2)

Usage and Invoking

Returns an array of as many as 6 entries:

entry[0] is the distance between the two points
entry[1] is the difference between the top coordinates of the two objects or coordinates set (that is: if a layer is positioned at top=100 and the second at top=40, yields 60 namely the difference between the tops)
entry[2] the same as tops but this time as far as left coordinates are concerned (namely the difference between the distances of the two objects form the left side of the window)
entry[3] is the gradient, namely the inclination of the segment
entry[4] is the distance between tops with a plus or minus algebraic sign before it
entry[5] the distance between lefts with algebraic sign before it

Both [4] and [5] assume the first set of coordinates are the leading ones, namely that we are figuring that the object which is located at such coordinates could/would move towards the second object (the second set of coordinates, that is): therefore a minus sign in, say, entry[5] which is the entry that reports about left coordinates positions, would mean that to make the left coordinate of the first object coincide with the left coordinate of the second object, you should subtract such amount from the first object left coordinate, or add it in case the sign is positive: after such a move their left coordinates would coincide. Same as foresaid in case of top position coordinates (entry [4]).

If [4] or [5] (as well as [1] and [2] in this case) would yield zero, means that the two objects , either as far as top axis or left axis are affected, lay on the same axis.

To read/grab one entry, say [2]:
distances(layerManager1, layerManager2)[2]
or you can assign the whole function to one variable like, say:
xxx=distances(layerManager1, layerManager2)
xxx[2]

midpointsCoords()

Purpose of the Script

You have a segment (the function can draw it taking avail of distances, thus you must have distances included in your script or midpointsCoords would not work), the function can find the midpoint of the yielded segment, or alternatively you can specify an amount of the given segment to search for (if segment is, say, 200pixels, you might want to find the coordinates of the point where the segment length is, say, 35pixels), and the function will find the top/left coordinates that are at that given point (calculated both starting from layer1 and from layer2, and producing both results so you can decide which one to pick) using the pythagoras theorem.
Very useful if you have two layers and an unknown distance between them and an unknown inclination of the segment that ideally joins the two layers topleft corners, and you want to position a third layer on that axis!

Arguments

midpointsCoords(top1, left1, top2, left2, search)
midpointsCoords(layerManager1, layerManager2, search)
midpointsCoords(top1, left1, top2, left2) //no search, assumes middle!
midpointsCoords(layerManager1, layerManager2) //no search, assumes middle!

Usage and Invoking

Returns an array of 5 entries, or boolean false if you provided less than 2 arguments at least.

[0]: top coordinate of the resulting point, calculated starting from layer1
[1]: left coordinate of the resulting point, calculated starting from layer1
[2]: top coordinate of the resulting point, calculated starting from layer2
[3]: left coordinate of the resulting point, calculated starting from layer2
[4]: yields zero or 1: if zero, the point you were searching for was within the segment boundaries, otherwise if it was out of those boundaries, returns 1 to flag that in case you might need to know.

To get one entry same as for distances:
var foofoo=midpointsCoords(top1, left1, top2, left2, search);
foofoo[index]

Keep in mind that if you're checking the midpoint of two layers, this midpoint is the midpoint between the topleft corners of the two layers: if the two layers have one side in common, you might wrongly argue there is no distance between them: of course there is: the midpoints are calculated from topleft corners.

layerCenterer()

Purpose of the Script

Must be enabled as a new managerMethod (see ULMA).
It perfectly centers its layerManager on the second layer passed as parameter named overThis: such parameter must be the layerManager itself of the layer which has to go behind the first layerManager: that is, not its name in between apex, passed as string, but the layerManager object itself (see distances for more?).

Arguments

layerManager1 is placeholder for whatever layerManager name you may have initialized by ULMA for this process.
layerManager1.layerCenterer(overThis, zindexing, onlyReturn)
overThis must be a second layerManager object.

Usage and Invoking

Returns an array of two entries carrying the top and left coordinates the first layer has to be moved to in order to be centered on the second.
If you set to 1 the argument called onlyReturn, it just returns those coordinates without physically centering the layer.
Argument named zindexing if not set, leaves the layers z-indexes (stack position) unaffected. If set to 1, stacks the layerManager1 above the layer passed as overThis argument, if set as -1, stacks below.

ULMAMassCenterer()

Purpose of the Script

Positions in the middle of the page, either horizontally or vertically or even both, a whole set of layers, and can additionally add defined spaces in between them.

Arguments

ULMAMassCenterer(layer1, layer2, layer3, layer4, space, progressiveDirection, progressionW, progressionH, addTop, addLeft)
you can include as many layerManagers as you prefer layer5, layer6..., or just one as well: it wants you to pass them as layerManagers object: the layerManager itself, that is, not its name or the layerName. It accepts you pass your set of layers as an array, or as a mix of single objects and arrays of objects.

Then space, which defaults to zero, to include space between layers.

Then progressiveDirection if not set or set as zero: tiles horizontally by default, if set as 1 tiles vertically, if set as 2 tiles both vertically and horizontally!

progressionW: defaults to zero, if set increases the horizontal space between layers by that amount at each subsequent layer.

progressionH: defaults to zero and does the same as above but horizontally.

addLeft: adds to the left coordinates of the leading layer the passed amount: defaults to zero.

addTop: same as above but for the top coordinate.

The script positions adding page offsets by default: to avoid this, use this formula:

ULMAMassCenterer(layer1, layer2, layer3, alyer4, space, progressiveDirection, progressionW, progressionH, eval(-offsetY), eval(-offsetX))

whereas the snippets within eval() passed as the last two arguments must be left and copied exactly as such if you're using ULMA, and all the previous arguments still have to be customized obviously.

Usage and Invoking

See section above.

ULMARun()

Purpose of the Script

Performs a massive call to run() on all (or defined subset of) ULMA objects.

Arguments

In between quotes you pass the names of the methods that you want to run (accepts also an array, or a mix of names and array of names, as long as its entries are methods names between quotes and methods are, obviously, defined in the script!): if they are not ULMA enabled, it even enables them on all layers prior to running them.

Runs them on all layers by default.
If you want to limit the amount of layers, pass an argument like this:
First your methods you want to run, then:
"#"
After that you can pass a selective amount of layerManagers.
NOTE: this time layerManagers (or also layer IDs) have to be passed as strings, that is: names in between quotes! If you have a layerManager such as:
foo=new layerManager() etc etc..., then:
ULMARun("aMethod", "moreMethod", "#", "foo")

So to run given method on all layers:
ULMARun("myMethod1", "myMethod2")
or for selective layerManagers:
ULMARun("myMethod1", "myMethod2", "#", "managerName1", "managerNameX")
It accepts if you pass arrays of methods or arrays of layer managers names or of layerIDs, even in mixed order (names, array, array, name, array...)

Usage and Invoking

See above.

ULMAExe()

Purpose of the Script

Performs a massive call to exe() on all (or defined subset of) ULMA objects.

Arguments

First argument must be the method, and it accepts you pass only one method at a time, not as ULMARun which accepts more methods: this beacuse whereas calls to run do not accept arguments in ULMA, calls to execute accept arguments and therefore given a method to execute, you have to pass along also its possible arguments.
So after you pass the name of the method to execute in between quotes, you pass all its possible arguments. Now the function executes such method on all layers, or if you include another argument as: "#" after it you can specify layers as etiehr layerManagers names or layerId, but once again in between apex.
ULMAExe("methodName", arg1, argX)
ULMAExe("methodName", arg1, argX, "#", "managerName1", "managerNameX")
If you specify layer managers, accepts array too, or a mix of names and arrays.

Usage and Invoking

see Above.

ULMAIn()

Purpose of the Script

Massive call to built in methods on ULMA Objects.
Main built in methods in ULMA are:

enable
relocate
still
setAttributes
alias

Arguments

First argument the name of the built in method you want to execute: it accepts you pass only one built-in methods: you have to be sure you passed an ULMA built in method name in between apex and not other type of personally defined methods or bundled methods like shower. I repeat, default built in methods, such as: enable, relocate, still.
After that you add as further arguments passed to ULMAIn, the method arguments meant to be passed to the built in method passed as first argument.

ULMAIn( "BuiltInFunc", "built in func ARG 1 if any", "other built in func ARG?") //etc...

Remember this critical factor: if your passed argument must be meant as a string, pass them nesting single apexes inside the double apexes (and do not add spaces): example:
ULMAIn("alias", "'abilitate'", "'anotherName'")
You may have noted the sequences:
" plus '
and
' plus "

You can specify specific layers so that only them would be affected by the given ULMAIn call, and you can do it by using the trick of the "#"sign as depicted for ULMAExe

ULMAIn( "BuiltInFunc", "built in func ARG 1 if any", "other built in func ARG?", "#", "layerID1", "layerIDx") //etc...

read ULMAExe procedures to pass arguments: method, arguments of the method, optional # sign, optional layers.

ULMA has also a built in method named abilitate: do not pass it at all for if ULMAIn finds a non abilitated layer, it abilitates it by default.
Instance: to run a massive enable of a specified amount of methods (enable is a built in ULMA function that gets method names as arguments, for it enables them to be considered as methods that belong to the stock of the layerManager upon which enabling has been called):

ULMAIn("enable", "method1", "method2", "method3")

which would enable on all layer managers method1, method2, method3!
If you specify layer managers after having passed in between strings a # sign as a discriminatory argument, ULMAIn accepts array of layerManagers names too!

Usage and Invoking

See above.

ULMAStatus()

Purpose of the Script

If a layerManager is still undergoing a run() method, returns TRUE (status active).
If no layerManager was found engaged in whatever running method, returns FALSE (quiet status).

Arguments

ULMAStatus()
Optionally, you can pass layerManager (either as objects or string name of the layerManager) as arguments and therefore ULMAStatus would check the status ONLY of the passed layerManagers: example:
ULMAStatus(layerManager1, layerManagerX) or
ULMAStatus("layerManagerName", "otherOptionalLMNames")
Accepts arrays as well, or a mix of names and arrays.

Usage and Invoking

Actually the return true is "disguised" in the form of an array holding all the layerManager objects (that is, it holds references to the layer managers themselves, so each array entry is an... active layerManager reference) that are still undergoing a run method: this would even allow you to selectively stop only some of them once you have grabbed them: example:
var foofoo=ULMAStatus()
if(foofoo){ foofoo[anIndex].stop()}

ULMACouples()

Purpose of the Script

Given an argument, produces a two (3, actually. See below) entries long array whose first entry is the layerManager corresponding to the argument (if it was a layerId, and the script can spot that on its own) and whose second entry is the corresponding layer ID (in case the argument was a layerManager object or a even layerManager name -a layerManager name passed in between apex, that is-, and the script can work it out)

Arguments

Returns a three entries array:
[0]: layerManager NAME.
[1]: its layer ID name.
[2]: layer manager OBJECT itself!

Possible invocations:
ULMACouples("layerID")
ULMACouples("managerName")
ULMACouples(managerObject)
ULMACouples("layerManagerName", 1) number 1 as second arguments flags that the passed name is certainly a layerManager name.
ULMACouples("layerID", 2) number 2 as second arguments flags that the passed name is certainly a layerID name.

Usage and Invoking

See above.

ULMAStop()

Purpose of the Script

Massive call to stop() onto ULMA running objects. Stops the built in method named still as well and stops ULMAWatermarker (see further on) as well.
Please note this script just stops, but doesn't reset other managers values to their defaults, for that you'd use ULMADefaulter().

Arguments

ULMAStop() or:
ULMAStop(layerManager1, layerManager2) which stops only the passed layerManagers, passed also as an array if you prefer, and as names or objects as well. You can include as many as you prefer.
ULMAStop(1) : in this case you passed one single argument and was a number 1: it just stops the ULMAWatermarker

Usage and Invoking

See above.

ULMAWatermarker()

Purpose of the Script

Watermarks (test the form: it prevents from scrolling): useful if you want to keep an animation to the focus.

Arguments

ULMAWatermarker() : this watermarks only if it detects objects which are still undergoing a run() method and are therefore still engaged in some animations, but triggers and does nothing if it sees no running object: useful to call only after you've made some call to run onto some layerManager.
ULMAWatermarker(1) : you pass one argument and it's a number: it watermarks anyway, even if no layer manager is still undergoing a running method.
ULMAWatermarker( optional1, "#anchor") : you know that an anchor in an html page is a location marked by a tag like: <a name="anchorName"></a>. If you send to the location a command like: location="#anchorName" the page automatically scrolls to the level where the anchor is located; well, passing such an anchor to ULMAWatermarker (do not forget to put before the # sign and to pass it in between apex), first ULMAWatermarker scrolls to the ancor, and then starts watermarking!

Usage and Invoking

See above.

The following form will allow you to test all the behaviours: nothing is more explicative than testing. You have several input fields you can use, the form will guide you if you preform something in the wrong way: choose a function and just click Trigger Test.
The codes will appear in the big textarea. Keep in mind that they are commented but only Internet Explorer would let you view the comments from within the textarea: some of these comments are precious and very useful so I'd encourage you to copy the code from Internet Explorer, although all these scripts would work on IE4++, NS4++, NS6++, & Mozilla for sure.