Expand/Shrink

IupSetAttribute

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.
pwa/p2js: Supported. Note that under pwa/p2js there is no distinction between IupSetAttribute() and IupSetStrAttribute(), largely due to the fact that everything is mapped to JavaScript attributes and CSS style settings. I suppose that means there could be some desktop/Phix programs which either accidentally or deliberately store a machine address and then poke that memory to effect an attribute change, and obviously that sort of thing will simply not work in a browser. Thankfully nothing like that has yet been encountered.

In contrast under pwa/p2js IupSetAttributePtr() simply stores a value without any of the validation or mapping performed by IupSet[Str]Attribute(), and IupGetAttributePtr() will crash rather than fail should there have been no prior corresponding invocation of IupSetAttributePtr(), or perhaps IupSetCallback() and similar. Said crash may or may not be replaced with (say) return NULL;, as further implementation and refinement of pGUI.js progresses, and as needs demand.
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:
Unacceptable: IupSetAttribute(ih,name,sprintf(fmt,x)) -- (never ever ever do this)
Acceptable: IupSetStrAttribute(ih,name,sprint(fmt,x))
Acceptable: IupSetStrAttribute(ih,name,fmt,x)
Acceptable: IupSetAttributes(ih,"name="&fmt,x)
Acceptable: IupSetAttributes(ih,sprintf("name=%s",{fmt}),x)
Unacceptable: IupSetAttribute(ih,name,stringvar) -- (unless stringvar is suitably long-lived or actually a constant)
Acceptable: IupSetStrAttribute(ih,name,stringvar)
Acceptable: 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