StoryFragment Class

Definition

Namespace:

System.Windows.Documents.DocumentStructures

Assembly:

PresentationFramework.dll

Represents all or part of a story within an XPS document.

public ref class StoryFragment : System::Collections::Generic::IEnumerable<System::Windows::Documents::DocumentStructures::BlockElement ^>, System::Windows::Markup::IAddChild

[System.Windows.Markup.ContentProperty("BlockElementList")]
public class StoryFragment : System.Collections.Generic.IEnumerable<System.Windows.Documents.DocumentStructures.BlockElement>, System.Windows.Markup.IAddChild

[<System.Windows.Markup.ContentProperty("BlockElementList")>]
type StoryFragment = class
    interface seq<BlockElement>
    interface IEnumerable
    interface IAddChild

Public Class StoryFragment
Implements IAddChild, IEnumerable(Of BlockElement)

Inheritance

Object

StoryFragment

Attributes

ContentPropertyAttribute

Implements

IAddChild IEnumerable<BlockElement> IEnumerable

Examples

The following example shows the <StoryFragment> part of an XML Paper Specification (XPS) document.

<StoryFragment StoryName="DocumentBody" FragmentType="Content">
  <SectionStructure>
    <ParagraphStructure>
      <NamedElement NameReference="Pg1Heading1" />
    </ParagraphStructure>

    <ParagraphStructure>
      <NamedElement NameReference="Pg1P1" />
    </ParagraphStructure>

    <ParagraphStructure>
      <NamedElement NameReference="Pg1P2" />
    </ParagraphStructure>

    <ParagraphStructure>
      <NamedElement NameReference="Pg1P3" />
    </ParagraphStructure>

    <ParagraphStructure>
      <NamedElement NameReference="Pg1P4" />
    </ParagraphStructure>

    <ParagraphStructure>
      <NamedElement NameReference="Pg1P5" />
    </ParagraphStructure>

    <ParagraphStructure>
      <NamedElement NameReference="Pg1Heading2" />
    </ParagraphStructure>

    <ParagraphStructure>
      <NamedElement NameReference="Pg1P6" />
    </ParagraphStructure>

    <ParagraphStructure>
      <NamedElement NameReference="Pg1P7" />
    </ParagraphStructure>

    <TableStructure>
      <TableRowGroupStructure>

        <TableRowStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R1C1P1" />
            </ParagraphStructure>
          </TableCellStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R1C2P1" />
            </ParagraphStructure>
          </TableCellStructure>
        </TableRowStructure>

        <TableRowStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R2C1P1" />
            </ParagraphStructure>
          </TableCellStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R2C2P1" />
            </ParagraphStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R2C2P2" />
            </ParagraphStructure>
          </TableCellStructure>
        </TableRowStructure>

        <TableRowStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R3C1P1" />
            </ParagraphStructure>
          </TableCellStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R3C2P1" />
            </ParagraphStructure>
          </TableCellStructure>
        </TableRowStructure>

        <TableRowStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R4C1P1" />
            </ParagraphStructure>
          </TableCellStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R4C2P1" />
            </ParagraphStructure>
          </TableCellStructure>
        </TableRowStructure>

        <TableRowStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R5C1P1" />
            </ParagraphStructure>
          </TableCellStructure>
          <TableCellStructure>
            <ParagraphStructure>
              <NamedElement NameReference="R5C2P1" />
            </ParagraphStructure>
          </TableCellStructure>
        </TableRowStructure>

      </TableRowGroupStructure>
    </TableStructure>
  </SectionStructure>
</StoryFragment>

Remarks

An XPS story in an XPS document is roughly analogous to a story in a newspaper or magazine. It is a passage of text and graphic content, usually on a single topic, within a single XPS document. Typically, it spans multiple pages, but it can be shorter than a page like a sidebar - boxed story - in a magazine. A story can also be discontinuous like a front page newspaper story that is continued on page 4. Consequently, a given page can have more than one story and parts of more than one story. A header or footer is also a special kind of story that is entirely contained on a single page.

A StoryFragment represents all or a portion of a story. It can never span more than one page, but it can occupy the whole of a page or share a page with other fragments. If a story is on more than one page, each part of it on each page is a separate fragment. Although stories can have discontinuous sets of fragments, no fragment can itself be discontinuous.

Only a StoryFragments element can be a parent of a StoryFragment. The location of the StoryBreak elements within a StoryFragment indicates if the story is contained in multiple fragments, and if the additional fragments either precede or follow the current fragment.

When a StoryFragment ends in the middle of some structural element; say a <TableRowGroupStructure>, then XPS document-producing applications must insert an appropriate end tag for the element (in this case </TableRowGroupStructure>) before the </StoryFragment> tag, even though the structure is being continued in a later fragment. (This is necessary to ensure that the element tree within the StoryFragment is valid XML.) The fragment that continues the story must begin with an opening tag for the interrupted structure. The entire tree of interrupted structures must be treated the same way (with one exception, discussed below): End tags must be added for every unmatched start tag above the point of interruption.

The exception applies when the story interruption comes immediately after a </TableCellStructure> tag, then the producing application must insert an empty table cell structure (<TableCellStructure></TableCellStructure>) at the corresponding point in the fragment that continues the story. This is necessary so that consuming applications that need to merge all fragments of a given story can use a simple algorithm to do this.

