MM Developer's Guide
MM Interfaces | MM Methods | MM Types and Misc API


IMoaMmValue

Interface ID: IID_IMoaMmValue
Pointer type: PIMoaMmValue
Inheritance: IMoaUnknown
Header file: mmivalue.h

Description

This interface provides support for converting C and MOA types to values that can be passed through the IMoaMmPropertyOwner interface and elsewhere in the multimedia API. The MoaMmValue type provides a general, platform and application-independent mechanism for moving data of various types between an Xtra and an application.

Like MOA interfaces, MoaMmValues use reference counting for memory management. The methods ValueAddRef() and ValueRelease() are provided by this interface to let you hold onto values when you need to and release them when you're finished. The "caller-owns" rule applies, as with MOA interfaces.

With IMoaMmUtils2, IMoaMmWndMac, and IMoaMmWndWin, this interface supercedes IMoaMmUtils, which has been made redundant.

Methods

Data conversion

StringToSymbol()
SymbolToString()
ValueToInteger()
ValueToSymbol()
ValueToFloat()
ValueToString()
ValueToStringPtr()
ValueToPoint()
ValueToRect()
IntegerToValue()
SymbolToValue()
FloatToValue()
StringToValue()
StringHandleToValue()
PointToValue()
RectToValue()

MoaMmValue management

ValueType()
ValueAddRef()
ValueRelease()
ValueStringLength()
ValueReleaseStringPtr()

FloatToValue()

Syntax

FloatToValue(MoaDouble fnum, PMoaMmValue pValue)

Parameters

fnum
Contains the MoaDouble to be used for the new value
pValue
Pointer to the MoaMmValue to receive the result

Returns

MoaError

Description

Creates a new float-type MoaMmValue from a MoaDouble. fnum contains the MoaDouble to be used as the basis for the new value. pValue contains a pointer to a MoaMmValue to receive the result. This call populates the MoaMmValue at pValuewith a new MoaMmValue, overwriting any current value. Make sure to release any preexisting value before making this call. The caller is responsible for releasing the returned value using IMoaMmValue:: ValueRelease().

IntegerToValue()

Syntax

IntegerToValue(MoaLong num, PMoaMmValue pValue)

Parameters

num
Contains the MoaLong to be used for the new value
pValue
Pointer to a MoaMmValue to receive the result

Returns

MoaError

Description

Creates a new integer-type MoaMmValue from a MoaLong. num contains the MoaLong to be used as the basis for the new value. pValue contains a pointer to a MoaMmValue to receive the result. This call populates the MoaMmValue at pValuewith a new MoaMmValue, overwriting any current value. Make sure to release any preexisting value before making this call. The caller is responsible for releasing the returned value using IMoaMmValue:: ValueRelease().

PointToValue()

Syntax

PointToValue(ConstPMoaPoint pPoint, PMoaMmValue pValue)

Parameters

pPoint
Pointer to a ConstPMoaPoint used for the new value
pValue
Pointer to a MoaMmValue to receive the result

Returns

MoaError

Description

Creates a new point-type MoaMmValue from a MoaPoint. On entry, pPoint contains a pointer to a MoaPoint to be used as the basis for the new value. pValue contains a pointer to a MoaMmValue to receive the result. This call populates the MoaMmValue at pValue with a new MoaMmValue, overwriting any current value. Make sure to release any preexisting value before making this call. The caller is responsible for releasing the returned value (see IMoaMmValue:: ValueRelease()).

RectToValue()

Syntax

RectToValue(ConstPMoaRect pRect, PMoaMmValue pValue)

Parameters

pRect
Pointer to a ConstPMoaRect used as the basis for the new value
pValue
Pointer to a MoaMmValue to receive the new value

Returns

MoaError

Description

Creates a new rectangle-type MoaMmValue from a MoaRect. On entry, pRect contains a pointer to a MoaRect to be used as the basis for the new value. pValue contains a pointer to a MoaMmValue to receive the result. This call populates the MoaMmValue at pValue with a new MoaMmValue, overwriting any existing value. Make sure to release any preexisting value before making this call. The caller is responsible for releasing the returned value (see IMoaMmValue:: ValueRelease()).

StringHandleToValue()

Syntax

StringHandleToValue(MoaHandle hString, PMoaMmValue pValue)

Parameters

hString
MoaHandle containing a null-terminated string used for the value
pValue
Pointer to a MoaMmValue to receive the new value

Returns

MoaError

Description

Creates a new string-type MoaMmValue from a C string contained in a MoaHandle. On entry hString contains a valid MoaHandle containing a null-terminated C string to be used as the basis for the value. pValue contains a pointer to a MoaMmValue to receive the result. This call populates the MoaMmValue at pValue with a new MoaMmValue, overwriting any current value. Make sure to release any preexisting value before making this call. The caller is responsible for releasing the returned value (see IMoaMmValue:: ValueRelease()).

