O'Reilly Longhorn Annotations

Appling Effects to Markup

Ian Griffiths, O'Reilly & Associates, Inc. — Tue, 28 Oct 2003 17:58:36 PST

I spent a while trying to work out how to apply an ImageEffect such as an ImageGlow to some markup. There's an obvious problem with trying to do this: ImageEffects are bitmap effects, but XAML is not about bitmaps. This didn't seem like it should be a problem, as there's obviously something in the system capable of rasterizing the XAML - it's in pixel form by the time you see it on screen. So I was looking for something similar to the way in which GDI+ lets you create a Graphics object that draws directly into a bitmap.

Unfortunately, it turns out that you can't do this...yet. Greg Schecter gave a talk at the PDC on the Avalon media architecture, so I asked him about this. The version of Longhorn released at the PDC doesn't provide the ability to do this - the features to allow markup to be rendered into bitmap or video streams are planned but not yet present.

The pleasing news was that not only is this coming, they also plan to support the application of bitmap-based image effects to markup directly. So there will be some fairly straightforward way of getting Avalon to transform your XAML to a bitmap and apply one or more effects for you. It's nice to know it's on its way, even if it isn't here yet. (I just wish I'd known before I spent a day trying to work out how to do it! :-) )

Using an ImageEffect

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 03:53:43 PST

I was unable to find any examples on how to use the various ImageEffects either in code or in markup. I can't work out how to use these from markup, but here's a way of setting an Image control's source to use an image effect in code. Given the following markup:

<FlowPanel xmlns="http://schemas.microsoft.com/2003/xaml/"
  xmlns:def="Definition" def:Class="Default"
  Loaded="OnLoaded">

  <Image ID="img"/>

</FlowPanel>

we can use the following codebehind to set the Image's source to use an ImageEffect:

using System;
using System.IO;
using MSAvalon.Windows.Media;

namespace Ian
{
  public partial class Default
  {
    private void OnLoaded(object sender, EventArgs e)
    {
      using (Stream stm = File.OpenRead("btn.png"))
      {
        ImageData src = new ImageData(stm);
        ImageEffectGlow glow = new ImageEffectGlow();
        glow.Input = src;
        ImageData output = new ImageData(glow.Output, false, 
                new IntegerRect(), new ImageSizeOptions(), false);
        img.Source = output;
      }
    }
  }
}

(Here, "btn.png" is a bitmap file - use whatever bitmap source you like.) This loads a bitmap, and then sets it as the input to an ImageEffectGlow. It then builds a new ImageData from the effect's output - the Image control requires its Source property to be set to an object of type ImageData.

Building an ImageSource From Scratch

Ian Griffiths, O'Reilly & Associates, Inc. — Tue, 28 Oct 2003 18:01:53 PST

In classic GDI+ it's easy to create your own Bitmap and then obtain a Graphics object that lets you draw into it. It's not obvious if you can do the same thing in Avalon - ImageSource appears to act as a source of bitmap data, but it's not clear how to build one from scratch.

If you don't mind generating the raw bytestream then it's pretty easy. But what I want to be able to do is take some markup (or maybe a Drawing object) and turn it into an ImageSource. Why? Because I'd like to be able to apply some of the ImageEffects like ImageEffectGlow or ImageEffectTint to bits of markup. ImageEffects are all bitmap-based effects - they work on pixel data. So you need to give them an ImageSource as their input. If there were a way of converting markup into bitmap data then you could apply these effects to markup too. But unfortunately, the PDC version of Longhorn doesn't support this.

In his talk on the Avalon Media layer at the PDC, Greg Schecter talked about 'top level objects' - these are the things that will apparently allow XAML to be converted to bitmaps or video streams. (XAML supports animation, so you might want to generate a sequence of bitmaps from it.) These are coming, but they're not in the build given out at the PDC.

Abbreviated Path Data Syntax

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 02:46:13 PST

In a few examples scattered around the SDK, the Path element is shown with its Data property set to a text string, rather than being set as a complex property containing a GeometryCollection. This allows a much more succinct expression of a path. For example:

<Path Stroke="Black" 
  Data="m 10,50 C 10,30 30,10 50,10 C 70,10 80,20 80,30 C 80,40 70,50 60,50 C 50,50 40,40 40,30 C 40,20 50,10 70,10 C 90,10 110,30 110,50 C 110,70 90,90 60,90 C 30,90 10,70 10,50 z"/>

This contains a StartSegment, 8 BezierSegments, and a CloseSegment. It avoids the boilerplate for the complex property approach - this requires Path.Data, GeometryCollection, PathGeometry, PathGeometry.Figures, PathFigureCollection, PathFigure, and PathSegmentCollection XML elements to be added before we even get to the main path data. The only syntactic disadvantages with this terse approach are that it results in an overly long line (you cannot split the value of an attribute across multiple lines in XML).

