Contents
Navigation
Home User Reference Other Resources


Each , , and can contain a user data list, which your application can use in any way you want. A user data list contains all the user data for a movie, track, or media.

Each user data list may contain one or more user data items. All QuickTime user data items share several attributes.

First, each user data item carries a type identifier, stored in a long integer. Apple has reserved all lowercase user data type values. You are free to create user data type values using uppercase or mixed case. Apple recommends using type values that begin with the © character (Mac Roman code 0xA9) to specify user data items that store text data. User data items of these types must contain text data only.

Second, you can create more than one user data item in a user data list. Therefore, each user data item is identified by a unique index. Index values are assigned sequentially within a user data type and start at 0.

Finally, you may create alternate text for a given user data text item. For example, you may want to support multiple languages and may therefore want to create different text for each language. The Movie Toolbox allows you to specify different versions of the text of a single user data item. These versions are distinguished by their region code values.

The QTPlgUserData class lets you whether manipulate existing user data lists or create and save new ones







The QTPlgUserData class constructors are called when you create a new instance of the class, while the ˜QTPlgUserData class destructor, is called automatically when the class is no more in use. Also, you can invoke the class destructor by setting the instance of the class to nil.
Once a new class instance is returned, it is good practice to check the class property to be sure that the new object can be used. A QTPlgUserData object is valid if it referes to a valid data reference (that is the value of the property is not 0)

The class provides you with the following initializer methods:
()
This is the default constructor. The new class instance will be initialized to an empty user data list in memory
(other as QTPlgUserData)
This is the copy constructor. The properties of the object to be copied will be used to initialize the new class instance properties
(m as movie)
use this function to initialize the new class instance with the user data list obtained from the movie specified by the m parameter. Note that the new class instance will not copy the movie’s user data but, instead, will retain just a reference to it; in such as way you can modify the movie’s user data by doing changes to its reference retained by the class. On the other hand, it is up to you to ensure that the QTPlgUserData class instance is referring anytime to a valid movie user data list. Moreover, you must save the source movie if you want to register the changes done to the user data list
Note: a more convenient way to access the movie user data is to use the property of the class
[Deprecated]: since version 6.5 of the plugin this redundant constructor is deprecated and will be removed from a future plugin version
(m as movie, trkIndex as integer, [fromMedia as boolean=false])
use this function to initialize the new class instance with the user data list obtained from the track of the movie specified by the m parameter that corresponds to the index passed into the trkIndex parameter; such as index ranges from 0 to the total number of movie tracks–1. If you set the optional fromMedia parameter to true you will obtain the user data list of the media associated to the specified track. Note that the new class instance will not copy the resulting user data but, instead, will retain just a reference to it; in such as way you can modify the original user data by doing changes to its reference retained by the class. On the other hand, it is up to you to ensure that the QTPlgUserData class instance is referring anytime to a valid track or media user data list. Moreover, you must save the source movie if you want to register the changes done to the user data list
Note: a more convenient way to access the or user data is to use the property of the appropriate container class instance
[Deprecated]: since version 6.5 of the plugin this redundant constructor is deprecated and will be removed from a future plugin version
(f as folderitem)
The new class instance will try to create a new user data list and, then, to initialize it with the contents in the file specified by the f parameter

returns the handle to the user data list. useful for toolbox programmers (use with care: you could invalidate the handle causing unpredictable results (probably an application crash))
specifies the total number of user data items of any type contained within list in use
specifies the total number of different user data types contained within list in use
specifies the total number of user data list items that belong to the group specified by the four characters code udType. You can find about the list of the types contained into the user data list by inspecting the array
specifies the array of different user data types contained within the user data list; you can access to the items of the array by the index i; as usual this index ranges from 0 to –1

()
use this method to remove every item from the user data list in use
returns nothing. Check the class property for errors
(udType as string)
using this method you will remove just the items of type udType from the user data list in use. You can find about the list of the types contained into the user data list by examining the class property
returns nothing. Check the class property for errors
(udType as string, index as integer) as string
by this function you can handle the contents of the user data item specified by its type (the udType parameter) and index (an integer value ranging from from 1 to ). You can use this function whether like setter method or getter method. You can replace the content of the specified item with a string you assign to the method. Setting the index parameter to a value greater than cause the method to append a new entry to the user data list
if you are using the method as getter method, returns a string set to the contents of the user data list item; if the function fails the returned string is empty. Check the class property for errors
You can use this method on both the right and the left sides of the assignment (=) operator
(udType as string, index as integer, region as integer) as string
by this function you can handle the contents of the user data text item specified by its type (the udType parameter), index (an integer value ranging from from 1 to ) and language code (the region parameter). If you need more informations and examples about region codes see the QTUserData Class section in the RealBasic Help On Line. You can use this function whether like setter method or getter method. You can replace the content of the specified item with a string you assign to the method. Setting the index parameter to a value greater than cause the method to append a new entry to the user data list
if you are using the method as getter method, returns a string set to the contents of the user data list item; if the function fails the returned string is empty. Check the class property for errors
You can use this method on both the right and the left sides of the assignment (=) operator
(udType as string, index as integer) as memoryblock
by this function you can handle the contents of the user data item specified by its type (the udType parameter) and index (an integer value ranging from from 1 to ). You can use this function whether like setter method or getter method. You can replace the content of the specified item with a block of memory that can represent whatever makes sense for you. Setting the index parameter to a value greater than , cause the method to append a new item to the user data list and fill it with the data of the memoryblock
if you are using the method as getter method, returns a memoryblock filled with the contents of the user data list item; if the function fails the returned value is set to nil. Check the class property for errors
You can use this method on both the right and the left sides of the assignment (=) operator
(udType as string, index as integer)
use this method to remove an item from the user data list in use. You determine the target item by specifying its type (udType parameter) and index (index parameter); this index ranges from 1 to . After the item has been removed, the remaining items of that type are renumbered so that their index values are sequential and start at 1. You can find about the list of the types contained into the user data list by examining the class property
returns nothing. Check the class property for errors
(f as folderitem)
use to method to write the contents of the user data list to the file specified by the f parameter. You can, later, initialize an instance of this class by using the appropriate overloaded version
returns nothing. Check the class property for errors