domObj.getObjectsByTag
(As of 3.1.002.06)
Find all objects in the current DOM which match a specified tag name - - find objects matching specific Tag names.
Syntax
domObj.getObjectsByTag(tag, [, tag...] [callback])
Parameters
tag is either a simple tag name or an array of tag names to search for domObj.
callback is an optional JavaScript function that will be called for each successful match.
If the last character in a tag parameter is * it is treated as a wildcard. So a search for BCC* will match objects with a tag name that starts with 'BCC'.
Returned Value
If a callback function is specified, this function returns TRUE. Otherwise, it returns a JavaScript array of pointers to DocOrigin DOM objects. That array is empty if no matches are found.
Background
This routine searches only the current object (typically the object containing this script) as well as all objects within (under) this object. When using the callback function, you can cause the search of the DOM to terminate prematurely by having the callback function return TRUE. Otherwise, the callback is called for every match in the DOM. This can be useful (for example) if you're only interested in the first match, or already know that there is in fact only one object that will match. This might improve the program's speed.
Example
var p=getObjectsByTag('BCC*');
for(i=0; i<p.length; i++) {
_logf("%d. name='%s' value='%s'", i, p[i]._name, p[i]._value);
}
The above script will generate a listing of all objects with any tag name starting with BCC. If this script is put on a top-level object (Form, Page, Container for instance) then all instances are found. If it occurs on a lower-level Pane it will only find the instances within that Pane.
function myfun(p) {
_logf("%d. name='%s' value='%s'", i, p._name, p._value);
if (p._value == 0) return true; // quit when a value of zero is encountered
}
getObjectsByTag('BCC*', myfun);
This second example does the same thing as the first, but via a callback routine. It also terminates the search if an object with a value of zero is encountered.