For some reason however, the syntax is undocumented. The few examples in the SDK allow us to determine a few: M moves to a new position, C draws a Bezier curve. H and V draw horizontal and vertical line sections. Z closes a figure. (Or is that clozes?) The use of uppercase vs. lowercase for these commands appears to select between relative and absolute coordinatates.

But what about ArcSegment, LineSegment, and QuadraticBezierSegment? Presumably there are commands for these. It would be nice to have the documentation for them!

EvenOdd vs NonZero Fill Rules

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 02:45:28 PST

The distinction between these two fill rules (or 'winding' rules as they are sometimes known) is not immediately obvious, since for some shapes the two rules behave in exactly the same way. (And at the time of writing this annotation, this page has no explanatory text at all, which makes it even harder to discern the meaning!) The distinction is only important when a shape has areas which are enclosed by more than one outline.

There are two ways this can happen. First, a path may contain multiple figures. If one figure is either completely inside another, or if two overlap, then some areas of the shape will be inside both figures. Second, a path may overlap itself - since a path can be any shape, the path's outline can intersect itself. Again, this results in there being certain areas of the shape being multiply enclosed; there may be only one outline, but because it intersects itself, it would be necessary to cross the outline twice to get from the doubly enclosed area to a point entirely outside of the shape.

A question arises for these cases: if the shape has a Fill set, should the multiply-enclosed areas be filled? The FillRule answers this.

The EvenOdd rule is the simplest. It says that whether or not a region is filled depends on whether there are an even or an odd number of boundaries between the region and the outside of the shape. This means that each time an edge is crossed, we alternate between filling and not filling.

The NonZero rule is a little more peculiar. It takes the direction in which the edge is drawn into account. Executing the NonZero rule is equivalent to the following process: to determine whether a given point is filled, draw a line between that point and any point outside of the shape. For each edge of the shape that this line crosses, either add or subtract one from the running total; whether you add or subtract depends on the direction in which the edge is travelling. (The direction of travel is that which you get by tracing round the shape, following the points in the path data in the order in which they are defined.)

For example, consider a path consisting of two concentric circular figures. If the two circles were drawn with path data running in the same direction, the count for the innermost region will be either 2 or -2 depending on the direction of the circles. Either way it's non-zero, which means the area is filled. But if one of the circles is drawn in the opposite direction from the other, the count will be zero - one edge will cancel out the other. So even though the outline of the shape looks the same - two concentric circles - the direction of travel determined which regions were filled.

It's often best to try a real example. The following shape yields different results with the two rules:

<Canvas>
  <Path Stroke="Black" Fill="Green" FillRule="EvenOdd"
        Data="m 10,50 C 10,30 30,10 50,10 C 70,10 80,20 80,30 C 80,40 70,50 60,50 C 50,50 40,40 40,30 C 40,20 50,10 70,10 C 90,10 110,30 110,50 C 110,70 90,90 60,90 C 30,90 10,70 10,50 z"/>

  <Path Stroke="Black" Fill="Green" FillRule="NonZero" Canvas.Top="100" 
        Data="m 10,50 C 10,30 30,10 50,10 C 70,10 80,20 80,30 C 80,40 70,50 60,50 C 50,50 40,40 40,30 C 40,20 50,10 70,10 C 90,10 110,30 110,50 C 110,70 90,90 60,90 C 30,90 10,70 10,50 z"/>
</Canvas>

However, this shape yields the same results for either rule:

<Canvas>
  <Path Stroke="Black" Fill="Green" FillRule="EvenOdd"
        Data="m 10,50 C 10,30 30,20 40,20  C 60,20 60,50 80,50 C 90,50 100,40 100,30 C 100,20 80,10 60,10 C 40,10 20,20 20,30 C 20,40 30,50 40,50 C 60,50 60,20 80,20 C 90,20 110,30 110,50 C 110,70 90,90 60,90 C 30,90 10,70 10,50 z"/>

  <Path Stroke="Black" Fill="Green" FillRule="NonZero" Canvas.Top="100" 
        Data="m 10,50 C 10,30 30,20 40,20  C 60,20 60,50 80,50 C 90,50 100,40 100,30 C 100,20 80,10 60,10 C 40,10 20,20 20,30 C 20,40 30,50 40,50 C 60,50 60,20 80,20 C 90,20 110,30 110,50 C 110,70 90,90 60,90 C 30,90 10,70 10,50 z"/>
</Canvas>

Logical Tree -> XAML

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 02:42:35 PST

Although your XAML source is not preserved by the compilation process, it is still possible to generate an XAML representation of your UI using the XamlRootSerializer class:

using System.IO;
using System.ComponentModel.Design.Serialization;
using MSAvalon.Windows;
using MSAvalon.Windows.Serialization;

public class XmlSaver
{
  public static void SaveAsXaml(FrameworkElement elem, string fileName)
  {
    XamlRootSerializer xamlSer = new XamlRootSerializer();
    DesignerSerializationManager dsm = new DesignerSerializationManager ();

    using (dsm.CreateSession())
    {
      using (StreamWriter w = new StreamWriter(File.OpenWrite(fileName)))
      {
        xamlSer.SerializeObjectTree(dsm, w, elem);
      }
    }
  }
}

