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()

AppendValueToList

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.

AppendValueToPropList()

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.

CountElements()

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.

GetPropertyNameByIndex()

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.

GetValueByIndex()

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.

GetValueByProperty()

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.

NewListValue()

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.

NewPropListValue()

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.

SetValueByIndex()

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.

SetValueByProperty()

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.