# CTextStory Class

Class that wraps all the methods of the ITextStory interface.

Name | Description
--- | ---
CONSTRUCTORS | Called when a class variable is created.
DESTRUCTOR | Called automatically when a class variable goes out of scope or is destroyed.
LET | Assignment operator.
CAST | Cast operator.
TextStoryPtr | Returns a pointer to the underlying ITextStory interface.
Attach | Attaches an ITextStory interface pointer to the class.
Detach | Detaches the underlying ITextStory interface pointer from the class.

### ITextStory Interface

The ITextStory interface methods are used to access shared data from multiple stories, which is stored in the parent ITextServices instance.

The stories can be “edited” simultaneously by using individual ITextRange2 methods, and displayed independently of one another. In addition, one story at a time can be UI active; that is, it receives keyboard and mouse input.

The ITextStory is a lightweight interface that does not require an ITextRange2 object. This allows the client to manipulate a story, which is a faster, smaller object than a complete editing instance.

Name | Description
--- | ---
GetActive | Gets the active state of a story.
SetActive | Sets the active state of a story.
GetDisplay | Gets a new display for a story.
GetIndex | Gets the index of a story.
GetType | Gets this story’s type.
SetType | Sets this story’s type.
GetProperty | Gets the value of the specified property.
GetRange | Gets a text range object for the story.
GetText | Gets the text in a story according to the specified conversion flags.
SetFormattedText | Replaces a story’s text with specified formatted text.
SetProperty | Sets the value of the specified property.
SetText | Sets the text in this range.

### Methods inherited from CTextObjectBase Class

Name | Description
--- | ---
GetLastResult | Returns the last result code
SetResult | Sets the last result code.
GetErrorInfo | Returns a description of the last result code.

## CONSTRUCTORS

Called when a `CTextStory` class variable is created.

    DECLARE CONSTRUCTOR
    DECLARE CONSTRUCTOR (BYVAL pTextStory AS ITextStory PTR, BYVAL fAddRef AS BOOLEAN = FALSE)

## CONSTRUCTOR (Empty)

Can be used, for example, when we have an ITextStory interface pointer returned by a function and we want to attach it to a new instance of the `CTextStory` class. To get a pointer to the ITextStory interface call the GetStory method of the CRichEditCtx class.

    DIM pCTextStory AS CTextStory
    pCTextStory.Attach(pTextStory)

## CONSTRUCTOR (ITextStory PTR)

    CONSTRUCTOR CTextStory (BYVAL pTextStory AS ITextStory PTR, BYVAL fAddRef AS BOOLEAN = FALSE)

Parameter | Description
--- | ---
pTextStory | An ITextStory interface pointer.
fAddRef | Optional. TRUE to increment the reference count of the passed ITextStory interface pointer; otherwise, FALSE. Default is FALSE.

#### Return value

A pointer to the new instance of the class.

## DESTRUCTOR

Called automatically when a class variable goes out of scope or is destroyed.

    DESTRUCTOR CTextStory

## LET

Assignment operator. The assigned pointer must be an “addrefed” one.

    OPERATOR LET (BYVAL pTextStory AS ITextStory PTR)

## CAST

Cast operator.

    OPERATOR CAST () AS ITextStory PTR

## TextStoryPtr

Returns a pointer to the underlying ITextStory interface

    FUNCTION TextRangePtr () AS ITextStory PTR

## Attach

