Difference between revisions of "Taglists"
From MorphOS Library
m (Style.) |
m (Grammar and readability fixes.) |
||
| Line 2: | Line 2: | ||
| − | A taglist is an array of "key-value" pairs. The key is always a 32-bit integer number and is called a ''tag''. The value has | + | A taglist is an array of "key-value" pairs. The key is always a 32-bit integer number and is called a ''tag''. The value also has a size of 32 bits. It may be an integer, or a pointer to any structure or object. Taglists are commonly used in the MorphOS API for passing a variable number of arguments, usually sets of attributes with their values. A few special key values are used for array termination, concatenation and item skipping. A set of functions in the ''utility.library'' may be used for taglist traversing, filtering, searching, copying etc. |
Every pair in a taglist is a ''TagItem'' structure, defined in ''<utility/tagitem.h>'': | Every pair in a taglist is a ''TagItem'' structure, defined in ''<utility/tagitem.h>'': | ||
| Line 12: | Line 12: | ||
}; | }; | ||
| − | To be | + | To be self descriptive, every taglist, being just a plain C array, must have some kind of termination. It is very similar to the string null-termination idea. The termination is done with a ''TagItem'' having its ''ti_Tag'' field set to ''TAG_END'' (which happens to be defined as zero). The ''ti_Data'' value of the terminating ''TagItem'' is ignored, it is usually set to zero too. The illustration below shows a simple taglist: |
| Line 45: | Line 45: | ||
(ULONG)obj, TAG_END); | (ULONG)obj, TAG_END); | ||
| − | Of course in the second case variable ''mytaglist'' | + | Of course in the second case variable ''mytaglist'' need not be defined anywhere. Note that for every taglist-based function the taglist is '''the last''' argument. There may be some plain arguments before it. It is a common practice to omit ''ti_Data'' for the terminator (it is ignored anyway). |
Revision as of 00:59, 6 November 2010
Grzegorz Kraszewski
A taglist is an array of "key-value" pairs. The key is always a 32-bit integer number and is called a tag. The value also has a size of 32 bits. It may be an integer, or a pointer to any structure or object. Taglists are commonly used in the MorphOS API for passing a variable number of arguments, usually sets of attributes with their values. A few special key values are used for array termination, concatenation and item skipping. A set of functions in the utility.library may be used for taglist traversing, filtering, searching, copying etc.
Every pair in a taglist is a TagItem structure, defined in <utility/tagitem.h>:
struct TagItem
{
ULONG ti_Tag;
ULONG ti_Data;
};
To be self descriptive, every taglist, being just a plain C array, must have some kind of termination. It is very similar to the string null-termination idea. The termination is done with a TagItem having its ti_Tag field set to TAG_END (which happens to be defined as zero). The ti_Data value of the terminating TagItem is ignored, it is usually set to zero too. The illustration below shows a simple taglist:
This taglist may be created with the following code:
double x = 3.438872763e+17;
Object *obj = NewObject( /* ... */ );
struct TagItem mytaglist[] = {
{ Tag1, 2837 },
{ Tag2, (ULONG)&x },
{ Tag3, (ULONG)"The quick brown fox..." },
{ Tag4, (ULONG)obj },
{ TAG_END, 0 }
};
Passing Taglists to Functions
Building taglists as global or local variables is not very convenient. That is why almost every MorphOS API function getting a taglist as one of its arguments has two forms. The first one accepts a pointer to the taglist. The second one is a variadic args macro building the taglist on the program stack dynamically. Such function pairs are named according to one of the two conventions:
- SomeFunctionA() takes a pointer to a taglist, SomeFunction() builds the taglist dynamically.
- SomeFunctionTagList() takes a pointer to a taglist, SomeFunctionTags() builds the taglist dynamically.
Continuing the above example, one can pass the example taglist to SomeFunction() in two ways:
SomeFunctionTagList(mytaglist); SomeFunctionTags(Tag1, 2837, Tag2, (ULONG)&x, Tag3, (ULONG)"The quick brown fox...", Tag4, (ULONG)obj, TAG_END);
Of course in the second case variable mytaglist need not be defined anywhere. Note that for every taglist-based function the taglist is the last argument. There may be some plain arguments before it. It is a common practice to omit ti_Data for the terminator (it is ignored anyway).