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
This is the copy constructor. The properties of the object to be copied will be used to initialize the
new class instance properties
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
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
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
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
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
You can use this method on both the right and the left sides of the assignment (=) operator
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
You can use this method on both the right and the left sides of the assignment (=) operator
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
You can use this method on both the right and the left sides of the assignment (=) operator
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
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