Important: StringHandleToValue() does not copy the MoaHandle supplied in hString. Instead, the MoaHandle is transferred to the value. Therefore, the caller releases direct ownership of the original handle by making this call and can no longer reference or dispose it. To create a string-type value from a copy of an existing C string, use StringToValue()instead.

StringToSymbol()

Syntax

StringToSymbol(ConstPMoaChar pString, PMoaMmSymbol pSymbol)

Parameters

pString
Pointer to the ConstPMoaChar containing the string
pSymbol
Pointer to a MoaMmSymbol that receives the result

Returns

MoaError

Description

Converts the string, pString, to the corresponding symbol and returns the result in pSymbol. Symbols are used to refer to specific properties and media data. In addition, symbols are data types in Lingo, Director's scripting language.

StringToValue()

Syntax

StringToValue(ConstPMoaChar pString, PMoaMmValue pValue)

Parameters

pString
Pointer to a null-terminated string used for the value
pValue
Pointer to a MoaMmValue that receives the result

Returns

MoaError

Description

Creates a new string-type MoaMmValue from a C string stored at pString. On entry pString contains a pointer to a null-terminated C string to be used as the basis for the value. pValue contains a pointer to a MoaMmValue to receive the result. This call populates the MoaMmValue at pValuewith a new MoaMmValue, overwriting any existing value. Make sure to release any preexisting value before making this call. The caller is responsible for releasing the returned value (see IMoaMmValue:: ValueRelease()).

StringToValue() copies the string data at pStringfor use in the MoaValue. If you want to avoid a memory copy and supply the C string data directly for the value, use StringHandleToValue() instead.

SymbolToString()

Syntax

SymbolToString(MoaMmSymbol symbol, PMoaChar pStringBuf, MoaLong bufLen)

Parameters

symbol
The symbol to translate
pStringBuf
Pointer to a string buffer to receive the result
bufLen
The size of the string buffer

Returns

MoaError

Description

Converts symbol to a string. pStringBuf contains a pointer to the caller's string buffer which will receive the string. bufLen is the size of the caller's buffer. Symbols are used to refer to specific properties and media data. In addition, symbols are data types in Lingo, Director's scripting language.

SymbolToValue()

Syntax

SymbolToValue(MoaMmSymbol symbol, PMoaMmValue pValue)

Parameters

symbol
The symbol to translate
pStringBuf
Pointer to a string buffer to receive the result
bufLen
The size of the string buffer

Returns

MoaError

Description

Converts symbol to a string. pStringBuf contains a pointer to the caller's string buffer which will receive the string. bufLen is the size of the caller's buffer. Symbols are used to refer to specific properties and media data. In addition, symbols are data types in Lingo, Director's scripting language.

ValueAddRef()

Syntax

ValueAddRef(PMoaMmValue pValue)

Parameters

pValue
PMoaMmValue

Returns

MoaError

Description

Increments the reference count of a value by 1. Because MoaMmValuesare shared objects, you should always call this method on values you passed as a method argument to retain it across method calls to your Xtra. When you explicitly request or construct a new value (for example, using IntegerToValue()) this method is automatically called for you. Thus, you are responsible for calling IMoaMmValue:: ValueRelease() on any value you create, unless the value is being passed back to the host application. Values passed back to the host application as return values to Xtra method functions are transferred to the host application which is then responsible for releasing them. Examples of this are your asset and sprite GetProp()and CallFunction()methods, and your Lingo Xtra Call() method.

ValueRelease()

Syntax

ValueRelease(PMoaMmValue pValue)

Parameters

pValue
PMoaMmValue

Returns

MoaError

Description

Decrements the reference count of a value by 1. When the refCount drops to 0, the value is released from memory. Because MoaMmValuesare shared objects, you should always call this method on values you passed as a method argument if you need to retain it across method calls to your Xtra. When you explicitly request or construct a new value (for example, using IntegerToValue()) this method is automatically called for you. Thus, you are responsible for calling IMoaMmValue:: ValueRelease() on any value you create, unless the value is being passed back to the host application Values passed back to the host application as return values to Xtra method functions are transferred to the host application which is then responsible for releasing them. Examples of this are your asset and sprite GetProp() and CallFunction() methods, and your Lingo Xtra Call() method.

ValueReleaseStringPtr()

Syntax

ValueReleaseStringPtr(ConstPMoaMmValue pValue)

Parameters

pValue
Pointer to a string-type ConstPMoaMmValue

Returns

MoaError

Description

Releases hold on the contents of a string value initiated by a call to ValueGetStringPtr(). ValueReleaseStringPtr() must be called when caller has finished directly accessing string data, stored in a string-type MoaMmValue. To obtain a copy of a value's string data, use ValueToString() rather than ValueToStringPtr().

ValueStringLength()

Syntax

ValueStringLength(ConstPMoaMmValue pValue, MoaLong * pResult)

Parameters

