ITextVariable Class Reference

#include <ITextVariable.h>

Inheritance diagram for ITextVariable:

Public Types
enum	{ kDefaultIID = IID_ITEXTVARIABLE }
enum	ScopeStyles { kSection = 0, kDocument }
enum	UseStyles { kFirstInPage = 0, kLastInPage }

Public Member Functions
virtual const WideString &	GetName () const =0
virtual void	SetName (const WideString &s)=0
virtual const WideString &	GetContents ()=0
virtual void	SetContents (const WideString &s)=0
virtual const ClassID	GetBaseTypeID () const =0
virtual void	SetBaseTypeID (ClassID id)=0
virtual const ClassID	GetFormatterID ()=0
virtual void	SetFormatterID (ClassID id)=0
virtual const UID	GetUID () const =0
virtual void	SetUID (UID uid)=0
virtual const WideString &	GetTextBefore ()=0
virtual void	SetTextBefore (const WideString &s)=0
virtual const WideString &	GetTextAfter ()=0
virtual void	SetTextAfter (const WideString &s)=0
virtual ScopeStyles	GetScope () const =0
virtual void	SetScope (ScopeStyles scope)=0
virtual UseStyles	GetUse () const =0
virtual void	SetUse (UseStyles use)=0
virtual bool16	GetDeleteEndPunctuation () const =0
virtual void	SetDeleteEndPunctuation (bool16 b)=0
virtual bool16	GetIncludeExtension () const =0
virtual void	SetIncludePath (bool16 b)=0
virtual bool16	GetIncludePath () const =0
virtual void	SetIncludeExtension (bool16 b)=0
virtual bool16	GetEmperorDate () const =0
virtual void	SetEmperorDate (bool16 b)=0
virtual int32	GetFlags () const =0
virtual void	SetFlags (int32 flags)=0
virtual void	VariableToString (const UIDRef &target, WideString &s, bool16 uniformApproximateWidth=kFalse)=0
virtual void	GetVariableTypeName (WideString &typeName) const =0
virtual ScriptID	GetTextVariableTypeScriptID (const ScriptInfo::RequestContext &context) const =0
virtual ScriptID	GetTextVariableOptionsScriptID (const ScriptInfo::RequestContext &context) const =0
virtual ServiceID	GetFormatterServiceProviderID () const =0
virtual bool16	IsEquivalent (const ITextVariable *other) const =0
virtual bool16	IsPrivate () const =0
virtual void	Get (AddVariableInfo &info) const =0
virtual void	Set (const AddVariableInfo &info)=0
Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0
virtual void	AddRef () const =0
virtual void	Release () const =0

Detailed Description

A Text Variable. This is a representation of a variable within the variable table. It is the definition of the variable and can, with some added information (namely positioning information) produce a text string that should be used as a substitute for the marker within the story.
Each text variable contains a base type name, whether it's visible in the UI or not, and a formatting service type (e.g. number, date or string). These are the intrinsic properties of a variable of a specific type.
Added to it at creation time are a set of properties that further define this type of variable. These are the variable name itself, a formatter specific to the formatting service type, a string representing the contents of the variable, and a UID to a piece of private data specific to this variable. For example, the TotalPagesVariable is a Number Variable using a NumberingService and is visible in the UI. Furthermore, the user can specify that it has the name "Roman Page Count", it's formatted with the Upper Case Roman Numeral number formatter, and has no private data, nor contents.
To create this object, the ITextVariableTable can be queried with the name of the variable. It returns the fully realized object variable instance that can produce the "value" of the variable. The value of the variable is the unformatted, native representation of the variable. For instance, for the TotalPagesVariable, it could be the number 7, for the CreateDateVariable it will be an IDTime.
The value of the variable is used to produce the result, which is a string representation of the value. For instance, using the above example for the TotalPagesVariable, the would be the string "5" if the Arabic Number Formatter was used, or "V" if the Upper Case Roman Number Formatter was used.
To produce the result, dynamic information is given and the resulting string returned. The dynamic information consists of: the "contents" of the variable (representing either nothing, the value or the code to be processed, depending on the variable type), the formatter type (which converts it to a string), and positional information (in the form of a UIDRef to an IOwnedItem).
A variable lives in the variable table. A variable instance (or a reference to a variable) lives in the story and points to a variable in the variable table.

Member Enumeration Documentation

enum ITextVariable::ScopeStyles

Helper enum for the scope types of the TotalPagesVariable's last page number

enum ITextVariable::UseStyles

Helper enum for the bit types of the Char/ParaVariable's running header/footer

Member Function Documentation

virtual void ITextVariable::Get ( AddVariableInfo &  info ) const

pure virtual

Avoid this call if possible - this is legacy and is deprecated.

Parameters

info	information in the CS3 version of the text variable.

Note

This may be a subset in the future and should be avoided.

virtual const ClassID ITextVariable::GetBaseTypeID ( ) const

pure virtual

Get class id of the base variable (e.g. Custom Text Variable, Date Variable, etc)

virtual const WideString& ITextVariable::GetContents ( )

pure virtual

