IIDXMLElement Class Reference

#include <IIDXMLElement.h>

Inheritance diagram for IIDXMLElement:

Public Types
enum	{ kDefaultIID = IID_IIDXMLELEMENT }
enum	_Placement { kEndIndex = -2 }
typedef InDesign::TextRange	value_type
typedef XMLContentIterator	iterator
typedef XMLContentIterator	const_iterator
typedef const value_type *	pointer
typedef const value_type *	const_pointer
typedef const value_type &	reference
typedef const value_type &	const_reference
typedef K2Reverse_iterator < iterator, value_type, std::ptrdiff_t, pointer, reference >	reverse_iterator
typedef K2Reverse_iterator < const_iterator, value_type, std::ptrdiff_t, const_pointer, const_reference >	const_reverse_iterator

Public Member Functions
virtual const XMLReference &	GetXMLReference () const =0
virtual void	SetXMLReference (const XMLReference &newXMLRef)=0
virtual int32	GetChildCount () const =0
virtual XMLReference	GetNthChild (int32) const =0
virtual const XMLReference &	GetParent () const =0
virtual void	SetParent (const XMLReference &newParent)=0
virtual XMLReference	FindChild (const WideString &tag, int32 index) const =0
virtual int32	FindChild (const XMLReference &childToFind) const =0
virtual void	AddChildAt (const XMLReference &newChild, int32 indexAt, bool16 setChildsParent=kTrue)=0
virtual void	RemoveChild (const XMLReference &childToRemove, bool16 resetChild=kTrue)=0
virtual void	RemoveChild (int32 indexAt, bool16 resetChild=kTrue)=0
virtual void	SetChildAt (const XMLReference &newChildXMLRef, int32 indexAt)=0
virtual UID	GetTagUID () const =0
virtual WideString	GetTagString () const =0
virtual void	SetTag (UID newTag)=0
virtual void	SetTag (const WideString &newTag)=0
virtual UID	GetContentItem (LayoutSelector selector=kStandardLayout) const =0
virtual void	SetContentItem (UID contentItem, LayoutSelector selector=kStandardLayout)=0
virtual const XMLContentReference &	GetContentReference (void) const =0
virtual void	SetContentReference (const XMLContentReference &contentReference)=0
virtual ITextStoryThread *	QueryContentTextStoryThread (void) const =0
virtual void	AddAttribute (const WideString &name, const WideString &value, bool16 removable=kTrue)=0
virtual void	RemoveAttribute (const WideString &name)=0
virtual void	SetAttributeName (const WideString &name, const WideString &newName)=0
virtual void	SetAttributeValue (const WideString &name, const WideString &newValue)=0
virtual int32	GetAttributeCount () const =0
virtual bool16	HasAttribute (const WideString &name) const =0
virtual WideString	GetAttributeNameAt (int32 pos) const =0
virtual WideString	GetAttributeValue (const WideString &name) const =0
virtual WideString	GetAttributeValueAt (int32 pos) const =0
virtual bool16	IsAttributeRemovable (const WideString &name) const =0
virtual const_iterator	begin () const =0
virtual const_iterator	end () const =0
virtual const_iterator	make_iterator (int32 position) const =0
virtual const_reverse_iterator	rbegin () const =0
virtual const_reverse_iterator	rend () const =0
virtual const_reverse_iterator	rmake_iterator (int32 position) const =0
virtual void	GetInsertChildElementList (XMLDTDInsertElementList &childElementList) const =0
virtual void	GetInsertSiblingAfterList (XMLDTDInsertElementList &siblingAfterList) const =0
virtual void	GetReplaceElementList (XMLDTDReplaceElementList &replaceElementList) const =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

This interface is for elements on the logical structure tree; from client code- don't call mutators on this interface, instead use IXMLElementCommands, IXMLAttributeCommands etc.

See the element definition in XML 1.0 specification. An element will have at least a name (see IXMLTag), possibly some attributes and perhaps some content. The content and attributes if present are represented through this class.