pValue
Pointer to a string-type ConstPMoaMmValue
pResult
Pointer to a MoaLong to receive the string length

Returns

MoaError

Description

Obtains the string length of a string-type MoaMmValue. pResult is a pointer to a MoaLong to receive the length. The length supplied does not include the null terminator byte. Returns kMoaMmErr_StringExpected if pValue is not a string-type value.

ValueToFloat()

Syntax

ValueToFloat(ConstPMoaMmValue pValue, MoaDouble * pResult)

Parameters

pValue
Pointer to a float-type ConstPMoaMmValue
pResult
Pointer to a MoaDouble to receive the result

Returns

MoaError

Description

Obtains the MoaDouble for a float-type MoaMmValue. pResult is a pointer to a MoaDouble to receive the result. Returns kMoaMmErr_FloatExpected if pValue is not a float-type value.

ValueToInteger()

Syntax

ValueToInteger(ConstPMoaMmValue pValue, MoaLong * pResult)

Parameters

pValue
Pointer to an integer-type ConstPMoaMmValue
pResult
Pointer to a MoaLong to receive the result

Returns

MoaError

Description

Obtains the MoaLong for an integer-type MoaMmValue. pResult is a pointer to a MoaLong to receive the result. Returns kMoaMmErr_IntegerExpected if pValue is not an integer-type value.

ValueToPoint()

Syntax

ValueToPoint(ConstPMoaMmValue pValue, PMoaPoint pResult)

Parameters

pValue
Pointer to an integer-type ConstPMoaMmValue
pResult
Pointer to a MoaPoint to receive the result

Returns

MoaError

Description

Obtains the MoaPoint for an integer-type MoaMmValue. pResult is a pointer to a MoaPoint to receive the result. Returns kMoaMmErr_PointExpected if pValue is not a point-type value.

ValueToRect()

Syntax

ValueToRect(ConstPMoaMmValue pValue, PMoaRect pResult)

Parameters

pValue
Pointer to a rectangle-type ConstPMoaMmValue
pResult
Pointer to aMoaRect to receive the result

Returns

MoaError

Description

Obtains the MoaRect for a rectangle-type MoaMmValue. pResult is a pointer to a MoaRect to receive the result. Returns kMoaMmErr_RectExpected if pValue is not a rectangle-type value.

ValueToString()

Syntax

ValueToString(ConstPMoaMmValue pValue, PMoaChar pStringBuf, MoaLong bufLen)

Parameters

pValue
Pointer to a string-type ConstPMoaMmValue
pStringBuf
Pointer to a buffer to receive a copy of the string data
bufLen
MoaLong indicating the length of the buffer

Returns

MoaError

Description

Obtains the C string for a string-type MoaMmValue. pStringBuf is a pointer to a buffer to receive a copy of the string data. bufLen is the length of the caller's buffer. The buffer must be large enough for the string data including the terminating null byte. To access the string data directly rather than obtaining a copy, use ValueToStringPtr(). Returns kMoaMmErr_StringExpected if pValue is not a string-type value.

ValueToStringPtr()

Syntax
ValueToStringPtr(ConstPMoaMmValue pValue, ConstPMoaChar * pResult)
Parameters
pValue
Pointer to a string-type ConstPMoaMmValue
pResult
Pointer to a ConstPMoaChar to receive the pointer
Returns
MoaError
kMoaMmErr_StringExpected if pValue is not a string-type value.
Description
Obtains direct-access to the C string for a string-type MoaMmValue. pResult is a pointer to a ConstPMoaChar to receive a pointer to the C string data. The string buffer being accessed is owned by the MoaMmValue. When done accessing the string data, you must call ValueReleaseStringPtr(). To get a copy of the string data rather than accessing it directly, use ValueToString().

ValueToSymbol()

Syntax

ValueToSymbol(ConstPMoaMmValue pValue, PMoaMmSymbol pResult)

Parameters

pValue
Pointer to a symbol-type ConstPMoaMmValue
pResult
Pointer to a MoaMmSymbol to receive the result

Returns

MoaError

Description

Obtain the MoaMmSymbol for a symbol-type MoaMmValue. pResult is a pointer to a MoaMmSymbol to receive the result. Returns kMoaMmErr_SymbolExpected if pValue is not a symbol-type value.

ValueType()

Syntax

ValueType(ConstPMoaMmValue pValue, MoaMmValueType * pResult)

Parameters

pValue
Pointer to a ConstPMoaMmValue
pResult
Pointer to a MoaMmValueType to receive the result

Returns

MoaError

Description

Obtains the type code for a MoaMmValue. This method returns a MoaMmValueType which specifies the type of value. Note that some MoaMmValue scripting objects do not have a unique MoaMmValueType. For example, to find out if a MoaMmValue references an image object, use the GetImageInfo() method of IMoaMmImage.

Copyright © 1995-2008 Adobe Macromedia Software LLC, Inc.