mcs/tools/xamlc/README

   1 This is my xaml compiler, being written as part of Google's summer of code
   2 program.
   3
   4 Xaml is a language for concisely describing how to connect up a bunch of
   5 objects. As an example, in the avalon world:
   6 <Window Title="Hi!">
   7   <Button>Click</Button>
   8 </Window>
   9
  10 Would produce a child of Window where the constructor does this:
  11 this.Title = "Hi!";
  12 Button button = new Button();
  13 window.AddChild(button);
  14 button.AddText("Click");
  15
  16 Except of course it can handle trees of arbitrary depth, so descriptions of
  17 complicated GUIs are not a problem and potentially much more readable than
  18 the code version.
  19
  20 To use this thing:
  21 cd ../../class/WindowsBase
  22 make install
  23 cd ../PresentationFramework
  24 make install
  25 cd ../../tools/xamlc
  26 make install
  27
  28 That will get everything compiled. There's a demo in the mcs/tools/xamlc/demo
  29 directory; to run it, cd into that directory and do "make run". Stuff should
  30 happen, along the lines of a program test.exe being generated and run to
  31 produce this output:
  32
  33 Hello World
  34 IT BEGINS!
  35 Hello World
  36 YYYI'm surrounded!ZZZ
  37 What should I say?
  38
  39 I say I say: INPUTINPUT
  40 I say.
  41
  42
  43 Goodbye.
  44 Goodbye.
  45 Goodbye.
  46 Bye
  47 Bye
  48
  49 In the same directory, "make run2" should demonstrate the runtime creation of
  50 objects from xaml files.
  51
  52 How it works
  53 ============
  54 The compiler's main job is to identify the types to which your xaml file refers
  55 and use that to ensure that correct types appear in the output xaml file. This
  56 is also an issue when performing creation of objects from the xaml file at
  57 runtime because of the need to perform conversions between types.
  58
  59 The following examples are given in terms of objects being instantiated directly
  60 by the parser at runtime; if this is not your chosen approach, then things work
  61 somewhat differently. The former approach, of calling Parser.LoadXml(), will
  62 create the object at runtime, while the latter approach of invoking xamlc will
  63 create a source code file representing the object that would otherwise have
  64 been created at runtime. The process by which this functions is that the class
  65 is defined as inheriting the class being represented by the top-level element of
  66 the xml tree, and every other object mentioned is either a variable local to the
  67 function or a field of the class.
  68
  69 A xaml file is an Xml file where meaning is derived from processing
  70 instructions, text, elements, and attributes. Elements typically indicate class
  71 instances or properties, attributes refer mainly to properties, and processing
  72 instructions are used to allow types to be resolved correctly.
  73
  74 In order to facilitate the correct resolution of types, every element must have
  75 a specified XML namespace. The XML namespace is an arbitrary string that has
  76 been defined as the identifier for an Assembly-ClrNamespace pair. The
  77 definition of these pairs is achieved with processing instructions (PIs). A line
  78 <?Mapping ClrNamespace="Org.Project" Assembly="myassembly.dll" XmlNamespace="cc" ?>
  79
  80 indicates that every element in the cc namespace corresponds to a type defined
  81 in myassembly.dll in the Org.Project namespace. There is substantial similarity
  82 of purpose between the Mapping PI and C#'s using statement, but the Mapping PI
  83 is substantially more precise.
  84
  85 Elements representing class instances in XAML files are required to have the
  86 name of the class to be instantiated as the element name. The top-level element
  87 must therefore be named according to what kind of object you wish to be produced
  88 by the compilation process. For example, if "XX" is defined (in the manner
  89 described above) as corresponding to an assembly where the relevant namespace
  90 defines a Window class, the xaml document <x:Window xmlns:x="XX" /> will have a
  91 similar effect to the C# code "new Window()".
  92
  93 If Xaml is to succeed in its goal of simplifying code in the style of that which
  94 is commonly used to initialize GUIs, it must have a way of adding objects as
  95 children to other objects. This maps to child elements in Xml - the standard
  96 case is for a child element of an object element to represent an object which
  97 is a child of the aforementioned object. The notion of a child object is defined
  98 by the System.Windows.Serialization.IAddChild interface, which provides an
  99 AddChild method for making objects children of the implementor of the interface.
 100
 101 We can therefore see that given a namespace defined similarly to that in the
 102 previous example containing Window and Button objects that the following
 103 document:
 104
 105 <x:Window xmlns:x="XX">
 106         <Button />
 107         <Button />
 108 </x:Window>
 109
 110 Is equivalent to the following C# code:
 111 Window w = new Window();
 112 ((System.Windows.IAddChild)w).AddChild(new Button());
 113 ((System.Windows.IAddChild)w).AddChild(new Button());
 114
 115 The same mechanism also allows for the addition of text. The document:
 116 <x:Button xmlns:x="XX">I Am Button.</x:Button>
 117
 118 Is equivalent to:
 119 Button b = new Button();
 120 ((System.Windows.IAddChild)b).AddText("I Am Button.");
 121
 122
 123 So far, we've seen mechanisms for type resolution, making an element a child of
 124 another one, and adding text for an element. We still need mechanisms for
 125 setting properties and event handlers.
 126
 127 The basic mechanism by which properties can be set is the xml attribute. The
 128 name of the attribute corresponds to the name of the property, and the value is
 129 converted from a string with .net's standard TypeConverter framework and
 130 assigned to the property. If our hypothetical Window class has a property
 131 Title of type String, we could do something like the following:
 132 <x:Window Title="The title of a window" xmlns:x="XX" />
 133
 134 To produce code equivalent to
 135 Window w = new Window();
 136 w.Title = "The title of a window";
 137
 138 While if Window defined a SecondsToDestruction property of type Int32, code like
 139 <x:Window SecondsToDestruction="5" xmlns:x="XX" />
 140
 141 To produce code equivalent to:
 142 Window w = new Window();
 143 w.SecondsToDestruction = (new Int32Converter()).ConvertFromString("5");
 144
 145 This system means that any property, the type of which has a converter allowing
 146 instances to be created from strings, can be assigned to in your Xaml code.
 147
 148 While this is sufficiently general for many cases, it is impractical for cases
 149 where you are unable for whatever reason to express the property value as a
 150 string. For cases like these the complex property syntax is provided. In order
 151 to use this syntax, you define an element as a child of the element representing
 152 the object the property of which you want to set. The elements name should be
 153 the name of the class with the property as member, followed by a ., followed by
 154 the name of the property. Continuing on with our Window example, if the Window
 155 had a Thumbnail property we might do something like this:
 156 <x:Window xmlns:x="XX">
 157         <Window.Thumbnail>
 158                 <Button />
 159         </Window.Thumbnail>
 160 </x:Window>
 161
 162 In order to produce code equivalent to:
 163 Window w = new Window();
 164 w.Thumbnail = new Button();
 165
 166 This syntax allows arbitrarily complex objects to be used as property values.
 167
 168 The syntax for events follows the syntax for properties. In order to add an
 169 event handler, all that is neccesary is to add an attribute to the object's
 170 element with the name of the event as its name and the name of the event handler
 171 as its value. For example, if the Window has an OnClose event:
 172 <x:Window OnClose="close_handler" xmlns:x="XX" />
 173
 174 Would correspond to code like:
 175 Window w = new Window();
 176 w.OnClose += close_handler;