Expand/Shrink

IupGetAttribute

Definition: include pGUI.e

string res = IupGetAttribute(Ihandln ih, string name, dflt="")
-- or --
atom res = IupGetAttributePtr(Ihandln ih, string name)
Description: Retrieve an interface element attribute value.

ih: Identifier of the interface element. If NULL will retrieve from the global environment.
name: name of the attribute.
dlft: value to return if not found or undefined.

Returns: the attribute value or dlft if the attribute is not set or does not exist.

Note: IupSetAttribute() accepts an atom_string, whereas IupGetAttribute always yields a string, and IupGetAttributePtr retrieves (the raw pointer or) a handle.
The (strictly speaking somewhat unnecessary) IupSetAttributePtr() is intended to be the logical counterpart to IupGetAttributePtr (which has a very real need), and in that simple way make code more self-documenting.
Alternatively the utility functions below may be used to retrieve numerical indexes, etc.
pwa/p2js: Supported. Note that IupGetAttribute() in pGUI.js is moderately aggressive in pointing out unsupported attributes, explicitly setting dflt (even to "") can avoid some of that, whereas IupGetAttributePtr() (deliberately) never raises any errors or warnings under pwa/p2js.
Some of the utility functions listed below may not yet be available (but should be fairly easy to add).
Utility Functions: These functions can also be used to get attributes from the element:

atom res = IupGetInt(Ihandln ih, string name)
atom {a1,a2} = IupGetIntInt(Ihandln ih, string name)
atom res = IupGetInt2(Ihandle ih, string name)
atom res = IupGetIntId(Ihandle ih, string name, integer id)
atom res = IupGetIntId2(Ihandle ih, string name, integer lin, col)
atom res = IupGetFloat(Ihandle ih, string name)
atom res = IupGetFloatId(Ihandle ih, string name, integer id)
atom res = IupGetFloatId2(Ihandle ih, string name, integer lin, col)
atom res = IupGetDouble(Ihandln ih, string name)
atom res = IupGetDoubleId(Ihandle ih, string name, integer id)
atom res = IupGetDoubleId2(Ihandle ih, string name, integer lin, col)
integer {r,g,b} = IupGetRGB(Ihandle ih, string name)
integer {r,g,b} = IupGetRGBId(Ihandle ih, string name, integer id)
integer {r,g,b} = IupGetRGBId2(Ihandle ih, string name, integer lin, col)
string res = IupGetAttributeId(Ihandle ih, string name, integer id)
string res = IupGetAttributeId2(Ihandle ih, string name, integer lin, col)

id, lin, col: used when the attribute has additional ids.

IupGetIntInt retrieves two integers (as separated by 'x', ':' or ',').
IupGetInt2 returns just the second value (and IupGetInt just the first, and the ˜Id2 routines just the first of a different thing).
As far as most Phix applications are concerned there is probably not much point using IupGetFloat instead of IupGetDouble, apart from easing translation.
Only those routines I have personally found useful for retrieving global attributes accept an Ihandln first parameter. Let me know if any others should, however I suspect that sometimes an immediate error may prove more helpful than some potential/additional but as yet completely unused flexibility.
Note that IupGetInt() etc retrieve 32-bit (or 64-bit) integers, or pointers/handles, which may need to be stored as an atom.
(Renaming as IupGetAtom() etc would only succeed in making it more difficult to translate C code, or search for examples.)
Notes: See the Attributes Guide for more details.

The returned value is not necessarily the same pointer used by the application to define the attribute value. The pointers of internal IUP attributes returned by IupGetAttribute should never be freed or changed, except when it is a custom application pointer that was stored using IupSetAttribute and allocated by the application.

The returned pointer can be used safely even if IupGetGlobal or IupGetAttribute are called several times. But not too many times, because it is an internal buffer and IUP may reuse it after around 50 calls.
See Also: IupSetAttribute, IupSetAttributes, IupGetHandle, IupSetGlobal, IupGetGlobal