// $Revision: 1.5 $
// Copyright (C) 1995 Taligent, Inc. All rights reserved.
#if 0
---------------------------------------------------------------------------
> Class:
 | THypertextScrapItem  
> Taxonomy Category:
 | Documented Samples  
 | WebRunner Sample  
> Interface Category:
 | Sample.  
> Inherits From:
 | TScrapItem 
> Inherited By:
 | None. 
> Purpose:
 | This scrap item is used to transport a block of styled text along with the title for the document and a list of all hypertext links within the text.  
> Instantiation:
 | Allocate on the heap or the stack.  
> Deriving Classes:
 | Deriving classes must properly handle the type negotiation protocol inherited from TScrapItem.  
> Concurrency:
 | _Not_ multithread safe.  
> Resource Use:
 | No special requirements.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::THypertextScrapItem ;
 | 1. THypertextScrapItem ()  
 | 2. THypertextScrapItem (const THypertextScrapItem & source)  
> Interface Category:
 | Sample.  
> Purpose:
 | 1. Default constructor.  
 | 2. Copy constructor.  
> Calling Context:
 | 1. Called by the stream-in operators and directly.  
 | 2. Called to copy an object.  
> Parameters:
 = 1. Takes no parameters.  
 = 2. const THypertextScrapItem & source -The object to copy.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::~ THypertextScrapItem ;
 | virtual ~ THypertextScrapItem ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Destructor.  
> Calling Context:
 | Called to destroy an object.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::operator =;
 | THypertextScrapItem & operator =(const THypertextScrapItem & source)  
> Interface Category:
 | Sample.  
> Purpose:
 | Assignment operator.  
> Calling Context:
 | Called when an object is assigned to another compatible object.  
> Parameters:
 = const THypertextScrapItem & source -The object to assign.  
> Return Value:
 | A non-const reference to the left-hand side object.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::operator >>=;
 | virtual TStream & operator >>=(TStream & toStream) const  
> Interface Category:
 | Sample.  
> Purpose:
 | Stream-out operator.  
> Calling Context:
 | Called to stream out data.  
> Parameters:
 = TStream & toStream -The stream the object streams itself out to.  
> Return Value:
 | Returns a reference to the stream the object streams itself out to.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::operator <<= ;
 | virtual TStream & operator <<= (TStream & fromStream)  
> Interface Category:
 | Sample.  
> Purpose:
 | Stream-in operator.  
> Calling Context:
 | Called to stream in data.  
> Parameters:
 = TStream & fromStream -The stream the object streams itself in from.  
> Return Value:
 | Returns a reference to the stream the object streams itself in from.  
> Exceptions:
 | Throws TInvalidVersionError if the object version isn't known.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::GetText ;
 | virtual const TText * GetText () const  
> Interface Category:
 | Sample.  
> Purpose:
 | Provides a way to access the text block stored in the scrap item.  
> Calling Context:
 | Call this function directly.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | Returns a pointer to the scrap item's text.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::GetTitle ;
 | virtual const TText * GetTitle () const  
> Interface Category:
 | Sample.  
> Purpose:
 | Provides a way to access the title of the hypertext in this scrap item.  
> Calling Context:
 | Call this function directly.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | Returns a pointer to the text object holding the title.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::SetTitle ;
 | virtual void SetTitle (const TText & titleText)  
> Interface Category:
 | Sample.  
> Purpose:
 | Provides a way to set the title of the hypertext in this scrap item.  
> Calling Context:
 | Called by the creator of this scrap item.  
> Parameters:
 = const TText & titleText -The text to use for the title.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::Append ;
 | virtual void Append (const TText & text)  
> Interface Category:
 | Sample.  
> Purpose:
 | Adds a piece of text onto the end of the hypertext in this scrap item.  
> Calling Context:
 | Called by the creator of this scrap item.  
> Parameters:
 = const TText & text -The text to append to this item.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::AddStyle ;
 | virtual void AddStyle (const TStyle & style, const TTextRange & at)  
> Interface Category:
 | Sample.  
> Purpose:
 | Adds a style to some range of text in this hypertext scrap item.  
> Calling Context:
 | Called by the creator of this scrap item.  
> Parameters:
 = const TStyle & style -The style to apply.  
 = const TTextRange & at -The range in this hypertext over which to apply the style.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::AddLinkRange ;
 | virtual void AddLinkRange (const TTextRange & range, const TURL & destination)  
> Interface Category:
 | Sample.  
> Purpose:
 | Adds a new hypertext link to this scrap item by marking off a range of the text that has already been inserted and telling what URL that range should lead to when a user clicks on it.  
> Calling Context:
 | Called by the creator of the scrap item.  
> Parameters:
 = const TTextRange & range -The range of text to use as the link.  
 = const TURL & destination -The location of the information to display when the link is followed.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::CreateLinkIterator ;
 | TIteratorOver < TKeyValuePair < TTextRange , TURL > > * CreateLinkIterator () const
> Interface Category:
 | Sample.  
> Purpose:
 | Provides an iterator to use to traverse all of the hypertext links found in this hypertext scrap item.  
> Calling Context:
 | Called by a recipient of a completed scrap item.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | Returns the iterator for the hypertext links.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: THypertextScrapItem::InternalCopyAvailableTypes ;
 | virtual void InternalCopyAvailableTypes (TSequenceOf < TTypeDescription > & result, TMemoryHeap & whichHeap) const
> Interface Category:
 | Sample.  
> Purpose:
 | Gets a list of all types available from this scrap item.  
> Calling Context:
 | Called by the frameworks that use scrap items. In the WebRunner sample, this is used by the Data Translation framework.  
> Parameters:
 = TSequenceOf < TTypeDescription > & result -The list of types.
 = TMemoryHeap & whichHeap -The heap to create the results on.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | Items are copied, so they must be deleted when the client is done.  
---------------------------------------------------------------------------
#endif