WPF Controls - A Visual Quick Start

Introduction

Understanding the default controls available in .NET/WPF can save you a lot of time. In fact, having a strong understanding of the basics is virtually required since most WPF controls were designed to be extended. The examples are written in XAML, as they can be easily copied and pasted into the Visual Studio 2008 (or any other) designer. My goal is to show how the controls work with screenshots and XAML, instead of using text descriptions.

WPF Visual Quick Start Articles by Josh Fischer

Layouts
Controls (this article)
Lists/Views

Background

Controls are the basis for virtually any 2D WPF application. They range from the basic label and button, to complex tree views and grids. If you have used any version of Access, VB, or Visual Studio, then you are familiar with the concept. WPF takes the model one step further, however, and allows nearly endless customization and nesting of controls.

Conventions

I chose to use a Canvas for all the examples as it allows for exact placement of controls and does not stretch the controls to fit in a certain region. This means you can effectively ignore statements such as Canvas.Top="50" since this is merely telling WPF where to put the control on the screen. One thing you will quickly discover is that certain properties such as background color, font, etc., can be changed for virtually every control. Rather than show a screenshot for every possible customization, I attempted to show what features are most important for the given control. Please remember this article is for beginners, and is not intended as a reference (that is what MSDN is for).

The Controls

Buttons	Text	Shapes
Containers	Media	Toolbars
Scrolls	Panels & Lists	Miscellaneous

Buttons

Button - The defacto standard; indicates an area can be clicked
ToggleButton - Like a Button, but remains pressed down after it is clicked
CheckBox - Indicates a positive, negative, or indeterminate state
RadioButton - Allows exclusive selection among options


Example 1	Example 2	Example 3

Example 1

<Canvas>
  <Button Canvas.Top="0" Canvas.Left="0">Click Me</Button>
  <ToggleButton Canvas.Top="40" Canvas.Left="0">Toggle Me</ToggleButton>
  <CheckBox Canvas.Top="80" Canvas.Left="0">Check Me</CheckBox>
  <RadioButton Canvas.Top="0" Canvas.Left="80">Yes</RadioButton>
  <RadioButton Canvas.Top="50" Canvas.Left="80">No</RadioButton>
</Canvas>

Example 2

<Canvas>
<Button Width="75" Height="40"
    Canvas.Top="0" Canvas.Left="0">Click Me</Button>

<ToggleButton Foreground="White" Background="Red"
    Canvas.Top="40" Canvas.Left="0">Toggle Me</ToggleButton>

<CheckBox BorderBrush="Green" BorderThickness="10"
    Canvas.Top="80" Canvas.Left="0">Check Me</CheckBox>

<RadioButton FontFamily="Algerian" FontSize="24"
    Canvas.Top="0" Canvas.Left="80">Yes</RadioButton>

<RadioButton FontStyle="Italic" FontWeight="Bold"
    Canvas.Top="50" Canvas.Left="80">No</RadioButton>
</Canvas>

Example 3

<Canvas>
<!-- Clicking MyButton will call the "MyButton_Click_1" method in your code -->
<Button Name="MyButton" Click="MyButton_Click_1"
    Canvas.Top="0" Canvas.Left="0">Click Me</Button>

<!-- The button will intially be toggled or "pressed down" -->
<ToggleButton IsChecked="True"
    Canvas.Top="40" Canvas.Left="0">Toggle Me</ToggleButton>

<CheckBox IsChecked="True"
    Canvas.Top="80" Canvas.Left="0">Check Me 1</CheckBox>

<!-- Shows the indeterminate state; a grey check -->
<CheckBox IsChecked="{x:Null}"
    Canvas.Top="80" Canvas.Left="80">Check Me 2</CheckBox>

<RadioButton IsChecked="False"
    Canvas.Top="0" Canvas.Left="80">Yes</RadioButton>

<RadioButton IsChecked="True"
    Canvas.Top="40" Canvas.Left="80">No</RadioButton>
</Canvas>

Note:

The "Yes" and "No" buttons can not both be checked at the same time

Text

