IUP/Attributes

Introduction

Attributes are used to change properties of elements. Each element has a set of attributes that affect it, and each attribute can work differently for each element. Depending on the element, its value can be computed or simply verified also it can be internally stored or not.

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).

Only a few attributes are not inherited: "TITLE", "VALUE", "ALIGNMENT", "X", "Y", and "SIZE".

When an attribute is set it is always stored at the hash table unless the driver disable the storage. If the value is nil, the attribute will be removed from the hash table. Then the driver or the custom control is updated. Finally the attribute is also updated for the children of the element in the driver if they do not have the attribute defined in their own hash table.

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 together with 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 set it is always stored at the hash table unless the driver disable the storage. If the value is NULL, the attribute will be removed from the hash table. Then the driver or the custom control is updated. Finally the attribute is also updated for the children of the element in the driver if they do not have the attribute defined in their own hash table.

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.

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):

<source lang=lua>

       myButton = iup.button{title = "Ok", bgcolor = "0 255 0"}

</source> Font color can be subsequently changed by modifying the value of attribute fgcolor:

<source lang=lua>

       myButton.fgcolor = "255 0 0"

</source>

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:

<source lang=lua>

       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

</source>

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 of a “widget” type, 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.

The attributes in charge of treating the actions associated to objects are not directly transferred to IUP. Since the use of actions requires registering functions in C to be called when the event occurs, there is a differentiated treatment for such attributes. The IupLua system does not require the creation and registration of C functions for this purpose.