Attaches an ITextStory interface pointer to the class.

    FUNCTION Attach (BYVAL pTextStory AS ITextStory PTR, BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT

Parameter | Description
--- | ---
pTextStory | The ITextStory interface pointer to attach.
fAddRef | TRUE to increment the reference count of the object; otherwise, FALSE. Default is FALSE.

## Detach

Detaches the interface pointer from the class

    FUNCTION Detach () AS ITextStory PTR

## GetLastResult

Returns the last result code

    FUNCTION GetLastResult () AS HRESULT

# SetResult

Sets the last result code.

    FUNCTION SetResult (BYVAL Result AS HRESULT) AS HRESULT

Parameter | Description
--- | ---
Result | The HRESULT error code returned by the methods.

## GetErrorInfo

Returns a description of the last result code.

    FUNCTION GetErrorInfo () AS CWSTR
       IF SUCCEEDED(m_Result) THEN RETURN "Success"
       DIM s AS DWSTRING = "Error &h" & HEX(m_Result, 8)
       SELECT CASE m_Result
          CASE E_POINTER : s += ": E_POINTER - Null pointer"
          CASE S_OK : s += ": S_OK - Success"
          CASE S_FALSE : s += ": S_FALSE - Failure"
          CASE E_NOTIMPL : s += ": E_NOTIMPL - Not implemented."
          CASE E_INVALIDARG : s += ": E_INVALIDARG - Invalid argument"
          CASE E_OUTOFMEMORY : s += ": E_OUTOFMEMORY - Insufficient memory"
    '      CASE E_FILENOTFOUND : s += "E_FILENOTFOUND - File not found"
          CASE &h80070002 : s += "E_FILENOTFOUND - File not found"
          CASE E_ACCESSDENIED : s += "E_ACCESSDENIED - Access denied"
          CASE E_FAIL : s += ": E_FAIL - Access denied"
          CASE NOERROR : s += ": NOERROR - Success" '' (same as S_OK)
          CASE CO_E_RELEASED:  : s += ": CO_E_RELEASED: - The object has been released"
          CASE ELSE
             s += "Unknown error"
       END SELECT
       RETURN s
    END FUNCTION

## GetActive

Gets the active state of a story.

    FUNCTION GetActive () AS LONG

#### Return value

The active state. It can be one of the following values.

Value | Meaning
--- | ---
tomDisplayActive | The story has no UI or display (fast and lightweight).
tomDisplayUIActive | The story is UI active; that is, gets keyboard and mouse interactions.
tomInactive | The story has display, but no UI.
tomUIActive | The story has display and UI activity.

#### Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

## SetActive

Sets the active state of a story.

    FUNCTION SetActive (BYVAL Value AS LONG) AS HRESULT

Parameter | Description
--- | ---
Value | The active state. It can be one of the following values.

Value | Meaning
--- | ---
tomDisplayActive | The story has no UI or display (fast and lightweight).
tomDisplayUIActive | The story is UI active; that is, gets keyboard and mouse interactions.
tomInactive | The story has display, but no UI.
tomUIActive | The story has display and UI activity.

#### Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

## GetDisplay

Gets a new display for a story.

    FUNCTION GetDisplay () AS IUnknown PTR

#### Return value

The IUnknown interface for a display.

#### Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

#### Remarks

A story can be displayed by calling SetActive(tomDisplayActive). The GetDisplay method is included, in case it might be advantageous to have more than one display for a set of ITextStory interfaces.

## GetIndex

Gets the index of this story.

    FUNCTION GetIndex () AS LONG

#### Return value

The index of the story.

#### Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

#### Remarks

The index is used with the GetStory method of the ITextDocument2 interface.

## GetType

Gets this story’s type.

    FUNCTION GetType () AS LONG

#### Return value

This story’s type. It can be any of the following values, or a custom client value from 100 to 65535.

Type | Description
--- | ---
tomCommentsStory | The story used for comments.
tomEndnotesStory | The story used for endnotes.
tomEvenPagesFooterStory | The story containing footers for even pages.
tomEvenPagesHeaderStory | The story containing headers for even pages.
tomFindStory | The story used for a Find dialog.
tomFirstPageFooterStory | The story containing the footer for the first page.
tomFirstPageHeaderStory | The story containing the header for the first page.
tomFootnotesStory | The story used for footnotes.
tomMainTextStory | The main story always exists for a rich edit control.
tomPrimaryFooterStory | The story containing footers for odd pages.
tomPrimaryHeaderStory | The story containing headers for odd pages.
tomReplaceStory | The story used for a Replace dialog.
tomScratchStory | The scratch story.
tomTextFrameStory | The story used for a text box.
tomUnknownStory | No special type.

#### Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

## SetType

Sets this story’s type.

    FUNCTION SetType (BYVAL Value AS LONG) AS HRESULT

Parameter | Description
--- | ---
Value | This story’s type. It can be any of the following values, or a custom client value from 100 to 65535.

Type | Description
--- | ---
tomCommentsStory | The story used for comments.
tomEndnotesStory | The story used for endnotes.
tomEvenPagesFooterStory | The story containing footers for even pages.
tomEvenPagesHeaderStory | The story containing headers for even pages.
tomFindStory | The story used for a Find dialog.
tomFirstPageFooterStory | The story containing the footer for the first page.
tomFirstPageHeaderStory | The story containing the header for the first page.
tomFootnotesStory | The story used for footnotes.
tomMainTextStory | The main story always exists for a rich edit control.
tomPrimaryFooterStory | The story containing footers for odd pages.
tomPrimaryHeaderStory | The story containing headers for odd pages.
tomReplaceStory | The story used for a Replace dialog.
tomScratchStory | The scratch story.
tomTextFrameStory | The story used for a text box.
tomUnknownStory | No special type.

#### Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

## GetProperty

Gets the value of the specified property.

    FUNCTION GetProperty (BYVAL nType AS LONG) AS LONG

Parameter | Description
--- | ---
nType | The ID of the property. Currently, no extra properties are defined.

#### Return value

The property value.

#### Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

## GetRange

Gets a text range object for the story.

    FUNCTION GetRange (BYVAL cpActive AS LONG, BYVAL cpAnchor AS LONG) AS ITextRange2 PTR

Parameter | Description
--- | ---
cpActive | The active end of the range.
cpAnchor | The anchor end of the range.

#### Return value

The text range object.

#### Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

## GetText

Gets the text in a story according to the specified conversion flags.

    FUNCTION GetText (BYVAL Flags AS LONG) AS DWSTRING

Parameter | Description
--- | ---
Flags | The conversion flags. A Flags value of 0 retrieves text the same as ITextRange.GetText. Other values include the following: tomAdjustCRLF, tomAllowFinalEOP, tomFoldMathAlpha, tomIncludeNumbering, tomNoHidden, tomNoMathZoneBrackets, tomLanguageTag, tomTextize, tomTranslateTableCell, tomUseCRLF.

#### Return value

The text in the story.

#### Result code

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code | Description
--- | ---
E_INVALIDARG | Invalid argument.
E_ACCESSDENIED | Write access is denied.
E_OUTOFMEMORY | Insufficient memory.

#### Remarks

This method is similar to using ITextRange2.GetText2 for a whole story, but it doesn’t require a range.

## SetFormattedText

Replaces a story’s text with specified formatted text.

    FUNCTION SetFormattedText (BYVAL pUnk AS IUnknown PTR) AS HRESULT

Parameter | Description
--- | ---
pUnk | The formatted text to replace the story’s text.

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code | Description
--- | ---
E_INVALIDARG | Invalid argument.
E_ACCESSDENIED | Write access is denied.
E_OUTOFMEMORY | Insufficient memory.

#### Remarks

This method calls IUnknown.QueryInterface for an ITextRange2 interface.

## SetProperty

Sets the value of the specified property.

    FUNCTION SetProperty (BYVAL nType AS LONG, BYVAL VaLue AS LONG) AS HRESULT

Parameter | Description
--- | ---
nType | The Microsoft accountID that identifies the property. Currently, no extra properties are defined.
Value | The new property value.

#### Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

## SetText

Replaces the text in a story with the specified text.

    FUNCTION SetText (BYVAL Flags AS LONG, BYREF wszText AS WstRING) AS HRESULT

Parameter | Description
--- | ---
Flags | Flags controlling how the text is inserted as defined in the following table: tomCheckTextLimit, tomMathCFCheck, tomUnhide, tomUnicodeBiDi, tomUnlink.
wszText | The new text for this story. If this parameter is ““, the text in the story is deleted.

#### Return value

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code | Description
--- | ---
E_INVALIDARG | Invalid argument.
E_ACCESSDENIED | Write access is denied.
E_OUTOFMEMORY | Insufficient memory.