TextBox - Contains unformatted, editable text
PasswordBox - Like a TextBox, but masks the characters
Label - Contains read-only text
TextBlock - Like a Label, but allows for greater display customization
RichTextBox - An editable version of a TextBlock


Example 1	Example 2	Example 3

Example 1

<Canvas>
 <TextBox Canvas.Top="0">standard text input</TextBox>
 <PasswordBox Canvas.Top="40" Password="secret" />
 <Label Canvas.Top="80">basic read-only text</Label>
 <TextBlock Canvas.Top="120">advanced read-only text</TextBlock>
</Canvas>

Example 2

<Canvas>
<TextBox Name="MyTextBox" MaxWidth="150" TextWrapping="Wrap"
    HorizontalContentAlignment="Right" SpellCheck.IsEnabled="True"
    Canvas.Top="0">standard text input + more text</TextBox>

<PasswordBox Width="150" PasswordChar="-"
    HorizontalContentAlignment="Right"
    Canvas.Top="40" Password="secretquot; />

<!-- Hitting alt+ b will move the cursor to the text box -->
<Label Target="{Binding ElementName=MyTextBox}"
    Canvas.Top="80">_basic read-only text</Label>

<TextBlock Width="150" Height="50" 
         TextAlignment="Center" Canvas.Top="120">
    <Bold>advanced</Bold> <Italic>read-only</Italic>
    <LineBreak />
    <Hyperlink>text</Hyperlink> 
</TextBlock>
</Canvas>

Example 3

<Canvas>
<TextBlock Width="180" TextWrapping="Wrap" Canvas.Top="0">
    The <Run FontSize="14" Background="Yellow">TextBlock</Run> class 
    supports a subset of the features provided by the WPF 
    <Bold><Italic>"document"</Italic></Bold> components.
    <LineBreak />
    These components allow you to use <Run FontSize="14" Foreground="Red" 
    FontFamily="Algerian">XAML</Run> markup 
    or code to construct a <Underline>visually enhanced document</Underline>.
</TextBlock>

<RichTextBox Width="180" Height="80" 
            SpellCheck.IsEnabled="True" Canvas.Top="90" >
    <FlowDocument>
    <Paragraph>
    The RichTextBox class is <Bold>very</Bold> similar to the TextBlock class 
    <Underline>except</Underline> the contents are
    <Run FontSize="12" Background="Red" Foreground="White">editable</Run>.
    <LineBreak /><LineBreak />
    <Run FontFamily="Arial Narrow" FontSize="12">Built in spell-checking is nice!</Run>
    </Paragraph>
    </FlowDocument>
</RichTextBox>
</Canvas>

Note:

Using an underscore ("_") in a Label's text indicates a keyboard shortcut can be used (like Alt+F for the File menu)
TextBox and RichTextBox have built-in spell checking

Shapes

Rectangle - Defined by a starting point (upper left corner), a width, and a height
Ellipse - Allows you to draw circles and ellipses
Line - A straight line defined by two points
Polyline - A series of connected straight lines defined by a set of points
Polygon - Allows you to draw virtually any shape as defined by a set of points

Example 1

<Canvas>
<Rectangle Stroke="Black" StrokeThickness="2" Fill="Yellow"
    Width="50" Height="20"
    Canvas.Left="0" Canvas.Top="0" />

<Ellipse Stroke="Green" StrokeThickness="4" Fill="Yellow"
    Width="100" Height="50"
    Canvas.Left="50" Canvas.Top="50" />

<Line Stroke="Red" StrokeThickness="2"
    X1="100" Y1="30" X2="150" Y2="10" />

<Polyline Stroke="Blue" StrokeThickness="2"
    Points="25,50 25,155 100,125 110,110" />

<Polygon Stroke="Black" StrokeThickness="4" Fill="Yellow"
    Points="150,100 155,150 170,90" />
</Canvas>

Containers

GroupBox - Draws a header and rectangle around a group of controls
Expander - Basically, a collapsible version of the GroupBox
TabControl - Divides controls onto different pages and only displays one tab page at a time


Example 1	Example 2	Example 3

Example 1