Gets contents(currently only used in format string for dates and custom text contents)

Note

Often empty

virtual bool16 ITextVariable::GetEmperorDate ( ) const

pure virtual

Get Emperor Date

virtual int32 ITextVariable::GetFlags ( ) const

pure virtual

Get all flags

Returns

all boolean flags for a given variable

virtual const ClassID ITextVariable::GetFormatterID ( )

pure virtual

Get class that can format this variable

virtual ServiceID ITextVariable::GetFormatterServiceProviderID ( ) const

pure virtual

Returns the Service ID of the service that's used for formatting the value of the variable, if any.

Returns

kInvalidService if there is no formatter for this variable, else the appropriate ServiceID

Note

Primarily used for scripting and UI, since the formatting is automatically applied.

virtual bool16 ITextVariable::GetIncludeExtension ( ) const

pure virtual

Get Include path extension

virtual bool16 ITextVariable::GetIncludePath ( ) const

pure virtual

Get Include Path

virtual const WideString& ITextVariable::GetName ( ) const

pure virtual

Returns the *translated* name of the variable.

Returns

Reference to WideString

virtual ScopeStyles ITextVariable::GetScope ( ) const

pure virtual

Get Scope

virtual const WideString& ITextVariable::GetTextAfter ( )

pure virtual

Get string to place after the calculated part of the variable.

virtual const WideString& ITextVariable::GetTextBefore ( )

pure virtual

Get the string to place before the calculated part of the variable

virtual ScriptID ITextVariable::GetTextVariableOptionsScriptID ( const ScriptInfo::RequestContext &  context ) const

pure virtual

Returns the options object associated with this type of variable in the given scripting DOM

virtual ScriptID ITextVariable::GetTextVariableTypeScriptID ( const ScriptInfo::RequestContext &  context ) const

pure virtual

Returns the script enumerator corresponding to this type of variable in the given scripting DOM

virtual const UID ITextVariable::GetUID ( ) const

pure virtual

Get uid of desired style (running header footer only)

virtual UseStyles ITextVariable::GetUse ( ) const

pure virtual

Get Use

virtual void ITextVariable::GetVariableTypeName ( WideString &  typeName ) const

pure virtual

Get the base type name for a given variable

Parameters

typeName

returned base type name for the variable

virtual bool16 ITextVariable::IsEquivalent ( const ITextVariable *  other ) const

pure virtual

Tells caller if two variables are conceptually equal

Parameters

other

variable to compare with

Returns

kTrue if equivalent

virtual bool16 ITextVariable::IsPrivate ( ) const

pure virtual

A variable is private if it does not appear in the UI to the user. The variables will have an escape character as the first character in their name - something that the UI won't let you put in.

Returns

kTrue if the Variable is private.

virtual void ITextVariable::Set ( const AddVariableInfo &  info )

pure virtual

Avoid this call if possible - this is legacy and is deprecated.

Parameters

info	information needed to fill out the CS3 text variable.

Note

This can change in the future and should be avoided.

virtual void ITextVariable::SetBaseTypeID ( ClassID  id )

pure virtual

Set class id of the base variable (e.g. Custom Text Variable, Date Variable, etc)

virtual void ITextVariable::SetContents ( const WideString &  s )

pure virtual

Sets contents (currently only used in format string for dates and custom text contents)

Note

Often empty

virtual void ITextVariable::SetEmperorDate ( bool16  b )

pure virtual

Set Emperor Date

virtual void ITextVariable::SetFlags ( int32  flags )

pure virtual

Get all flags

Returns

all boolean flags for a given variable

virtual void ITextVariable::SetFormatterID ( ClassID  id )

pure virtual

Set formmater ID

virtual void ITextVariable::SetIncludeExtension ( bool16  b )

pure virtual

Set Include Path

virtual void ITextVariable::SetIncludePath ( bool16  b )

pure virtual

Set Include path extension

virtual void ITextVariable::SetName ( const WideString &  s )

pure virtual

Sets translated name of variable

virtual void ITextVariable::SetScope ( ScopeStyles  scope )

pure virtual

Set Scope

virtual void ITextVariable::SetTextAfter ( const WideString &  s )

pure virtual

Set string to place after the calculated part of the variable.

virtual void ITextVariable::SetTextBefore ( const WideString &  s )

pure virtual

Set string to place before the calculated part of the variable.

virtual void ITextVariable::SetUID ( UID  uid )

pure virtual

Set uid of desired style (running header footer only)

virtual void ITextVariable::SetUse ( UseStyles  use )

pure virtual

Set Use

virtual void ITextVariable::VariableToString ( const UIDRef &  target, WideString &  s, bool16  uniformApproximateWidth = kFalse  )

pure virtual

Convert the variable to a string.

Parameters

target	- the owned item that refers to this variable. Can also be a non-owned item, in which case an approximate result will be returned - useful for example text.
s	- out: the formatted string representation of the variable's value.
uniformApproximateWidth	- if kTrue, the target is possibly not the context in which the variable will be used. The variable will return a representative string based on the variable's current information (e.g. trial file name).