Panel elements handle page layout and act as containers for elements, such as controls or other panels. Some panel-derived elements are used as root elements, but the primary purpose of the panel is to provide support for layout and placement of elements on the page. Some panel classes are intended for designing the user interface, while others are special panels designed specifically for special layout scenarios. An example is the bullet panel, which is used specifically to display only two child elements (usually a text element and a glyph representing a checkbox or a radio button), and is used as a component of other elements such as RadioButton and CheckBox . When you declare a RadioButton , a BulletPanel is one of the underlying components that is rendered on the screen.
The panel elements designed for user-interface design are DockPanel , StackPanel , Canvas , WrapPanel , and Grid .
Shape and Geometric Elements
Shape and geometric elements represent 2-D vector graphics. Shapes derive from the Shape class and represent predefined geometric shapes. WPF shapes available for use with XAML are Ellipse , Line , Path , Polygon , Polyline , and Rectangle . Shapes are a type of UIElement , which means they can be used inside panels and most other controls.
Geometric elements, while also representing 2-D vector graphics, are more flexible than shape elements and can also be used for hit-testing and clipping purposes. Geometry elements can be simple vector graphics such as circles or polygons, or more complex elements comprised of Bezier lines and arcs. Geometries cannot render themselves. They must be drawn by another element, such as Drawing or Path . The attributes common to shape— Fill , Stroke , and StrokeThickness —are attached to the element that draws the geometries rather than the geometry element itself. Geometry elements are CombinedGeometry , LineGeometry , EllipseGeometry , GeometryGroup , PathGeometry , RectangleGeometry , PathSegment , ArcSegment , LineSegment , BezierSegment , QuadraticBezierSegment , PolyQuadraticBezierSegment , PolyLineSegment , PolyBezierSegment , StartSegment , and CloseSegment .
There are some similarities between respective shape and geometric entities. For example, Ellipse and EllipseGeometry provide the same basic functionality, i.e., both declare an ellipse. However, the way in which these elements are interpreted differs. An Ellipse is a standalone element. Its attributes provide all the information necessary to render a complete ellipse. EllipseGeometry , however, does not. Because it is designed to be a part of an ordered collection of geometric types, EllipseGeometry relies on attributes defined on the element appearing before it in the collection. Similarly, attributes assigned to EllipseGeometry will be used to render the next geometry instance in the collection. This trait is shared by all the geometry objects and differentiates them from their Shape -based counterparts.
Document elements handle document presentation. Documents are categorized as either flow or fixed. The FixedDocument element is designed to be What You See Is What You Get (WYSIWYG) and is intended to appear in all formats (print, browser, application) with exactly the same layout.
A FlowDocument element provides more flexibility in appearance to enhance readability. Flow documents dynamically reformat content based on a variety of factors, including screen and page size, font size, and optional user preferences. Flow documents are comprised of one or more elements derived from Block or Inline . Block elements such as Block , Figure , Floater , List , ListItem , Paragraph , Section , Table , and TableCell are used to organize and format blocks of text. Inline elements are used to format text within a block. Inline elements are Bold , AccessKey , LineBreak , Hyperlink , Italic , Subscript , Superscript , and Underline .
Some of these elements might look familiar, such as Paragraph , Table , and Italic . Similar formatting elements exist in other user-interface markup languages, such as <p> , <table> , and <i> , respectively, in HTML. These elements are virtually identical in execution but have structural differences as well as an abundance of attributes in XAML that do not exist in their HTML counterparts.
While the core syntax of XAML is very similar to markup languages such as HTML, XAML user-interface elements are not restricted to containing traditional content. For example, a Button is not required, nor restricted, to present text-based content as a prompt. The flexibility of XAML and its object-oriented nature offer unlimited possibilities. You can just as easily decorate the face of a Button with any UIElement -derived element. Example 3-6 declares three circles—defined by an Ellipse element with equivalent x- and y-axis radii—as the content element of a Button . While content control-derived classes may only have one child element, that child element may contain additional elements, such as the DockPanel or StackPanel .
Example 3-6. Using alternate elements as the content of a Button
Attributes are the XML representation of the properties of an element’s corresponding CLR class. The Width attribute of the XAML Button element corresponds directly to the Width property of the System.Windows.Button class. To show the correlation between XAML and CLR classes, Examples 3-7 and 3-8 declare a Button instance and its attributes in both XAML and C#.
Example 3-7. Button declared in XAML
<Button Width="100" Name="myButton" Height="20" Content="This is my button" />
Example 3-8. Button declared in C#
Button myButton ; myButton.Width=100; myButton.Height=20; myButton.Content = "This is my button";
As with the XAML tags for elements, attributes are spelled exactly the same as their corresponding CLR class properties. ( Width = Width , Content = Content ... You get the picture.)
There are two types of XAML attributes. The first, dependency properties, are public static read-only fields on CLR classes that are derived from DependencyProperty and have declared CLR accessor methods. In other words, the value of dependency properties can be dependent on (hence the name) other variables in CLR classes and, therefore, can only be accessed with a public get or set accessor method to be evaluated properly.
Dependency properties are like stock certificates. The stock certificate represents a value (money), but the actual amount of money it is worth (its value) is deter mined by external calculations and can change at nearly any time. To determine the value of your stock certificate, you must consult the stock exchange and do some multiplication. Dependency properties can also be based on external resources and often rely on calculations to determine their value.
Dependency property values are determined from a number of different places. The WPF property system searches for the value from the following places in this order:
Storyboards or event triggers that start an animation; property values set by an animation override even local values
Local value (i.e., <Object Property="value"> )
Property triggers
TemplatedParent ’s template (i.e., that template includes <Setter> )
Style property
ThemeStyle
Inheritance (from your parent element, not your superclass)
DefaultValue specified when you registered the property (or override metadata)
These attributes provide support for value expressions, property invalidation, default values, inheritance, data binding, animation, and styling. The property system is complex, so WPF provides simple get and set accessor methods to manipulate these attributes.
The second type of attribute supported in XAML is the common language runtime property. Common language runtime properties are standard read/write CLR class properties that can be accessed directly and do not require get or set accessor methods, although they generally have them.
Both dependency properties and common runtime properties are accessed in XAML using the same techniques. The difference between them is important only when you are using more advanced techniques, such as defining styles or triggers that act upon a specific attribute. Some attributes of elements must reference a dependency property, so you need to know which attributes are dependency properties and which are not.
Regardless of their underlying types, all XAML attributes can be assigned in one of two ways. They can be assigned inline, as part of the element declaration, or they can be explicitly declared as nested elements within the element being described. As a general rule, complex attributes must be declared explicitly, while simple attributes can be defined inline, as shown in Example 3-9. Simple attributes are those whose data types are primitives, such as String , Integer , and Double . Enumerations are also declared inline, using a String representation of the name of the enumerated value. All inline attribute declarations must be enclosed in double quotes, regardless of the underlying data type of the property being described. You don’t have to enclose attributes of type String in two sets of quotes. String is sort of the exception to the rule, because it is, after all, already a String .
Example 3-9. Inline declaration of a simple attribute
<Button Content="Click Me" />
Complex attributes are defined as a CLR class or are of type struct . They are declared explicitly, as shown in Example 3-10. In this example, GeometryDrawing has two complex attributes: Pen and Geometry . Neither attribute can be specified using abbreviated syntax, so it is necessary to explicitly declare them. The exception to this rule is the specification of child elements, which are declared by using standard XML mechanisms without the name of the attribute. This is illustrated in Example 3-10, in which two instances of EllipseGeometry are implicitly declared as children of GeometryGroup . It is not necessary to specify child elements as a complex attribute by name. Elements nested between the opening and closing tags of an element are assumed to be the children of that element and are automatically added to the appropriate container property according to the CLR class, usually the Children or InternalChildren property of the parent element.
Example 3-10. Explicit declaration of a complex attribute
Properties and More in XAML