<Canvas>
<GroupBox Header="Group 1" Canvas.Left="0" Canvas.Top="0">
    <StackPanel>
    <Button>1</Button><Button>2</Button><Button>3</Button>
    </StackPanel>
</GroupBox>

<Expander Header="Group 2" Canvas.Left="100" Canvas.Top="0">
    <StackPanel>
    <Button>4</Button><Button>5</Button><Button>6</Button>
    </StackPanel>
</Expander>

<TabControl Canvas.Left="0" Canvas.Top="100">
    <TabItem Header="Group 3">
<StackPanel>
    <Button>7</Button><Button>8</Button><Button>9</Button>
</StackPanel>
    </TabItem>
    <TabItem Header="Group 4">
    <StackPanel>
        <Button>10</Button><Button>11</Button><Button>12</Button>
    </StackPanel>
    </TabItem>
</TabControl>
</Canvas>

Examples 2 & 3

<Canvas>
<GroupBox Header="Group 1" Width="90" 
  FontWeight="Bold" Foreground="Blue"
  BorderBrush="Red" BorderThickness="4"
  Canvas.Left="0" Canvas.Top="0">
    <StackPanel>
    <Button>1</Button><Button>2</Button><Button>3</Button>
    </StackPanel>
</GroupBox>

<Expander Header="Group 2" IsExpanded="True" ExpandDirection="Up"
  FontFamily="Algerian" FontSize="12" Background="LightBlue"
  Canvas.Left="100" Canvas.Top="0">
    <StackPanel>
    <Button>4</Button><Button>5</Button><Button>6</Button>
    </StackPanel>
</Expander>

<TabControl Canvas.Left="0" Canvas.Top="100" 
           BorderThickness="10" TabStripPlacement="Right">
    <TabItem Header="Group 3" Background="Blue" Foreground="White">
    <StackPanel>
    <Button>7</Button><Button>8</Button><Button>9</Button>
    </StackPanel>
    </TabItem>
    <TabItem Header="Group 4" Background="Black" Foreground="White">
    <StackPanel>
    <Button>10</Button><Button>11</Button><Button>12</Button>
    </StackPanel>
    </TabItem>
</TabControl>
</Canvas>

Media

Image - Displays a picture in a rectangular region
InkCanvas - Allows you to draw free hand using the mouse
MediaElement - Embeds sound or displays video
ViewBox - Allows you to stretch the contents, often an Image
WebBrowser - Runs an instance of Internet Explorer inside your application

Example 1

<Canvas>
<Image Source="C:\Temp\playultimate.png" Width="100"
    Canvas.Left="0" Canvas.Top="0" />

<InkCanvas Width="100" Height="100" Background="ightBlue"
    Canvas.Left="150" Canvas.Top="0" />

<MediaElement Name="MySound" Source="C:\Temp\asound.wav" Volume="1"
    LoadedBehavior="Manual" UnloadedBehavior="Stop" />
<Button Click="Button_Click"
    Canvas.Left="300">Play Sound</Button>

<Viewbox Width="350" Height="100"
    Canvas.Left="0" Canvas.Top="120" Stretch="Fill">
    <Image Source="C:\Temp\playultimate.png" />
</Viewbox>

<WebBrowser Width="380" Height="130" Source="http://www.codeproject.com"
    Canvas.Left="0" Canvas.Top="230" />
</Canvas>

Toolbars

ToolBarTray - A container for ToolBars; allows ToolBars to be moved around in its defined area
ToolBar - Contains text or image elements that represent commands or actions that can be clicked


Example 1	Example 2

Example 3	Example 4

Example 1

<Canvas>
<ToolBarTray Orientation="Horizontal"
    Canvas.Left="0" Canvas.Top="0">
    <ToolBar Header="Alpha">
        <Button>1</Button>
    </ToolBar>
    <ToolBar Header="Bravo">
        <Button>2</Button>
    </ToolBar>
</ToolBarTray>

<ToolBarTray Orientation="Vertical"
    Canvas.Left="0" Canvas.Top="50">
    <ToolBar Header="Charlie">
        <Button>3</Button>
    </ToolBar>
    <ToolBar Header="Delta">
        <Button>4</Button>
    </ToolBar>