This produces XAML which is likely to be considerably more verbose than your original markup. But it can still be useful to get markup even if it's not the original.

StartPoint and EndPoint Coordinates

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 02:41:08 PST

A linear gradient brush must specify the start and end points of the fill. This is done with the StartPoint and EndPoint properties, but it's not immediately obvious how these will be interpretted. If you are using absolute positioning on a Canvas, and you attempt to set the fill start and end points using the coordinate system of the Canvas, you will not get the results you require.

By default, the StartPoint and EndPoint of a brush use a coordinate system which is relative to the brush itself: the top left of the brush is at (0, 0), and the bottom right is at (1, 1). For a Rectangle, this is pretty straightforward, but for other shapes it is less clear - where are the corners of a brush when it is applied to some text? Is it the bounding box of the glyphs? Does it take into account the line spacing? A simple experiment lets us find out:

<DockPanel xmlns="http://schemas.microsoft.com/2003/xaml/">

  <TextBox DockPanel.Dock="Top" FontSize="72" Height="100"
           Foreground="VerticalGradient Black White" />

</DockPanel>

This applies a vertical gradient fill from black to white across the brush for the text of a TextBox. If you type in some lowercase letters with no ascenders or descenders (e.g, "ooeeooeeoo") you will see that the tops of the letters are completely black and the bottoms are completely white. But if you now type in either an uppercase letter, or a lowercase letter with an ascender (e.g. "b" or "i"), you will see that the range of the brush changes - it will now start from the top of the ascender. This has the effect of changing the appearance of the other letters typed in so far - the tops of the smaller letters will go from being black to grey when you add a taller letter. Likewise, if you add a letter with a descender (e.g. "y" or "j") you will find the the fill becomes larger again, so that it does not become completely white until the bottom of the descenders. Again, this changes the appearance the letters that were there before.

This reveals that the brush bounds are the same as the bounds of the letter outlines. While this makes sense, it's rather inconvenient. What if I actually wanted the text in my textbox to use a vertical linear gradient that stayed still? The problem with this example is that the fill moves as the user types in letters.

Fortunately, the MappingMode property comes to the rescue. MappingMode lets us chose whether the coordinate system of the Brush is relative to its bounding box, or the coordinate system of the containing panel. The following example uses this property to apply a fill to the text whose range is fixed regardless of the actual bounding box of the text:

<DockPanel xmlns="http://schemas.microsoft.com/2003/xaml/">

  <TextBox DockPanel.Dock="Top" FontSize="72" Height="100">
    <TextBox.Foreground>
      <LinearGradientBrush MappingMode="Absolute"
           StartPoint="0,0" EndPoint="0,100">
        <LinearGradientBrush.GradientStops>
          <GradientStopCollection>
            <GradientStop Color="Black" Offset="0"/>
            <GradientStop Color="White" Offset="1"/>
          </GradientStopCollection>
        </LinearGradientBrush.GradientStops>
      </LinearGradientBrush>
    </TextBox.Foreground>
  </TextBox>

</DockPanel>

Sadly this is much more verbose. As far as I can tell, the MappingMode property can only be set if you abandon the abbreviated gradient fill syntax. However, this just makes the markup larger - there isn't any extra runtime cost associated with this. (The abbreviated syntax expands out to the same code as the more verbose syntax.)

Resolution Independence

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 02:38:49 PST

One of the unit types supported by this enumeration is Pixel. However, despite what the name suggests, this is a resolution-independent unit - it means 1/96 inch. As it happens, if you are running Windows with 'small fonts' Windows assumes by default that your display resolution is 96dpi, so one UnitType.Pixel happens to map onto one screen pixel. But if your screen has a higher resolution (and Windows is aware of this fact) one UnitType.Pixel will be several physical pixels wide. (It would be less than a physical pixel wide if you had a very low resolution device). One UnitType.Pixel might not even map to a whole number of physical pixels.

All measurement in Avalon is device-independent. This means that a visual element can be given an absolute size, independent of display or output technology. There are a number of advantages to this approach. It means that when a document is printed, everything should remain the same size. (Printers often have a very high resolution. If you write Win32 code that works in terms of pixels, it can end up producing incredibly small drawings when printing.) It also means that programs can look right on very high resolution displays - it is possible to build flat panel displays with a resolution of 300dpi or better, but these are currently unusable with Windows because too many programs use physical pixels for their measurements. Such programs end up with an unusably small user interface. But with Avalon's resolution independence, it will start to become practical for very high resolution screens to come out of the research labs and onto our desktops.

Another advantage of resolution independence is that all displays are intrinsically scalable. This means that you can enlarge or reduce the display to an arbitrary size by applying a transformation. This is a lot more flexible than using a simple screen magnifier (and the results look better). The following markup example shows how this would look:

