Element Initialization For Elements Not in a Tree

Some aspects of Windows Presentation Foundation (WPF) element initialization are deferred to processes that typically rely on that element being connected to either the logical tree or visual tree. This topic describes the steps that may be necessary in order to initialize an element that is not connected to either tree.

This topic contains the following sections.

• Elements and the Logical Tree
• Related Topics

Elements and the Logical Tree

When you create an instance of a Windows Presentation Foundation (WPF) class in code, you should be aware that several aspects of object initialization for a Windows Presentation Foundation (WPF) class are deliberately not a part of the code that is executed when calling the class constructor. Particularly for a control class, most of the visual representation of that control is not defined by the constructor. Instead, the visual representation is defined by the control's template. The template potentially comes from a variety of sources, but most often that template is obtained from theme styles. Templates are effectively late-binding. The necessary template is not attached to the control in question until the control is ready for layout. And the control is not ready for layout until it is attached to a logical tree that connects to a rendering surface at the root. It is that root level element that initiates the rendering of all of its child elements as defined in the logical tree.

The visual tree also participates in this process. Elements that are part of the visual tree through the templates are also not fully instantiated until connected.

The consequences of this behavior are that certain operations that rely on the completed visual characteristics of an element will require additional steps if you are attempting to get the visual characteristics of a class that was constructed but not yet attached to a tree. For instance, if you wanted to call Render on a RenderTargetBitmap and the visual you were passing was an element not connected to a tree, that element is not visually complete without running the additional initialization steps.

Using BeginInit and EndInit to Initialize the Element

Various classes in WPF implement the ISupportInitialize interface. You use the BeginInit and EndInit methods of the interface to denote a region in your code where initialization steps (such as setting property values that affect render) are contained within. After EndInit is called in the sequence, the layout system can process the element and start looking for an implicit style.

If the element you are setting properties on is a FrameworkElement or FrameworkContentElement derived class, then you can call the class versions of BeginInit and EndInit rather than casting to ISupportInitialize.

Sample Code

The following is sample code for a console application that uses rendering APIs and System.Windows.Markup.XamlReader.Load(System.IO.Stream) of a loose XAML file to illustrate the proper placement of BeginInit and EndInit around other API calls that adjust properties that affect rendering.

[STAThread]
static void Main(string[] args)
{
    UIElement e;
    string file = Directory.GetCurrentDirectory() + "\\starting.xaml";
    using (Stream stream = File.Open(file, FileMode.Open))
    {
        // loading files from current directory, project settings take care of copying the file
        ParserContext pc = new ParserContext();
        pc.BaseUri = new Uri(file, UriKind.Absolute);
        e = (UIElement)XamlReader.Load(stream, pc);
    }

    Size paperSize = new Size(8.5 * 96, 11 * 96);
    e.Measure(paperSize);
    e.Arrange(new Rect(paperSize));
    e.UpdateLayout();

    /*
     *   Render effect at normal dpi, indicator is the original RED rectangle
     */
    RenderTargetBitmap image1 = Rasterize(e, paperSize.Width, paperSize.Height, 96, 96);
    Save(image1, "render1.png");

    Button b = new Button();
    b.BeginInit();
    b.Background = Brushes.Blue;
    b.Width = b.Height = 200;
    b.EndInit();
    b.Measure(paperSize);
    b.Arrange(new Rect(paperSize));
    b.UpdateLayout();

    // now render the altered version, with the element built up and initialized

    RenderTargetBitmap image2 = Rasterize(b, paperSize.Width, paperSize.Height, 96, 96);
    Save(image2, "render2.png");
}

The example illustrates the main function only. The functions Rasterize and Save (not shown) are utility functions that take care of image processing and IO.

See Also

Concepts

Element Tree
Windows Presentation Foundation Graphics Rendering Overview
XAML Overview