</ToolBarTray>
</Canvas>

Example 2

<Canvas>
<ToolBarTray Orientation="Horizontal" Width="150"
    Canvas.Left="0" Canvas.Top="0">
    <ToolBar Header="Alpha" Band="1">
        <Button>button 1</Button>
        <Button>button 2</Button>
    </ToolBar>
    <ToolBar Header="Bravo" Band="0">
        <Button>button 3</Button>
        <Button>button 4</Button>
    </ToolBar>
</ToolBarTray>
<ToolBarTray Orientation="Vertical"
    Canvas.Left="0" Canvas.Top="50">
    <ToolBar Header="Charlie" Band="0">
        <Button>5</Button>
        <Button>6</Button>
    </ToolBar>
    <ToolBar Header="Delta" Band="1">
        <Button>7</Button>
        <Button>8</Button>
        <Button ToolBar.OverflowMode="Always">button 9</Button>
    </ToolBar>
</ToolBarTray>
</Canvas>

Examples 3 & 4

<Canvas>
<ToolBarTray Width="150">
    <ToolBar Header="Alpha" Band="0" BandIndex="1">
        <Button>1</Button>
        <Button>2</Button>
    </ToolBar>
    <ToolBar Header="Bravo" Band="1" BandIndex="1">
        <Button>3</Button>
        <Button>4</Button>
    </ToolBar>
    <ToolBar Header="Charliequot; Band="0" BandIndex="0">
        <Button>5</Button>
        <Button>6</Button>
    </ToolBar>
    <ToolBar Header="Delta" Band="1" BandIndex="0">
        <Button>7</Button>
        <Button>8</Button>
    </ToolBar>
</ToolBarTray>
</Canvas>

Note:

A Band is nothing more then a row; the BandIndex is the ToolBar's position inside the row/band
Examples 3 and 4 use the same code, but I manually rearranged the ToolBars with the mouse at runtime
When there is not enough room to display all the tools, they are placed into the overflow region which can be accessed by clicking the ToolBars arrow

Scrolls

ProgressBar - Visual representation of a numeric value; often displays a ratio or percentage
Slider - Allows the user to visually input a numeric value by moving the bar back and forth
ScrollBar - Like a Slider, but often used on the left and bottom of other controls to mimic the Windows standard
ScrollViewer - Automatically adds scrolling capability and scrollbars to its contents


Example 1	Example 2

Example 1

<Canvas>
<ProgressBar Width="170" Height="20" 
    Value="70" Maximum="100"
    Canvas.Left="0" Canvas.Top="0" />

<Slider Width="170" Value="70" Maximum="100"
    Canvas.Left="0" Canvas.Top="30" />

<ScrollBar Width="170" Value="70" Maximum="100"
    Orientation="Horizontal"
    Canvas.Left="0" Canvas.Top="70" />

<ScrollViewer Width="170" Height="70"
    Canvas.Left="0" Canvas.Top="100">
    <TextBlock>
    While all these controls look<LineBreak />
    similar, they are used for very<LineBreak />
    different purposes. I hope this<LineBreak />
    visual guide serves as a  good starting<LineBreak />
    point for you in your WPF learning!
    </TextBlock>
</ScrollViewer>
</Canvas>

Example 2

<Canvas>
<ProgressBar Background="Red" Foreground="White"
    Width="170" Height="20" Value="70" Maximum="100"
    Canvas.Left="0" Canvas.Top="0" />

<Slider TickPlacement="BottomRight" TickFrequency="10"
    Width="170" Value="70" Maximum="100"
    Canvas.Left="0" Canvas.Top="30" />

<ScrollBar Width="1.5in" Scroll="ScrollBar_Scroll"
    Value="70" Maximum="100" Orientation="Horizontal"
    Canvas.Left="0" Canvas.Top="70" />