There are methods that return iterators (of type XMLContentIterator) that can be used to iterate over the contents of an element in the order of the DOM. What these are doing is iterating over the children of a given XML element, not traversing the sub-tree.

Member Typedef Documentation

typedef XMLContentIterator IIDXMLElement::const_iterator

Typedef for content iteration.

typedef const value_type* IIDXMLElement::const_pointer

Typedef for content iteration.

typedef const value_type& IIDXMLElement::const_reference

Typedef for content iteration.

typedef K2Reverse_iterator<const_iterator, value_type, std::ptrdiff_t, const_pointer, const_reference> IIDXMLElement::const_reverse_iterator

Typedef for content iteration.

typedef XMLContentIterator IIDXMLElement::iterator

Typedef for content iteration.

typedef const value_type* IIDXMLElement::pointer

Typedef for content iteration.

typedef const value_type& IIDXMLElement::reference

Typedef for content iteration.

typedef K2Reverse_iterator<iterator, value_type, std::ptrdiff_t, pointer, reference> IIDXMLElement::reverse_iterator

Typedef for content iteration.

typedef InDesign::TextRange IIDXMLElement::value_type

Typedef for content iteration. When iterating the children of an element, the children can (perhaps) be characterised by text ranges; if you have an element within one story, say, section, with some dependents like 'title' and 'para' then these will lie within the text range of the parent, and each be characterised by a TextRange in the text model.

Member Enumeration Documentation

enum IIDXMLElement::_Placement

Index in parent constants, for AddChildAt() method

Member Function Documentation

virtual void IIDXMLElement::AddAttribute ( const WideString &  name, const WideString &  value, bool16  removable = kTrue  )

pure virtual

Add an attribute, optionally specifying that it can be removed later.

Parameters

name	identifies the attribute
value	initial value for this attribute
removable	if set to kTrue, then the attribute can't be removed by later calls (i.e. RemoveAttribute will fail)

virtual void IIDXMLElement::AddChildAt ( const XMLReference &  newChild, int32  indexAt, bool16  setChildsParent = kTrue  )

pure virtual

Mutator, to add child at given index.

Parameters

newChild	child to add
indexAt	specifies desired new index for child (or kEndIndex if no pref.)
setChildsParent	if kTrue, set the child's parent to point back to this

virtual const_iterator IIDXMLElement::begin ( ) const

pure virtual

Get iterator for iterating through children of this element

Returns

iterator to mark start of forward iteration over all children

virtual const_iterator IIDXMLElement::end ( ) const

pure virtual

Get iterator for ending iteration (one of end of children)

Returns

iterator to mark limit for forward iteration

virtual XMLReference IIDXMLElement::FindChild ( const WideString &  tag, int32  index  ) const

pure virtual

Return the n'th child that has the specified tag applied.

Parameters

tag	name of the tag (IXMLTag) associated with this element
index	specifies index of child of interest

Returns

XMLReference to the given child

virtual int32 IIDXMLElement::FindChild ( const XMLReference &  childToFind ) const

pure virtual

Find index of child

Parameters

childToFind

persistent reference for child of interest

Returns

int32 zero-based index of child with given XMLReference, -1 if child does not exist

virtual int32 IIDXMLElement::GetAttributeCount ( ) const

pure virtual

Accessor for attribute count on this element

Returns

size of attribute list

virtual WideString IIDXMLElement::GetAttributeNameAt ( int32  pos ) const

pure virtual

Accessor for attribute at given index

Parameters

pos	zero-based index in attribute list, 0 <= pos < GetAttributeCount()

Returns

WideString giving attribute name

virtual WideString IIDXMLElement::GetAttributeValue ( const WideString &  name ) const

pure virtual

