Definition: |
include pGUI.e
IupSetAttribute(Ihandln ih, string name, atom_string v) -- or -- IupSetAttributePtr(Ihandln ih, string name, atom v) |
Description: |
Sets an interface element attribute.
ih: Identifier of the interface element. If NULL will set in the global environment. name: name of the attribute. v: value of the attribute. If NULL the default value will be used. |
Comments: |
IupSetAttribute can store only constant strings (like "Title", "30", etc) or application pointers. An error occurs if val is neither an atom nor a string. The given value is not duplicated as a string, only a reference is stored. Therefore, you can store application custom attributes, such as a context structure to be used in a callback. IMPORTANT: The value of the v parameter must be a literal constant or otherwise outlive the interface element: Instead of IupSetAttribute(ih,name,sprintf(fmt,x)) use IupSetStrAttribute(ih,name,fmt,x), or IupSetAttributes(ih,"name="&fmt,x) or even IupSetAttributes(ih,sprintf("name=%s",{fmt}),x). Likewise instead of IupSetAttribute(ih,name,stringvar) use IupSetStrAttribute(ih,name,stringvar), or even IupSetAttributes(ih,"%s=%s",{name,stringvar}). When non-string values are used (such as raw memory pointers) you must ensure they remain valid for the lifetime of the interface element. In contrast, the attribute name is always internally duplicated. While IupSetAttribute can set strings and pointers, they must be retrieved differently (see IupGetAttribute). Apart from the tighter validation of the last parameter, IupSetAttributePtr behaves identically to IupSetAttribute. While technically unnecessary, IupSetAttributePtr allows code to be more self-documenting, and is the logical counterpart to IupGetAttributePtr (for which, in contrast, there is a very real need). Note that IupSetAttributePtr should only be used for "always pointer/handle/NULL" rather than "string/NULL" settings. |
Utility Functions |
The following procedures can also be used to set attributes on an interface element:
IupSetAttributeId(Ihandle ih, string name, integer id, atom_string v) IupSetAttributeId2(Ihandle ih, string name, integer lin, col, atom_string v) id, lin, col: used when the attribute has additional ids. Id based attributes are always non inheritable, so these functions do not propagate the attribute to the children. The same rules for non-volatility of v also apply here. See also the Utility Functions in IupSetStrAttribute, which allow direct setting of integer, floating point, and RGB values. Note that the C function IupSetfAttributeId is not wrapped by pGUI, however that functionality is covered by the optional parameters of IupSetStrAttributeId. |
Example 1: |
IupSetAttribute(dlg, "VISIBLE", "YES") IupSetAttribute(text, "VALUE", "Hello!") IupSetAttribute(indicator, "VALUE", "ON") IupSetAttribute(dlg, sprintf("MY ITEM (%d)", i), "Test") atom myStruct = allocate(sizeofstruct(myData)) IupSetAttribute(dlg, "MYDATA", myStruct) -- Note that myStruct must be manually freed after dlg is destroyed |
Example 2: | Defines a radio’s initial value: |
Ihandle portrait = IupToggle("Portrait", NULL) Ihandle landscape = IupToggle("landscape", NULL) Ihandle box = IupVbox({portrait, IupFill(), landscape}) Ihandle mode = IupRadio(box) IupSetHandle("landscape", landscape) -- associates a name to initialize the radio IupSetAttribute(mode, "VALUE", "landscape") -- defines the radio’s initial value |
|
See Also: |
IupSetCallback,
IupSetStrAttribute,
IupGetAttribute,
IupSetAttributes,
IupGetAllAttributes,
IupSetGlobal,
IupGetGlobal
|