2.18 User tags

User tags are a way of passing additional information from Hollywood scripts to plugins. They can be used to pass an unlimited amount of additional data to plugins directly from the Hollywood script. For example, let's suppose there's a plugin that can load PDF pages as images. Such a plugin would need two additional pieces of information to do its job, namely the page to load and optionally a password in case the PDF is password-protected. Both pieces of information could be passed to the plugin using user tags.

From the Hollywood script's point of view, user tags are simply passed in an optional UserTags table accepted by many Hollywood functions, e.g. LoadBrush(). To pass the optional page and password arguments to an image plugin, a Hollywood script could do the following:

 
LoadBrush(1, "test.pdf", {UserTags = {Page = 5, Password = "secret"}})

All tags that the script passes in the UserTags table that is accepted by all commands that support plugins are then forwarded to plugins in a struct hwUserTagList linked list. For image plugins, the pointer to the first struct hwUserTagList node is passed to your LoadImage() implementation in the struct LoadImageCtrl argument. Your LoadImage() implementation can then examine all user tags that are in the list by iterating through the individual list nodes. struct hwUserTagList looks like this:

 
struct hwUserTagList
{
    struct hwUserTagList *Succ;
    STRPTR Name;
    STRPTR Str;
    double Val;
    int Length;
};

Here is a description of the structure members:

Succ:
Contains a pointer to the next node in the list or NULL for the tail node.

Name:
Name of the user tag.

Str:
If the user has set the tag to a string value, it is passed here. If this is NULL, then you have to examine the Val member below.

Val:
If the user has set the tag to a numerical value, it is passed in this structure member.

Length:
If the user has set the tag to a string value, this structure member contains the string length in bytes (not including the terminating 0). This structure member is useful when passing binary data through user tags. In that case there can be NULL characters in the string so the only way to find out the length of the data in Str is via this member.

Note that even if your plugin doesn't support any user tags, you should still look for the user tag list and pass it on to functions like hw_FOpenExt because the user tags passed to your plugin could also be intended for another plugin like the file adapter plugin that is used to handle the actual file I/O. That's why it is important that plugins always forward the user tags list to all functions that support user tags.

Show TOC