bgiGetGizmoHandle

Retrieves the handle of a named control from a loaded gizmo collection. Searches gizmoCollections map for collectionID. If collection not found, returns 0. Iterates through collection.gizmos vector. Compares entry.name with name parameter (string comparison). If match found, returns entry.handle. Returns 0 if name not found in collection.

This function provides name-based control lookup after loading XML GUI via bgiLoadGizmos. CollectionID is the return value from bgiLoadGizmos. Name parameter matches the name attribute in XML <Control> or <Dialog> tags. Handles are the gizmo IDs used by all other BGI functions (bgiSetButtonText, bgiGetTextboxText, etc.). Returns 0 for invalid collection ID or non-existent name (ambiguous - 0 could theoretically be valid handle). Case-sensitive name matching. Use for retrieving frequently-accessed controls to avoid repeated lookups. Common pattern: call once at startup to cache handles in variables, then use those variables for control manipulation. Example: myButton = bgiGetGizmoHandle("btnSubmit", collectionID), then bgiSetButtonText(myButton, "Click Me"). Dialog window handle is also stored in collection with its name attribute.