Accessor for attrib-value, given its name. NOTE: calling this method with an attribute name that does not exist on the element technically is an undefined operation, even though this method will return an empty WideString. In DEBUG, this method will fire an assert if it is called with an attribute that does not exist, although it is safe to continue. Please use HasAttribute() first to make sure the attribute exists.

See Also

HasAttribute

Parameters

name	specifies attribute of interest

Returns

WideString containing attrib value

virtual WideString IIDXMLElement::GetAttributeValueAt ( int32  pos ) const

pure virtual

Accessor for attribute at given index

Parameters

pos	zero-based index in attribute list, 0 <= pos < GetAttributeCount()

Returns

WideString the attribute value

virtual int32 IIDXMLElement::GetChildCount ( ) const

pure virtual

Return the number of children this element has.

Returns

int32 number of children

virtual UID IIDXMLElement::GetContentItem ( LayoutSelector  selector = kStandardLayout ) const

pure virtual

Return the item in layout where content will appear, if there is one.

Parameters

selector

identifies what layout content should appear in (param reserved for future use)

Returns

UID of content item associated

virtual const XMLContentReference& IIDXMLElement::GetContentReference ( void  ) const

pure virtual

Return the content reference associated with this element

Returns

content reference associated with this element

virtual void IIDXMLElement::GetInsertChildElementList ( XMLDTDInsertElementList &  childElementList ) const

pure virtual

get a list of first child elements the DTD will allow to insert

Parameters

childElementList

[OUT] receives the list of child elements the DTD will allow to insert for this element

virtual void IIDXMLElement::GetInsertSiblingAfterList ( XMLDTDInsertElementList &  siblingAfterList ) const

pure virtual

get a list of sibling after elements the DTD will allow to insert

Parameters

childElementList

[OUT] receives the list of sibling after elements the DTD will allow to insert

virtual XMLReference IIDXMLElement::GetNthChild ( int32  ) const

pure virtual

Return the n'th child of the element; note that you can also use iterators rather than this mechanism

to iterate over the children. Index is zero-based index that should be in range [0..GetChildCount()-1]

Returns

persist reference to child at given index

virtual const XMLReference& IIDXMLElement::GetParent ( ) const

pure virtual

Return the parent element.  

Returns

XMLReference to the parent

virtual void IIDXMLElement::GetReplaceElementList ( XMLDTDReplaceElementList &  replaceElementList ) const

pure virtual

get a list of possible replacement tags which the DTD will allow for this element

Parameters

replaceElementList

[OUT] receives the list of replacements tags the DTD will allow

virtual WideString IIDXMLElement::GetTagString ( ) const

pure virtual

Accessor for tag-name of this element

Returns

WideString giving tag-name of element

virtual UID IIDXMLElement::GetTagUID ( ) const

pure virtual

Return UID for tag (IXMLTag) associated with this element

Returns

UID which can be used to instantiate IXMLTag given database of this element

virtual const XMLReference& IIDXMLElement::GetXMLReference ( ) const

pure virtual

Return a persistent reference (XMLReference) to this element.

Returns

XMLReference to this element

virtual bool16 IIDXMLElement::HasAttribute ( const WideString &  name ) const

pure virtual

Determine if this element has named attribute

Parameters

name	name of attribute

Returns

bool16 kTrue if it has, kFalse otherwise

virtual bool16 IIDXMLElement::IsAttributeRemovable ( const WideString &  name ) const

pure virtual

Determine if attribute has been created as removable or not

Parameters

name	identifies attribute of interest

Returns

bool16 kTrue if can be removed by client code, kFalse otherwise

virtual const_iterator IIDXMLElement::make_iterator ( int32  position ) const

pure virtual

Get forward iterator for iterating through children of this element starting at arbitrary position in the children list

Parameters

position

specifies location where the iterator should start from

Returns

iterator that can be used to traverse children from given position to 'end'

virtual ITextStoryThread* IIDXMLElement::QueryContentTextStoryThread ( void  ) const

pure virtual

Query ITextStoryThread associated with the content, if applicable

Returns