<Canvas xmlns="http://schemas.microsoft.com/2003/xaml">
  <TransformDecorator>
    <TransformDecorator.Transform>
      <ScaleTransform ScaleX="4" ScaleY="4"/>
    </TransformDecorator.Transform>

  <Button Canvas.Top="2" Width="100" Height="20">
    Click me
  </Button>

  </TransformDecorator>

  <Button Canvas.Top="110" Width="400" Height="80">
    Click me
  </Button>

</Canvas>

This example enlarges a button to four times its normal size. This is not the same as simply setting a button's width and heigh to four times the size. To illustrate the difference, this example contains two buttons. The first has been scaled up, while the second is simply very large. The most obvious difference is that with the second button, the text has remained at the default size, which wouldn't be much use if your intention was to improve readability. Compare this with the first button, where all of its features have been enlarged.

The '' Processing Instruction

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 02:37:37 PST

Many of the examples (including some on this page) have XML Processing Instructions of the form:

<?Mapping XmlNamespace="media" ClrNamespace="MSAvalon.Windows.Media"
Assembly="PresentationCore"?>

I couldn't find this documented anywhere, but it appears to control the mapping between XML Namespaces and .NET Namespaces. There is a small amount of documentation for the programmatic aspects of this mapping to be found in the MSAvalon.Windows.Serialization.Mapper class, but apparently nothing describing how these mappings are dealt with in markup.

Most of the time, the mapping between markup elements and .NET classes is apparently magic - we can just use element names such as <Text> or <Ellipse>, and the XAML compiler somehow works out that the first should be in the MSAvalon.Windows.Controls and MSAvalon.Windows.Shapes namespaces respectively.

I don't know how these built-in element name mappings are handled. But the Mapping processing instruction allows us to use classes which XAML doesn't support intrinsically. If you wish to use a particular class, you simply add a Mapping instruction which defines the namespace and assembly name in which the class is defined, and assign this to an XML namespace URI of your choosing. Any elements you place in this namespace in the XAML will then use classes from the selected namespace and component. For example, given the declaration above, the following element:

<GradientBrush xmlns="media" ... />

explicitly refers to the MSAvalon.Windows.Media.GradientBrush class defined in the PresentationCore assembly.

Beyond Simple Images or Text

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 07 Nov 2003 10:15:08 PST

The examples on this page show two buttons, one containing just Text, and one containing just an image. In fact it is possible to build much more interesting-looking buttons than this. Button derives from ContentControl, which means that it contains some more markup as its content. Typically this content will just be some text, but in fact it could be any markup; the Image element used here is just one example. Here's a more interesting one:

<Canvas xmlns="http://schemas.microsoft.com/2003/xaml">
  <Button ID="btn1" Canvas.Top="2" Width="100" Height="20">
    <FlowPanel>
    <Canvas Button.VerticalAlignment="Center">
      <Ellipse Width="20" Height="20" CenterX="10" CenterY="10" Fill="Yellow" Stroke="Black"/>
      <Ellipse RadiusX="2" RadiusY="2" CenterX="7" CenterY="8" Fill="Black"/>
      <Ellipse RadiusX="2" RadiusY="2" CenterX="14" CenterY="8" Fill="Black"/>
      <Path Stroke="Black" Data="M4,12 C 4,18 16,18 16,12"/>
    </Canvas>
      <Text Height="20" Margin="5,0,0,0">Click me!</Text>
    </FlowPanel>
  </Button>
</Canvas>

This makes the content of the button a FlowPanel, which allows us to embed arbitrary flowing content inside the button. In this case we have two elements: a Canvas and some Text. The Canvas in turn contains some markup to draw a smiley face onto the button. So you're not restricted to just using bitmaps if you want to draw graphics on your buttons.

Full Trust for Page Functions?

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 02:35:05 PST

This page makes the following rather remarkable claim:

"Because page-function applications depend on reflection, they must run with full trust."

If this were true, then surely you would never want to use page functions - requiring full trust instantly makes deployment much harder. But apart from the fact that requiring full trust for something as basic as navigation would be really bad, there are other reasons to doubt this claim. Why do page function applications depend on reflection? Certainly none of the example code on this page uses reflection. (Maybe Avalon uses reflection internally to make page functions work, but that doesn't require my application to have full trust.) And even then, use of reflection doesn't require full trust - partially-trusted code can reflect against public members. And reflection against private members only requires the appropriate flag to be enabled on the SecurityPermission, rather than requiring full trust.

So it seems implausible. I really hope it's untrue. (I would say that I hoped it was just a typo, but it's clearly more than that - there are three paragraphs and two XML fragments devoted to the subject!)

PageFunctions and Generics

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 24 Oct 2003 02:34:52 PST

PageFunction is the base class of the various type-specific page function classes such as StringPageFunction or BoolPageFunction. The documentation implies that you should use these derived classes, and that using the base class directly is not supported. However, the compiler tells another story. If you try to use one of the derived classes, the compiler issues a warning telling you that the class is obsolete, and that you should use PageFunction instead!