Assume, for example, that an application wanted to add the following material to an XPS document:

<SectionStructure>  
   <TableStructure>  
      <TableRowGroupStructure>  
         <TableRowStructure>  
            <TableCellStructure>  
               <ParagraphStructure>  
                  <NamedElement NameReference="SomeContent" />  
               </ParagraphStructure>  
            </TableCellStructure>  
            <TableCellStructure>  
               <ParagraphStructure>  
                  <NamedElement NameReference="MoreContent" />  
               </ParagraphStructure>  
            </TableCellStructure>  
         </TableRowStructure>  
         <TableRowStructure>  
            <TableCellStructure>  
               <ParagraphStructure>  
                  <NamedElement NameReference="EvenMoreContent" />  
               </ParagraphStructure>  
            </TableCellStructure>  
            <TableCellStructure>  
               <ParagraphStructure>  
                  <NamedElement NameReference="LastContent" />  
               </ParagraphStructure>  
            </TableCellStructure>  
         </TableRowStructure>  
      </TableRowGroupStructure>  
   </TableStructure>  
</SectionStructure>  

If a page break forces an end to the fragment just after the </TableCellStructure> for "SomeContent", the application must create the split as shown in the following example:

<StoryFragment StoryName="MyStory" FragmentType="Content">  
 <SectionStructure>  
    <TableStructure>  
       <TableRowGroupStructure>  
          <TableRowStructure>  
             <TableCellStructure>  
                <ParagraphStructure>  
                   <NamedElement NameReference="SomeContent" />  
                </ParagraphStructure>   
             </TableCellStructure>  
<!-- lines from here to end of fragment added by producer-->  
          </TableRowStructure>  
       </TableRowGroupStructure>  
    </TableStructure>  
 </SectionStructure>  
</StoryFragment>  

<StoryFragment StoryName="MyStory" FragmentType="Content">  
 <SectionStructure>  
    <TableStructure>  
       <TableRowGroupStructure>  
          <TableRowStructure>  
             <TableCellStructure>   
              <!-- extra cell added by producer-->  
             </TableCellStructure>  
<!-- lines from here to start of fragment added by producer-->  
             <TableCellStructure>  
                <ParagraphStructure>  
                   <NamedElement NameReference="MoreContent" />  
                </ParagraphStructure>  
             </TableCellStructure>  
          </TableRowStructure>  
          <TableRowStructure>  
             <TableCellStructure>  
                <ParagraphStructure>  
                   <NamedElement NameReference="EvenMoreContent" />  
                </ParagraphStructure>  
             </TableCellStructure>  
             <TableCellStructure>  
                <ParagraphStructure>  
                   <NamedElement NameReference="LastContent" />  
                </ParagraphStructure>  
             </TableCellStructure>  
          </TableRowStructure>  
       </TableRowGroupStructure>  
    </TableStructure>  
 </SectionStructure>  
</StoryFragment>  

An application that reads the document might need to merge this content. Consider, for example, an XPS viewer with a Copy Whole Story to Clipboard button; or an XPS for the Blind application that passed stories to a voice synthesizer. Some applications that read the document may need to merge a subset of the fragments of a story. For example, a feature that copies a whole paragraph to the clipboard by triple-clicking it would need to do a merge whenever the paragraph spanned a page break, because such a paragraph would be split between two StoryFragments.

To merge use this algorithm:

1. Delete the </StoryFragment> from the end of the first fragment to be merged and delete the <StoryFragment> from the beginning of the second.

2. If the last closing tag of the first fragment is of the same type as the first opening tag of the second fragment (and they are not <NamedElement> tags), delete them both.

3. Repeat step 2 until the two fragments are in either of these states:

   • There is no longer a type match between the last end tag of the leading fragment the first start tag of the trailing fragment.

   • The last end tag of the leading fragment the first start tag of the trailing fragment are both <NamedElement> tags.

In the example above, if the empty cell had not been added by the producing application, then a merger of the fragments would produce a table whose first row had only one cell containing both the "SomeContent" and "MoreContent" references instead of the original first row with two cells, each containing a single reference

When the entire story is being merged, the algorithm should be repeated for each subsequent fragment that is part of the same story. The fragments that belong to a story are indexed in the <Story> element. See section 9.1.15 of the XML Paper Specification (XPS) specification which you can obtain at XPS: Specification and License Downloads. The last fragment for a given story will have a StoryBreak element as its last child.

Constructors

StoryFragment()

Initializes a new instance of the StoryFragment class.

Properties

FragmentName	Gets or sets the name of the story fragment.
FragmentType	Gets or sets the type of fragment.
StoryName	Gets or sets the name of the story.

Methods

Add(BlockElement)	Add a block to the story fragment.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current object. (Inherited from Object)

Explicit Interface Implementations

IAddChild.AddChild(Object)	This member supports the .NET Framework infrastructure and is not intended to be used directly from your code.
IAddChild.AddText(String)	Adds the text content of a node to the object.
IEnumerable.GetEnumerator()	This method has not been implemented.
IEnumerable<BlockElement>.GetEnumerator()	This method has not been implemented.

Extension Methods

See also

• StoryBreak
• StoryFragments