MM Developer's Guide
MM Interfaces | MM Methods
| MM Types and Misc API
IMoaMmList
Interface ID: IID_IMoaMmList
Pointer type: PIMoaMmList
Inheritance: IMoaUnknown
Header file: mmiservc.h
- Description
-
Lists are a type of value used to represent a collection of elements.
Lists can contain elements of multiple types, so it is possible
to have a single list containing any combination of integer, float,
string, and other values. In general, there are two types of lists:
linear and property. Linear lists contain an ordered sequence
of values which are referred to by index. Property lists contain
a sequence of propertyName value
pairs. Elements of a property list are referred to by property
name.
A list is a type of MoaMmValue.
Since lists are MoaMmValues,
they can be used as properties of objects (such as assets and
sprites) obtained and set using the standard IMoaMmPropowner::GetProp()
and SetProp() methods,
just like strings, integers, and other simple value types. The
elements of lists are also MoaMmValues.
Thus, a list can itself contain lists (sublists).
When adding to or modifying elements in a list, the value supplied
by the caller automatically calls
IMoaMmValue::ValueAddRef() before it is added to the
list. In effect, the value is copied and then placed in the list.
The caller continues to maintain ownership of the supplied element
value and is responsible for releasing it.
When retrieving elements from a list, the value in the list automatically
calls IMoaMmValue::ValueAddRef()
when it is returned. For example, when you call GetValueByIndex()
to retrieve a value, ValueAddRef()
is called. In effect, the list value is copied, then
returned to the caller. The caller owns the returned value and
is responsible for releasing it.
When you dispose of the list, elements within the list are disposed
recursively.
To add or release values, use the IMoaMmValue::ValueAddRef()
and ValueRelease()
methods.
Methods
- Adding values
- NewListValue()
AppendValueToList()
NewPropListValue()
AppendValueToPropList()
- List management
- CountElements()
- Accessing values
- GetValueByIndex()
SetValueByIndex()
GetValueByProperty()
GetPropertyNameByIndex()
- Editing values
- SetValueByProperty()
- Syntax
AppendValueToList(PMoaMmValue pListValue,
PMoaMmValue pElementValue)
- Parameters
-
pListValue
- Pointer to a pre-existing MoaMmValue linear list
pElementValue
- Pointer to the MoaMmValue to add
- Returns
-
MoaError
- Description
- Adds a value to the end of the linear list stored in pListValue.
pListValue must
be a pointer to a preexisting linear list-type MoaMmValue.
To create a new, empty list value, use IMoaMmList::NewListValue().
pElementValue is
a pointer to the MoaMmValue to
add to the list. Values added to lists are copied; therefore,
the caller maintains ownership of pElementValue
and is responsible for releasing it.
- Syntax
AppendValueToPropList(PMoaMmValue pListValue,
PMoaMmValue pElementProp,
PMoaMmValue pElementValue)
- Parameters
-
pListValue
- Pointer to a pre-existing MoaMmValue
property list
pElementProp
- Pointer to the MoaMmValue that represents
the property to add to the list
pElementValue
- Pointer to the MoaMmValue that represents
the property value to add to the list
- Returns
MoaError
- Description
- Adds a value to the end of a the property list stored in pListValue.
pListValue
must be a pointer to a preexisting property list-type MoaMmValue.
To create a new, empty property list value, use IMoaMmList::NewPropListValue().
pElementValue is
a pointer to the MoaMmValue
to add to the list. Values added to lists are copied; the caller
maintains ownership of pElementValue
and is responsible for releasing it.
- Syntax
CountElements(ConstPMoaMmValue pListValue)
- Parameters
-
pListValue
- Pointer to the ConstPMoaMmValue for the list whose elements to count
- Returns
- Returns the number of elements in pListValue.
If pListValue is not a list, then -1 is returned.
- Description
- pListValue can
be either a linear-list or a property list. The list elements
are not counted recursively; that is, only the top-level
values are counted, not sublists.
- Syntax
- GetPropertyNameByIndex(ConstPMoaMmValue pListValue,
MoaLong index,
PMoaMmValue pResultValue)
- Parameters
pListValue
- Pointer to the ConstPMoaMmValue for the list
index
- Ordinal number of element in the list
pResultValue
- Pointer to the symbol-type value representing the
property name
- Returns
MoaError
- Description
- Returns the property name associated with an element in a
property list. index
specifies the element of interest, the first element in the list
has an index of 1. The property name is returned as a symbol-type
value in pResultValue.
To convert symbols to strings, use the IMoaMmUtils::SymbolToString()
method.
- Syntax
GetValueByIndex(ConstPMoaMmValue pListValue,
MoaLong index,
PMoaMmValue pResultValue)
- Parameters
pListValue
- Pointer to the ConstPMoaMmValue for
the list
index
- Ordinal number of element in the list
pResultValue
- Pointer to the value of the element
- Returns
MoaError
- Description
- Obtains the value of an element in a list by index. index
specifies the element of interest, the first element
in the list has an index of 1. This call populates a MoaMmValue
at pResultValue
with the list element. The caller is responsible
for releasing the value returned. This call overwrites any current
value at pResultValue,
so if the current value is valid, make sure to release it before
making this call.
- Syntax
- GetValueByProperty(ConstPMoaMmValue pListValue,
PMoaMmValue pPropNameValue,
PMoaMmValue pResultValue)
- Parameters
pListValue
- Pointer to the ConstPMoaMmValue for
the list
pPropNameValue
- Pointer to a symbol-type value representing the property
name of the element
pResultValue
- Pointer to the value of the element
- Returns
MoaError
- Description
- Obtains the value of an element in a list by property name.
pPropNameValue must
contain a symbol-type value specifying the property name of the
element of interest. This call populates a MoaMmValue
at pResultValue
with the list element. The caller is responsible
for releasing the value returned. This call overwrites any current
value at pResultValue,
so if the current value is valid, make sure to release it before
making this call.
- Syntax
- NewListValue(PMoaMmValue pListValue)
- Parameters
pListValue
- Pointer to the MoaMmValue for the
new linear list
- Returns
MoaError
- Description
- Creates a new linear list-type value. This call populates the value at pListValue
with the result. This call overwrites any current value at pListValue,
so if the current value is valid, make sure to release it before making this
call. The caller owns the newly created value and is responsible for releasing
it.
- Syntax
- NewPropListValue(PMoaMmValue pListValue)
- Parameters
pListValue
- Pointer to the MoaMmValue for the new property
list
- Returns
MoaError
- Description
- Creates a new property list-type value. This call populates the value
at pListValue with the result. This call overwrites any current
value at pListValue, so if the current value is valid, make
sure to release it before making this call. The caller owns the newly created
value and is responsible for releasing it.
- Syntax
- SetValueByIndex(PMoaMmValue pListValue,
MoaLong index,
PMoaMmValue pNewValue)
- Parameters
pListValue
- Pointer to theMoaMmValuefor the existing
list
index
- Ordinal number of the element to modify in the list
pNewValue
- Pointer to the MoaMmValue to add to the
list
- Returns
MoaError
- Description
- Sets the value of a list element by index. pListValue
specifies an existing list to modify. index
specifies the element to be modified, the first
element in the list has an index of 1. pNewValue
is a pointer to a caller-owned value to be added
to the list. This call copies the value at pNewValue,
and replaces the current value in position index
with the copy. Since the value is copied, the
caller maintains ownership of the pNewValue
and is responsible for releasing it.
- Syntax
- SetValueByProperty(PMoaMmValue pListValue,
PMoaMmValue pPropNameValue,
PMoaMmValue pNewValue)
- Parameters
pListValue
- Pointer to theMoaMmValue for the existing
list
pPropNameValue
- Pointer to the symbol-type value representing the
property name of the element to modify
pNewValue
- Pointer to the MoaMmValue to add to the
list
- Returns
MoaError
- Description
- Sets the value of a list element by property name. pListValue
specifies an existing property list to modify.
pPropNameValue is
a symbol-type value specifying the property name of the element
to be modified. pNewValue is
a pointer to a caller-owned MoaMmValue
to be added to the list. This call copies the value
at pNewValue,
and replaces the current value in the list associated with property
pPropNameValue with
the copy. Since the value is copied, the caller maintains ownership
of the pNewValue and
is responsible for releasing it.
Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.