PageFunction is a generic class. This means that if your language supports generics, there is no need for the specific derived types. For example, in C#, rather than using the StringPageFunction, you can just use PageFunction. You could even use your own custom type, e.g. PageFunction, although it's not clear how you would map this into markup.

In trying to get the example on this page running, I've could only get it to work by using the generics-based event handling. The example here uses this (non-generics-based) code to attach an event handler:

next.NonGenericReturn += new StringReturnEventHandler(task1_Return);

When I try this, task1_Return does not get called when the page returns. However, if I write the generic equivalent:

next.Return += new ReturnEventHandler (task1_Return);

and modify the event handler method to use generics too:

public void task1_Return(object sender, ReturnArgs e)
{
    task1Return.TextRange.Text = e.Result;
}

I find that my event handler now gets called correctly. So from this, it would appear that the compiler warnings tell us the right way to go: use generics here.

Different Trees?

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:54:57 PST

This page implies that the Generic Logical Tree and the Logical Tree are two different trees. This is potentially confusing, because in either case you are accessing the exact same nodes. A Logical Tree is technically not the same tree simply because it is usually a subset of the whole Generic Logical tree, but it is helpful to be aware that these are really just two different ways of accessing the same objects.

For example, consider the Text element in the example on this page that displays the Generic Logical Tree. (The first example in the "Using the Generic Logical Tree" section.) The Text class derives from FrameworkElement, and FrameworkElement implements ILogicalTreeNode. So when you get hold of the ILogicalTreeNode implementation that represents the Text element, it's really an object of type Text. Moreover, it's the very same Text object you would have got using the Logical Tree. It's easy to verify this. We can add some code in the loop inside the FindIt method, modifying the innermost if block so that it looks like this:

if(childNode != null)
{
  Elements = Elements + "\n" + childNode.GetType();
  // ADDED CODE: see if this is the same node as we can
  // get from the Logical Tree
  if (object.ReferenceEquals(childNode, Text1))
  {
    Elements += " (exact same object reference as Text1 in logical tree)";
  }
  // END OF ADDED CODE.
  FindIt(childNode);
}

This modified version of FindIt checks each node it finds in the Generic Logical Tree, using the object.ReferenceEquals method to find out whether this is the exact same object as the Text1 node in the Logical Tree. Lo and behold, when we run it we get this output:

List of Logical Elements on page:
MSAvalon.Windows.Controls.Text (exact same object reference as Text1 in logical tree)
MSAvalon.Windows.Controls.DockPanel
...

The object representing the Text node in the Generic Logical Tree is the same object that represents the same Text node in the logical tree. The only difference is whether we use it via its concrete class interface, or the generic ILogicalTreeNode interface. So when this page talks about the Generic Logical Tree, it is describing the use of the generic ILogicalTreeNode interface to access the tree nodes. When it talks about the Logical Tree, it means the use of the concrete element-specific class interfaces to access the very same tree nodes.

This page also mentions the Visual Tree. So is that a different tree? FrameworkElement derives from Visual, so everything in the Logical Tree is by definition also in the Visual Tree. However, it is possible for the Visual Tree to contain Visuals which are not in the Logical Tree. So it's not quite the same - some nodes in the Visual tree may not feature in the Logical Trees, but any object in a Logical Tree will also be in the Visual Tree.

Commands Don't Work in Markup

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:54:38 PST

If you try to set this Command property on a MenuItem in markup, it doesn't seem to work. (At least not if you're building your markup. If you just run the XAML file directly it seems to be OK. However, you can only run XAML files directly if they contains no code. If you're building menu items, you will need some code behind them if they're going to do anything useful, so this property is effectively unusable in XAML.)

If you try to set a Command attribute you get the error "TypeConverter cannot converted from System.String". The reason turns out to be that although the Command class itself does have a TypeConverterAttribute applied to it, the attribute isn't quite right. (TypeConverters are used to convert from one representation to another - in this case they are being used to convert from the text value of the attribute stored in the XAML to a real Command object.) So if you try to obtain the TypeConverter for a Command (using TypeDescriptor.GetConverter) you get back a generic base TypeConverter rather than CommandConverter, which is what you're supposed to get here. The base TypeConverter doesn't know what to do here, and throws an exception.

Because this is a problem with the Command class, it applies to any property of type Command. So not only do the Samples that attempt to use the MenuItem's Command property fail at runtime, so will anything else that tries to use Command, such as the CommandLink property of the UIElement class.

The current workaround is not to try and use the Command architecture. (So the whole MSAvalon.Windows.Commands namespace is pretty much off limits...) You can instead handle low level events like Click.

Applicability of attr="{resname}" Syntax

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:53:05 PST

Something that wasn't obvious to me from the documentation was whether this attribute="{resourceName}" syntax could be applied to any attribute, or whether it was something that only certain attribute types recognize. It looks like this is universally applicable. The markup compiler appears to convert this into the following code:

