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 pElementValueand 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 pResultValuewith 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 the MoaMmValue for 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 the MoaMmValue 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-2008 Adobe Macromedia Software LLC, Inc.