<ScrollViewer HorizontalScrollBarVisibility="Visible"
    Background="Red" Foreground="White"
    Width="170" Height="70" 
    Canvas.Left="0" Canvas.Top="100">
    <TextBlock>
    While all these controls look<LineBreak />
    similar, they are used for very<LineBreak />
    different purposes. I hope this<LineBreak />
    visual guide serves as a  good starting<LineBreak />
    point for you in your WPF learning!
    </TextBlock>
</ScrollViewer>
</Canvas>

Note:

In Example 1, the contents of the ScrollViewer are cut off because full scrolling is not enabled

Miscellaneous

Border - Allows you to put a border around virtually any control including the outermost panel
ContextMenu - A menu that is displayed when a user right clicks on a control; can be applied to almost any control
ToolTip - Displays a message when a user hovers over a control; can be applied to almost any control
Menu & MenuItem - Allows you to build "file" menus that are standard to most Windows applications


Example 1	Example 2	Example 3

Example 1

<Border BorderThickness="5" BorderBrush="Green" Background="Yellow">
    <Canvas>
        <Border BorderThickness="5" BorderBrush="Red"
            Canvas.Left="10" Canvas.Top="22" >
            <Image Width="150" Source="C:\temp\playultimate.png" />
        </Border>
    </Canvas>
</Border>

Example 2

<Canvas>
<Button Canvas.Left="10" Canvas.Top="10">
    Right Click Me
    <Button.ContextMenu>
        <ContextMenu>
        <MenuItem Header="Option 1" />
            <Button>Button 1</Button>
            <Slider/>
        </ContextMenu>
    </Button.ContextMenu>
</Button>

<TextBox Canvas.Left="10" Canvas.Top="80">
    Some Text
    <TextBox.ToolTip>
    <ToolTip Width="175" Height="75" Background="LightBlue">
    <StackPanel>
       <Button>test</Button>
       <TextBlock TextWrapping="Wrap">
        <Run Foreground="Green" FontWeight="Bold">WPF</Run> tooltips can contain 
        <Run Foreground="Red" FontSize="14">more</Run> 
        than just <Italic>plain text</Italic>!
       </TextBlock>
    </StackPanel>
    </ToolTip>
    </TextBox.ToolTip>
</TextBox>
</Canvas>

Example 3

<Canvas>
<ToolBar>
    <Menu>
    <MenuItem Header="_File">
        <MenuItem Header="_Open" />
            <MenuItem Header="_Close" >
            <MenuItem Header="_Now"/>
            <MenuItem Header="_Later"/>
        </MenuItem>
    </MenuItem>
    <MenuItem Header="_Edit">
        <MenuItem Command="ApplicationCommands.Copy" />
        <MenuItem Command="ApplicationCommands.Paste" />
    </MenuItem>
    </Menu>
</ToolBar>

<Button HorizontalContentAlignment="Right" Width="120"
    Canvas.Left="0" Canvas.Top="100">
    <StackPanel Orientation="Horizontal">
        <Label>Button Text</Label>
        <Menu>
        <MenuItem Header="Options" Background="Red">
            <MenuItem Header="One"/>
            <MenuItem Header="Two"/>
        </MenuItem>
        </Menu>
    </StackPanel>
</Button>
</Canvas>

Note:

The Border tag is defined outside of the Canvas tag
ContextMenus and ToolTips can now contain more than just plain text

Panels & Lists

Please refer to my Layouts and Lists/Views articles.

History

11/21/2008: Initial version.
3/3/2009: Added related article index.

You must Sign In to use this message board.


Per page

nice article...
pratikmehta

19:49 22 Nov '09

great effort.. thanks josh
Sign In·View Thread·PermaLink

Fantastic article for beginners!
rawwool

2:21 27 May '09

Great effort mate! Keep up the good work! My 5 for you.
Sign In·View Thread·PermaLink

A bug fix and a question!
sameh_serag

7:49 21 Jan '09