element.SetResourceReference(WhicheverProperty, "resourceName");

('WhicheverProperty' will be the public static member defining the property being set. For example, if you set the Text property of a SimpleText element, this will be MSAvalon.Windows.Controls.SimpleText.TextProperty.) This causes the value to be set at runtime to whatever that resource's value is.

Scope of Resources

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:52:26 PST

The examples on this page all show resources being used within the same markup tree in which they are defined. However, it doesn't have to be this way. A resource reference of the form <SomeElement SomeAttr="{resourceName}"/> can look in several places for the definition of the 'resourceName' resource.

Avalon will look for the resource definition closest in scope to the reference. So if the element referring to some resource 'foo' defines the 'foo' resource in its own Resources, this will override any other definitions. But since resource definitions are usually employed to allow reuse of markup, it is more normal for the resource to be defined in some containing element. Avalon therefore walks its way up the element tree until it finds the relevant definition. For example:

<FlowPanel xmlns="http://schemas.microsoft.com/2003/xaml/"
  xmlns:def="Definition">

  <FlowPanel.Resources>
    <Style def:Name="MyStyle">
      <SimpleText Foreground="Red"/>
    </Style>
  </FlowPanel.Resources>

  <SimpleText Style="{MyStyle}" Text="Hello">
    <SimpleText.Resources>
      <Style def:Name="MyStyle">
        <SimpleText Foreground="Yellow"/>
      </Style>
    </SimpleText.Resources>
  </SimpleText>
  <SimpleText Style="{MyStyle}" Text="World">

</FlowPanel>

Here, the first <SimpleText> element refers to 'MyStyle', but also defines MyStyle, so it will come out as yellow text. But the second element, which also refers to 'MyStyle', does not have resources of its own. This means that it picks up the definition of this style supplied by its ancestor element, the <FlowPanel>.

But what if there were a reference to a style not defined anywhere in the markup, e.g. 'MyOtherStyle'? In this case, since Avalon cannot find the resource in this markup file, it will look to see if there are any application resources of that name - these are resources defined in the markup for the main application markup file. Finally, if it cannot find the resource in either the markup or the main application, it will consult the SystemResources, which contains global resources determined by the selected system theme.

Types of Resources

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:51:50 PST

Many of the examples with resources in markup use Style elements for the resources. But there are also examples showing things like brushes. This made me wonder: what kinds of elements are you allowed to use as resources? Are there any restrictions, or is anything fair game?

The FrameworkElement.Resources property is of type ResourceDictionary, which derives from Hashtable. A Hashtable entry can have anything as its value, so if you write code to populate the Resources, you really can put anything in there. This made me wonder if you could put, say, a String in there in markup. It turns out that you can, although just using <String> doesn't work - this is not a recognised XAML element. However, by adding a Mapping processing instruction to associate an XML namespace with a .NET namespace and assembly, we can use the System.String type as a resource:

<?Mapping XmlNamespace="sys" ClrNamespace="System" Assembly="mscorlib"?>

<FlowPanel xmlns="http://schemas.microsoft.com/2003/xaml/"
  xmlns:sys="sys"
  xmlns:def="Definition">

  <FlowPanel.Resources>
    <sys:String def:Name="TextInRes">This is some text in a resource</sys:String>
  </FlowPanel.Resources>

  <SimpleText Text="{TextInRes}"/>

</FlowPanel>

The rest of the gallery

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:50:32 PST

I expect this will be fixed sooner or later, but at time of writing this, the page contains a single XAML example. This example doesn't work on its own - it's just one page from an application. To see this in action, you will need to build the 'Layout Style Gallery ("XAML")' example in the Samples section of the documentation. The XAML shown here is just the 'chrome.xaml' page from that sample.

Margins, Borders, and Padding

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:50:22 PST

If you are familiar with the CSS2 formatting model from HTML, you may be wondering if you achieve the same padding, border, and margin effects that HTML offers in XAML. At first glance it looks like you can't. This Margin property works in the same way as a CSS2 - it determines the amount of space left around sides of the element - but what about the border and the padding? In HTML it is possible to get an outline (or 'border') drawn around an element, and to specifiy the space (or 'padding') between the border and the content.

It is entirely possible to achieve this effect with XAML. There is a Border element you can wrap around any other element. For example:

<Border Margin="5,5,5,5" BorderBrush="Blue" BorderThickness="2">
  <Text Margin="3,3,3,3">I'm in a box.</Text>
</Border>

This displays the text "I'm in a box" inside a blue border. It has a 5 pixel margin around the border, and 3 pixels of padding between the border and the content. Although this style requires two elements rather than one, it is conceptually slightly simpler than the HTML equivalent because there is no need for two seperate concepts of padding and margin. There is simply the margin around the content, and the margin around the border.

Can we also have a TryAccess please?

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:49:48 PST

I like this kind of thing - it enables me to get the compiler to write my finally blocks for me, which is a Good Thing. I like my code to be uncluttered.