ref-incremented ITextStoryThread interface of the content, if applicable; nil otherwise

virtual const_reverse_iterator IIDXMLElement::rbegin ( ) const

pure virtual

Get iterator for backward iteration through children

Returns

iterator for marking start of reverse iteration through children

virtual void IIDXMLElement::RemoveAttribute ( const WideString &  name )

pure virtual

Remove named attribute, unless added as non-removable; use IXMLElementCommands rather than this mutator from client code.

Parameters

name	identifies attribute to be removed

virtual void IIDXMLElement::RemoveChild ( const XMLReference &  childToRemove, bool16  resetChild = kTrue  )

pure virtual

Mutator; has the effect of removing given child,

Parameters

childToRemove	specifies child to remove
resetChild	if kTrue also sets the child's parent to invalid (i.e. kInvalidXMLReference).

virtual void IIDXMLElement::RemoveChild ( int32  indexAt, bool16  resetChild = kTrue  )

pure virtual

Remove child at given index

Parameters

indexAt	specifies zero based index of child to remove
resetChild	if kTrue also sets the child's parent to invalid (i.e. kInvalidXMLReference).

virtual const_reverse_iterator IIDXMLElement::rend ( ) const

pure virtual

Get iterator to mark end of backward iteration process

Returns

iterator for marking end of reverse iteration through children

virtual const_reverse_iterator IIDXMLElement::rmake_iterator ( int32  position ) const

pure virtual

Make reverse iterator, for backward iteration from arbitrary position

Parameters

position

where iteration should start from

Returns

iteration that can be used from this start point to 'rend'

virtual void IIDXMLElement::SetAttributeName ( const WideString &  name, const WideString &  newName  )

pure virtual

Mutator for an attribute name; from client code, use IXMLAttributeCommands method from client code.

Parameters

name	specifies existing name for attribute of interest
newName	specifies the new name to change it to

virtual void IIDXMLElement::SetAttributeValue ( const WideString &  name, const WideString &  newValue  )

pure virtual

Mutator; for attribute value, but use IXMLAttributeCommands method from client code.

Parameters

name	identifies attribute of interest
newValue	specifies new value

virtual void IIDXMLElement::SetChildAt ( const XMLReference &  newChildXMLRef, int32  indexAt  )

pure virtual

Mutator to set the specified child's XMLReference

Parameters

newChildXMLRef	specifies new child
indexAt	specifies index where child should be changed

virtual void IIDXMLElement::SetContentItem ( UID  contentItem, LayoutSelector  selector = kStandardLayout  )

pure virtual

Mutator for content item associated with this element

Parameters

contentItem
selector	default kStandardLayout (param reserved for future use)

virtual void IIDXMLElement::SetContentReference ( const XMLContentReference &  contentReference )

pure virtual

Mutator for content reference associated with this element

Parameters

contentReference

new content reference

virtual void IIDXMLElement::SetParent ( const XMLReference &  newParent )

pure virtual

Mutator for the parent element (moves the element to a new location on the hierarchy);

use IXMLElementCommands::MoveElement instead from client code.

Parameters

newParent

specifies new parent element to set for this element

virtual void IIDXMLElement::SetTag ( UID  newTag )

pure virtual

Mutator for tagname of this element; use IXMLElementCommands::SetElement rather than this from client code. Uses an IXMLTag, created perhaps with IXMLTagCommands method.

Parameters

newTag

specifies UID of an IXMLTag that contains new name for this element

virtual void IIDXMLElement::SetTag ( const WideString &  newTag )

pure virtual

Mutator for tagname, but use IXMLElementCommands::SetElement rather than this from client code.

Parameters

newTag

specifies new tagname to set for this element

virtual void IIDXMLElement::SetXMLReference ( const XMLReference &  newXMLRef )

pure virtual

Mutator to set a new persistent reference (XMLReference) for this element.

Parameters

newXMLRef

specifies the reference for this element.