gGetAttribute

Definition:	include pGUI.e object res = gGetAttribute(gdx id, string name, object dflt=999_999_999)
Description:	Retrieve an interface element attribute value. id: Identifier of the interface element. name: name of the attribute. dlft: value to return if not found or undefined, with 999_999_999 specifically/randomly meaning "crash". Returns: the attribute value or dlft if the attribute is not set or does not exist.
pwa/p2js:	Supported.
Notes:	While gSetAttribute() can be passed settings in either the most natural form or a suitable string representation, this routine returns the internal representation, and there is no way to force it to yield a string. Note that the internal form may be platform or back-end specific, for instance the red colour under GTK is (I think) the atom #FF0000 whereas under JavaScript it might be "#FF0000", or "red", or even "rgb(255,0,0)". In fact, red in WinAPI is actually #0000FF, but xpGUI.e expects/returns all colours in rgb form, and quietly maps them to/from the offbeat Windows bgr form for you. Obviously I can and will take pains to address the most common vexing issues, such as the colours just mentioned, and may in time be able to start guaranteeing some consistency between backends, but the more obscure the setting you are retrieving, the more defensive you should probably code. Also, gSetAttribute() is obviously and for good reason downright belligerent in pointing out unsupported attributes, whereas gGetAttribute() is somewhere between moderately aggressive in that regard and quite wrong in flagging something as an error simply because it hasn’t yet been set. There will doubtless be several such cases that should undeniably be treated as a straightforward bug (jlmk). [One specific case that was explicitly fixed for is gGetAttribute(id,"ACTIVE")] Simply providing a suitable default can sometimes go a long way to alleviating much of that.
Aliases:	The following aliases can be used for a clearer statement of intent and to make the code a little more self-documenting: integer res = gGetInt(gdx id, string name, object dflt=999_999_999) integer {a,b} = gGetIntInt(gdx id, string name, object dflt={0,0}) atom res = gGetDouble(gdx id, string name, object dflt=999_999_999) With the exceptions of gGetInt(id,“EXPAND/SPACE”), and gGetIntInt() quietly returning {0,0} should there be a typo in name, they don’t guarantee or do anything differently, apart from the lightest validation of the result. Even something like gGetInt(id,"TITLE") would be fine as long as to_number() does not object.
Additional:	integer {w,h} = gGetTextExtent(gdx id, sequence text, bool bSumHeights=true) Uses the current font settings on the specified element. No attempt is made to support rotated text (that would probably be a separate routine). Should not be invoked before the specified element has been displayed. If text is a sequence of strings the maximum width is returned. bSumHeights determines whether "" heights are summed or just the last returned.
Common:	The following (read-only) attributes are common to several controls/interface element types. See gSetAttribute for other (updateable) common attributes.
CLASSNAME	(read-only, non inheritable) Returns a human readable string representation of the inteface element type which may be helpful for diagnostic purposes. See the ctrl_names constant in xpGUI.e for more details.
MOUSEPOS	Returns the cursor position in client coordinates, {0..w-1,0..h-1}, where w,h are as per SIZE. The global version of MOUSEPOS returns absolute screen coordinates. Returns: {x,y}, a pair of integer pixel offsets.
SIZE	(non inheritable) Specifies the element user size, and returns the current/final size, in pixels. Note that technically this is read-only and attempts to set it actually set USER_SIZE, whereas reading this matches the final reality much more closely than the other one. In other words this attribute is really owned by and calculated by the layout manager, but will accept an initial/later hint or two. Most applications should just do everything via SIZE, and pretend that USER_SIZE does not even exist. Value: {width,height} or "widthxheight", where width and height are integer values corresponding to the horizontal and vertical sizes, respectively. You can also set only one of the parameters by removing the other one and maintaining the separator "x", which is equivalent to setting the other value to 0, or omit the x to set the width only, ditto an integer or length-1 sequence. For example: "x40" (height only = "0x40" - ditto {0,40}) or "40x" (width only = "40x0" - ditto "40", 40, or {40}). When this attribute is consulted the current/final size of the control is returned, not necessarily what was actually set. (In some cases a gRedraw() may be required between setting and fetching for updates to filter through.) A user size of {0,0} or "0x0" can be set, which can also be set using NULL. ? Should you wish to use the user size only as an initial size, change this attribute to NULL after the control is mapped, the returned size in gGetAttribute() will still be the current/final size. The element is NOT immediately repositioned. Call gRedraw() to update the dialog layout. See Layout Management for more details on sizes. Note this replaces the RASTERSIZE attribute of pGUI, and xpGUI_from_pGUI.e replaces "SIZE" with "SIZE[*charsize]" which needs manual fixup. (In IUP, SIZE is in "character units", which xpGUI does not yet support, largely since that makes little sense to me on containers, especially those whose children [might] all have different fonts set on them.) A possible future enhancement is to allow say "[r]em:20x1" which would set the size to the [root] width of 20 times and height of one 'm', with "pt", "px" and perhaps some other JavaScript-compatible size units also being allowed, and perhaps do better than that "SIZE[*charsize]", not that xpGUI_from_pGUI() is intended to have a particularly long lifespan anyway. Affects: All, except menus. See Also: FONT, USER_SIZE, gRedraw
See Also:	gSetAttribute, gSetAttributes, gSetHandler, gGetHandler, gSetGlobal, gGetGlobal