Unfortunately, this suffers from the same problem that has long annoyed me with the C# lock construct - it provides no way of passing in a timeout. I'm always loath to write production code that waits indefinitely for anything. So I never use the lock keyword in production code. In fact I usually end up writing a small utility class with a method that looks just like this method, but which locks the object you pass in using Monitor.TryEnter. I throw an exception if the timeout expires. It would be really nice to have the same thing here - we have both Enter and TryEnter, so since we have Access, can't we also have TryAccess?

Of course some would argue that indicating a timeout via an exception is a misuse of exceptions. In some situations, yes it would be, but there are plenty of situations where you can say "If I have to wait as long as a minute for this, something is badly wrong somewhere", and throwing an exception would be an appropriate thing to do. You could just make it return null instead, but that tends to end up looking messy, and isn't really appropriate in the case where a timeout really does indicate a problem

Prefer Access to Enter

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:49:11 PST

If you ever Enter a UIContext, you will of course need to make absolutely sure that you leave it again when you're done. You could of course do this by writing a try ... finally block, and calling Exit on the context in the finally block. But in C# it's much easier to use the UIContext.Access method instead. That returns an IDisposable object which exits the context in its Dispose method. This means you can just do this:

using(someUIContextObj.Context.Access())
{
  ... use the UIContextObj ...
} // UIContext.Exit() called here automatically

and the C# compiler will generate the finally block for you. Of course it just calls Dispose on the object that Access() returned, but that object in turn leaves the context for you.

Responsibility for Checking UIContext

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:47:49 PST

By deriving from UIContextObject, a class advertises the fact that it does not support multithreading, and must always be accessed from a particular context. This is good because it makes explicit something that was not immediately obvious in Windows Forms. Windows Forms controls always had to be accessed from the thread on which they were created; getting this wrong caused subtle and hard to find problems. Lots of people got this wrong.

What's not immediately obvious is who is responsible for entering and leaving the context, and for detecting attempts to call from the wrong context. Callers should ensure they are in the right context, but UIContextObject-derived objects are required to perform the check by calling Context.VerifyAccess() on themselves. This call will raise a UIContextAccessException if the caller is in the wrong context, making it instantly obvious that something is wrong. (Much better than in Windows Forms, where the results of such an error are usually much more subtle.)

If you are familiar with ContextBoundObject, it's particularly important to note that UIContextObject works differently. While calls into a ContextBoundObject would automatically be intercepted and delivered into the correct context, this does not happen here - the caller is responsible for making sure they're in the right context before making the call.

MIL

Ian Griffiths, O'Reilly & Associates, Inc. — Fri, 10 Oct 2003 08:50:06 PST

This article talks about the CS_MIL style for making Avalon functionality available in a window from Win32. I had seen the abbreviation MIL dotted around the documentation and wondered what it meant. Sometimes Avalon is refered to as Avalon MIL in the documentation. Some interface and type names have MIL in them. The PresentationCore assembly manifest has a reference to a milcore.dll, which appears to have a friend called MILRender.dll.

It appears to stand for Media Integration Layer. This term is not explicitly defined anywhere, but as far as I can tell, it seems to be the name for the new display technology in Avalon.

XAML Available After Compilation?

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:45:21 PST

A question occurred to me while looking at the way XAML-based applications are put together, and the way in which navigation between pages occurs: is the XAML stored somewhere in the compiled application, so that it's available at runtime? Superficially, it looks like it might be - you can refer to your XAML pages by name and navigate to them, for example.

However, digging around with ILDASM, it looks like XAML does not survive the compilation process. It gets converted into code that builds an object tree that reflects what was in the XAML, as this article describes. What is not immediately obvious from the article is that XAML source itself is long gone at runtime. The only reason you can navigate to a Uri that refers to the XAML file by name is that the build environment adds a special ResourceLoader class to your project and registers this with System.Resources.ResourceLoaderService. This resource 'loader' simply contains a switch statement that returns an instance of class corresponding to the XAML filename you pass in. So although your code may refer to, say, "MyPage.xaml", at runtime you only ever get an instance of the class for the page - you won't be able to get the original XAML itself.

Those who are concerned about their intellectual property being ripped off will presumably be happy about this. If the XAML were available, that would make it very easy to nab someone elses UI design, just as is often done today with HTML. Having said that, it is possible to use the XamlRootSerializer class to generate an XAML representation of the runtime logical tree. But this is not the same as the original XAML - it seems to be a lot more verbose and hard to read.

Of course it does make me wonder: can I generate XAML at runtime and display it? For example, could I get some XML from SQL Server and run it through XSLT to build a page? It looks like the classes in MSAvalon.Windows.Serialization could be used for this (Parser in particular), but I've not tried this yet.

Application vs NavigationApplication

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:45:07 PST

It would be easy to get the impression that unless you are sticking to raw procedural code, you will always want to use the NavigationApplication class rather than its base, Application. After all, this MSDN entry says that NavigationApplication "provides support for navigation".