* A working version of Example 3 in Misc section:
------------------------------------------------------------
<Canvas>
            <ToolBar>
                  <Menu>
                        <MenuItem Header="_File">
                              <MenuItem Header="_Open" />
                              <MenuItem Header="_Close" >
                                    <MenuItem Header="_Now"/>
                                    <MenuItem Header="_Later"/>
                              </MenuItem>
                        </MenuItem>
                        <MenuItem Header="_Edit">
                              <MenuItem Command="ApplicationCommands.Copy" />
                              <MenuItem Command="ApplicationCommands.Paste" />
                        </MenuItem>
                  </Menu>
            </ToolBar>

            <Button HorizontalContentAlignment="Right" Width="120"
      Canvas.Left="0" Canvas.Top="100">
                  <StackPanel Orientation="Horizontal">
                        <Label>Button Text</Label>
                        <Menu>
                              <MenuItem Header="Options" Background="Red">
                                    <MenuItem Header="One"/>
                                    <MenuItem Header="Two"/>
                              </MenuItem>
                        </Menu>
                  </StackPanel>
            </Button>
      </Canvas>
------------------------------------------------------------
I just added an '</MenuItem> ' to close the File menu item!
------------------------------------------------------------

* A simple question:
The 'WebBrowser' control didn't work with me, am I missing something?
Thanks in advance.

Re: A bug fix and a question!
Josh Fischer

10:29 21 Jan '09

Thanks for finding that bug, it must have been a copy and paste error. As for the WebBrowser control, did you include a "Source" (see example). If you don't specify a Source, you will see nothing. Also, there will be no "Back", "Refresh", etc buttons visible. The control does not run the IE shell; just the rendering and networking code under the hood. I hope that helps. Josh Fischer
Sign In·View Thread·PermaLink

Just the thing I needed
trulsuh

21:13 29 Dec '08

A quick look through 'C# in a nutshell' and this article and I have finished my first .NET WFP application. Very nice article. The code example were exactly what I was looking for. You have a really nice balance between text and code, so I hope you will write more articles on this subject and on .NET in general. T.
Sign In·View Thread·PermaLink

Thank You...Very helpful
Rajiv Gowda

7:04 11 Dec '08

Thank you very much...Your article helped me to jumpstart my adventure in WPF...Keep posting
Sign In·View Thread·PermaLink

My vote of 1
Shakeel Hussain

1:31 27 Nov '08

Poor article
Sign In·View Thread·PermaLink	1.00/5

Re: My vote of 1
Josh Fischer

16:48 27 Nov '08

I respect your right to your own opinion, but please remember that this article is intended as a -visual- quickstart for beginners and is marked as so. I feel that someone who has never seen WPF or done much coding would benefit from this article as well as my introduction to WPF layouts. Others have commented that they like this format so I respectfully ask you to reconsider your vote.
thanks

Josh Fischer

Re: My vote of 1
David Roh

5:18 19 Dec '08

I think Josh has written a nice quick and brief intro to WPF basic controls - he gets my five. David Roh
Sign In·View Thread·PermaLink

Re: My vote of 1
trulsuh

21:16 29 Dec '08

The least you owe the author is to justify your low rating beyond "poor article". It takes a lot of time to write something like this, and if you don't think it is any good then let the author know how to improve it. Was the code examples bad? Was the writing bad? Was there something missing? Come on man. Poor post. T.
Sign In·View Thread·PermaLink	5.00/5

poor message!
sth_Weird

23:49 12 May '09

You think it's a poor article? The popularity on top of this article proves otherwise. Maybe you're not the target audience for this article. Maybe you've mastered wpf, or you've never ever heard of it before. Anyway, we'll never find out because you did not say why you don't like the article. This makes your message pointless. You might even be a...Troll?
Sign In·View Thread·PermaLink

Treeview and Listview
3base

23:57 24 Nov '08

I appreciated this nice little summary of controls. Can we have one on treeview and listview type controls?
Sign In·View Thread·PermaLink

Re: Treeview and Listview
Josh Fischer

4:56 25 Nov '08

Yes, this article was getting long so I decided the "view" controls would need to have their own article. I mentioned this in the "Panels & Lists" section Look for it in the next couple of weeks. I appreciate everyone comments and votes and I hope my "quick start" articles can help some people. Josh Fischer
Sign In·View Thread·PermaLink