Attributes Guide
Using
Attributes are strings, and there are two functions to change them:
- IupSetAttribute stores only a pointer to the string and does not duplicate it.
- IupStoreAtribute duplicates the string, allowing you to use it for other purposes.
With IupSetAttribute you can also store application pointers that can be strings or not. This can be very useful, for instance, used inside callbacks. For example, by storing a C pointer of an application defined structure, the application can retrieve this pointer inside the callback through function IupGetAttribute. Therefore, even if the callbacks are global functions, the same callback can be used for several objects, even of different types.
When an attribute is updated (Set) it is stored internally at the hash table of the control only if the driver implementation of the control class allows the storage. If the value is NULL, the attribute will also be removed from the hash table. Finally the attribute is updated for the children of the control if they do not have the attribute defined in their own hash table. Here is a pseudo-code:
IupSetAttribute(ih, name, value)
{
if ih.SetAttribute(name, value) then
ih.hash_table.Set(name, value)
endif
if (ih.IsInheritable(name))
for each child of ih do
if not ih.hash_table.IsDefined(name) then
child.SetAttribute(name, value)
child.NotifyChildren(name, value)
endif
endfor
endif
}
When an attribute is retrieved (Get) it will first be checked at the driver implementation of the control class. If not defined then it checks in the hash table. If not defined it checks its parent hash table and so forth, until it reaches the dialog. And finally if still not defined then a default value is returned (the default value can also be NULL).
value = IupGetAttribute(ih, name)
{
value = ih.GetAttribute(name)
if not value then
value = ih.hash_table.Get(name)
endif
if not value then
value = ih.GetParentHashTableAttribute(name)
endif
if not value then
value = ih.GetDefaultAttribute(name)
endif
}
The driver implementation of the control class can update or retreive a value even if the control is not mapped. This is enabled for only a few attributes.
Attribute names are always upper case, lower case names will not work. But attribute values like "YES", "NO", "TOP", are case insensitive, so "Yes", "no", "top", and other variations will work. Boolean attributes accept the values "1", "YES", "ON" or "TRUE" for true, and NULL (not defined), "0", "NO", "OFF" or "FALSE" for false, even if in the documentation is only one of these combinations.
There are attributes common to all the elements. These attributes sometimes are not mentioned in each element documentation. We assume that the programmer knows they exist. In some cases, common attributes behave differently in different elements, but in such cases, there are comments explaining the behavior.
In LED there is no prefix IUP_ or quotation marks for attributes, names or values.
Inheritance
Elements included in other elements can inherit their attributes. This means there is an inheritance mechanism inside a given dialog.
This means, for example, that if you set the "MARGIN" attribute of a vbox containing several other elements, including other vboxes, all the elements depending on the attribute "MARGIN" will be affected, except for those who the "MARGIN" attribute is already defined.
Please note that not all attributes are inherited. Some examples: "TIP", "ZORDER", "TITLE", "VALUE", "ALIGNMENT", "X", "Y", "RASTERSIZE", "SIZE", "IMAGE", "IMINACTIVE", "IMPRESS", "SEPARATOR".
Id numbered attributes are NON inheritable always, like "1" or "MARK1:1". Attributes that are handle names like "IMAGE" and "MENU" are NON inheritable always. Attributes that are read-only or write-only are NON inheritable.
The attribute is first checked at the element specific implementation at the driver (if mapped) or at the custom control. If not defined then it checks in the hash table. If not defined in its hash table, the attribute will be inherited from its parent and so forth, until it reaches the dialog. But if still then the attribute is not defined a default value for the element is returned (the default value can also be NULL).
IupLua
Each interface element is created as a Lua table, and its attributes are fields in this table. Some of these attributes are directly transferred to IUP, so that any changes made to them immediately reflect on the screen. However, not all attributes are transferred to IUP.
Control attributes, such as handle, which stores the handle of the IUP element, and parent, which stores the object immediately above in the class hierarchy, are not transfered. Attributes that receive strings or numbers as values are immediately transferred to IUP. Other values (such as functions or objects) are stored in IupLua and might receive special treatment.
For instance, a button can be created as follows (defining a title and the background color):
myButton = iup.button{title = "Ok", bgcolor = "0 255 0"}
Font color can be subsequently changed by modifying the value of attribute fgcolor:
myButton.fgcolor = "255 0 0"
Note that the attribute names in C and in IupLua are the same, but in IupLua they can be written in lower case.
In the creation of an element some parameters are required attributes (such as title in buttons). Their types are checked when the element is created. The required parameters are exactly the paremeters that are necessary for the element to be created in C.
Some interface elements can contain one or more elements, as is the case of dialogs, lists and boxes. In such cases, the object’s element list is put together as a vector, that is, the elements are placed one after the other, separated by commas. They can be accessed by indexing the object containing them, as can be seen in this example:
mybox = iup.hbox{bt1, bt2, bt3}
mybox[1].fgcolor = "255 0 0" -- changes bt1 foreground color
mybox[2].fgcolor = caixa[1].fgcolor -- changes bt2 foreground color
While the attributes receiving numbers or strings are directly transferred to IUP, attributes receiving other interface objects are not directly transferred, because IUP only accepts strings as a value. The method that transfers attributes to IUP verifies if the attribute value is a handle, that is, if it is an interface element. If the element already has a name, this name is passed to IUP. If not, a new name is created, associated to the element and passed to IUP as the value of the attribute being defined.
This policy is very useful for associating two interface elements, because you can abstract the fact that IUP uses a string to make associations and imagine the interface element itself is being used.