But using NavigationApplication turns out not to be a prerequisite. You can write a custom application class that derives directly from Application, and still use XAML navigation. Your app.xaml file's main element will be Application instead of NavigationApplication, and you'll need to provide an implementation of the custom application class in a codebehind file. You lose certain features: global navigation events, the application Properties collection, and the StartupUri property. (So you'll need to override OnStartingUp and open a window in there if you want anything to appear when your program is launched.)

However, programmatic navigation carries on working, as does the HyperLink element. So apparently the NavigationApplication is not central to an application's ability to support navigation operations. It just supplies some extra functionality that you might find useful if you're using navigation in your application.

Application Properties

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:42:50 PST

As this section describes, NavigationApplication allows application-wide values to be stored in its Properties member. For some reason, this useful facility is not available on the base class, Application. This means that if you write a base application, deriving your own application class directly from Application, it won't have the Properties collection.

This is easily fixed, of course. NavigationApplication.Properties appears to be a simple Hashtable, so you can just add your own equivalent property to your custom Application-derived class. Even so, it seems like it would have been easier if the base Application supplied this - that way there would be no need to cast Application.Current simply in order access application-wide properties.

Animation Properties

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:41:48 PST

Something is unclear to me: some animatable properties have corresponding animation properties. For example, RotateTransform has an Angle property, and it also has an AngleAnimations property. Where such an animation property is present, you're supposed to use it. But not all properties have such animation counterparts. For those that don't you can often still animate the property by just setting an appropriate AnimationCollection as the value of the property.

What is the difference between these two styles? Why do some properties use one, and some the other? What would happen if I were to use the wrong one, e.g. apply an animation collection to the Angle property rather than the AngleAnimations property? Empirically, the answer appears to be: it doesn't work. But why?

The only reason the text seems to offer for this is that where animation properties are available, they are less verbose - you are allowed to omit the containing animation collection.

Rotate Anything

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:41:53 PST

My favorite thing about the TransformDecorator is that you can use it to rotate anything - it's not limited to rotating vector graphics drawn in WVG. For example, you can do this:

<TransformDecorator AffectsLayout="false">
  <TransformDecorator.Transform>
    <RotateTransform Angle="30" />
  </TransformDecorator.Transform>

  <FlowPanel>
    <SimpleText>Hello, world</SimpleText>
    <TextBox Text="Hello" Height="30"/>
    <Button>Click me!</Button>
  </FlowPanel>
</TransformDecorator>

This displays some text, a text entry field, and a button, all rotated by 30 degrees.

ImageBrush Content Mapping

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:41:31 PST

If the behavior you want from your ImageBrush is the obvious and straightforward effect that the image fills the area that the brush is being used to paint, then life is easy:

  <Rectangle RectangleWidth="200" RectangleHeight="200">
    <Rectangle.Fill>
      <ImageBrush ImageSource="Pic.bmp" TileMode="Tile"/>
    </Rectangle.Fill>
  </Rectangle>

This will cause the bitmap to fill the rectangle. But what if you want to take more control? Maybe you want to control the aspect ratio of the scaling, or perhaps you don't want to show the entire original image. Maybe you'd like to tile the image.

To do any of these things, you must be aware of five properties:

Property	Usage
ViewBox	This selects a part of the source image. This will be mapped into the ViewPort.
SizeViewBoxToContent	You must set this to false if you set ViewBox, otherwise ViewBox settings are ignored and the whole source image will be used.
ViewPort	This is the area on screen onto which the ViewBox will be mapped. (Defaults to the brush's entire bounding rectangle.)
ViewPortUnits	Determines the units used for the ViewPort. By default, these range from 0 to 1 across the bounding rectangle of the brush, but you can specify Absolute here to indicate that the ViewPort is specified in absolute units.
Tile	Allows tiling to be used. (This only makes any sense if your ViewPort does not completely enclose the brush bounding rectangle.) Note that if you enable tiling, the repetitions occur across the whole source image, rather than the portion of the source image selected by the ViewBox - when tiling is enabled, the ViewBox and ViewPort are simply used to work out the transformation that will be applied to the source image.

Relative Widths

Ian Griffiths, O'Reilly & Associates, Inc. — Thu, 23 Oct 2003 05:46:53 PST

Certain layout styles require a lot of developer effort on Windows Forms, or older technologies like VB6 and MFC. Although Windows Forms offers more support here than its predecessors, it cannot automatically resize elements in proportion to the size of their container. (The classic example is a table - if you wish to have a table which fills the available width, but which preserves the relative widths of each column, you have to write your own layout code in Windows Forms.)

In Longhorn, it's much easier. A FrameworkElement's Width property is of type Length. As well as supporting absolute widths, you can specify the width as a percentage of the containing element's width, e.g.:

<Text Width="20%">Hello, world.  This is a text element</Text>

This will ensure that this text element is 20% of the width of its container. The same technique may be used on the Height property. (You can also combine the techniques, e.g. an element may have a relative Width and an absolute Height.)