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(PIMoaMmValue This,
MoaDouble fnum,
PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

fnum
MoaDouble Contains the MoaDouble to be used for the new value

pValue
PMoaMmValue 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(PIMoaMmValue This,
MoaLong num,
PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

num
MoaLong Contains the MoaLong to be used for the new value

pValue
PMoaMmValue 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(PIMoaMmValue This,
ConstPMoaPoint pPoint,
PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

pPoint
ConstPMoaPoint Pointer to a ConstPMoaPoint used for the new value

pValue
PMoaMmValue Pointer to a MoaMmValueto 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(PIMoaMmValue This,
ConstPMoaRect pRect,
PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

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

pValue
PMoaMmValue 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(PIMoaMmValue This,
MoaHandle hString,
PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

hString
MoaHandleMoaHandle containing a null-terminated string used for the value

pValue
PMoaMmValue 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(PIMoaMmValue This,
ConstPMoaChar pString,
PMoaMmSymbol pSymbol)

Parameters

This
Pointer to the IMoaMmValue interface

pString
ConstPMoaChar Pointer to the ConstPMoaChar containing the string

pSymbol
PMoaMmSymbol 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(PIMoaMmValue This,
ConstPMoaChar pString,
PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

pString
ConstPMoaChar Pointer to a null-terminated string used for the value

pValue
PMoaMmValue Pointer to a MoaMmValuethat 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(PIMoaMmValue This,
MoaMmSymbol symbol,
PMoaChar pStringBuf,
MoaLong bufLen)

Parameters

This
Pointer to the IMoaMmValue interface

symbol
MoaMmSymbol The symbol to translate

pStringBuf
PMoaChar Pointer to a string buffer to receive the result

bufLen
MoaLong 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(PIMoaMmValue This,
MoaMmSymbol symbol,
PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

symbol
MoaMmSymbol The symbol to translate

pStringBuf
PMoaChar Pointer to a string buffer to receive the result

bufLen
MoaLong 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(PIMoaMmValue This,
PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

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(PIMoaMmValue This,

PMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

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(PIMoaMmValue This,
ConstPMoaMmValue pValue)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue 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(PIMoaMmValue This,
ConstPMoaMmValue pValue,
MoaLong FAR * pResult)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue Pointer to a string-type ConstPMoaMmValue

pResult
MoaLong FAR *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(PIMoaMmValue This,
ConstPMoaMmValue pValue,
MoaDouble FAR * pResult)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue Pointer to a float-type ConstPMoaMmValue

pResult
MoaDouble FAR * 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(PIMoaMmValue This,
ConstPMoaMmValue pValue,
MoaLong FAR * pResult)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue Pointer to an integer-type ConstPMoaMmValue

pResult
MoaLong FAR * 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(PIMoaMmValue This,
ConstPMoaMmValue pValue,
PMoaPoint pResult)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue Pointer to an integer-type ConstPMoaMmValue

pResult
PMoaPoint 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(PIMoaMmValue This,
ConstPMoaMmValue pValue,
PMoaRect pResult)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue Pointer to a rectangle-type ConstPMoaMmValue

pResult
PMoaRect Pointer to a MoaRect 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(PIMoaMmValue This,
ConstPMoaMmValue pValue,
PMoaChar pStringBuf,
MoaLong bufLen)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue Pointer to a string-type ConstPMoaMmValue

pStringBuf
PMoaChar Pointer to a buffer to receive a copy of the string data

bufLen
MoaLongMoaLong indicating the length of the buffer

Returns

MoaError

Description


Obtains the C string for a string-type MoaMmValue. pStringBufis a pointer to a buffer to receive a copy of the string data. bufLenis 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_StringExpectedif 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(PIMoaMmValue This,
ConstPMoaMmValue pValue,
PMoaMmSymbol pResult)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue Pointer to a symbol-type ConstPMoaMmValue

pResult
PMoaMmSymbol 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(PIMoaMmValue This,
ConstPMoaMmValue pValue,
MoaMmValueType FAR * pResult)

Parameters

This
Pointer to the IMoaMmValue interface

pValue
ConstPMoaMmValue Pointer to a ConstPMoaMmValue

pResult
MoaMmValueType FAR * 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-2007 Adobe Macromedia Software LLC, Inc.