Export (0) Print
Expand All

StoryFragment Class

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

Namespace: System.Windows.Documents.DocumentStructures
Assembly: PresentationFramework (in presentationframework.dll)

public class StoryFragment : IAddChild
public class StoryFragment implements IAddChild
public class StoryFragment implements IAddChild
<StoryFragment .../>

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.

The following example shows the <StoryFragment> part of an XML Paper Specification (XPS) document. For the full sample, see Document Structure Sample.

<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>

System.Object
  System.Windows.Documents.DocumentStructures.StoryFragment

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0

Community Additions

ADD
Show:
© 2014 Microsoft