Let’s say you had a form that collected a bunch of user input, and then had a button that would fire off some work. We’ll assume that you wanted to prevent people from firing off the work again before they know the results of the first time, so you’ll disable the button while you’re working. Something like this (leaving out the boring stuff about collecting the user’s input and displaying the results):

It’s pretty simple. In fact, I think there’s only three things worth pointing out:

1. There are variables for named controls.
2. If you want to make sure a control has time to update it’s display while you’re executing your event handler, call UpdateLayout().

1. You can disable and enable buttons.

Now, try doing the same thing with Windows Forms.

This was my first attempt:

Now, I bet you noticed that took a bit more code than the WPF version in ShowUI, but the thing about it is that I also had to manually specify the positions of the controls (and I had to set the size of the form to make that work). And after all that, it still doesn’t actually work, and it has a few ugly behaviors:

First of all, disabling the control doesn’t work, because Windows posts all click events as messages to the button’s message queue, and it doesn’t know that it should ignore them, because it only processes one at a time — when it’s done running the Click handler the first time, it notices there’s another event … and since it’s enabled, it processes it. If you click it five times while it’s disabled, you’re going to get the work done five more times… eventually.

On top of that, although the label updates without being told to, it didn’t push the button down the screen or resize the form, so eventually it overlaps the button, passes through the bottom of the form and disappears.

The next thing I tried was to actually unhook the event handler before I disable the button … but that had no effect either, because (as I wrote earlier) the button doesn’t actually ignore the clicks while it’s doing the work — it just queues them up for processing later.

Of course, I could do the work in a background job so that the button would return immediately, but that doesn’t meet the requirements I have for not queuing up extra work before the first work is done, and in fact, then I’d have extra work to do to create a time to check and see if the remote job was finished or not.

[New] Thanks to SAPIENDavid, I’ve realized the simple fix for the disabling problem, we just have to call DoEvents to empty the event queue before we re-enable the button.

Here’s what did work:

To fix the other problems, I added a FlowLayoutPanel (which is very different from the StackPanel in WPF, but still serves the same purpose), and made all the relevant bits autosize (it’s always surprising to me when I need to drop back to WinForms, how everything has to be told to autosize and fill empty space).

That’s enough to take care of the output problem, and make the two solutions roughly equivalent (there’s still some differences, as you can see if you run them).

For what it’s worth, this was a real world question from a user at our Virtual User Group this morning, and I just couldn’t help sharing how much easier user interfaces are to write in ShowUI. Clearly a designer like PrimalForms makes laying out the controls easier — but when it comes to the little things, you still have to figure out to make them work, and actually implement your event handlers correctly.

Just for the record, here’s what it would take to implement the WPF solution without ShowUI:

In programming, we call those interactions “events.” An event in WPF covers all forms of user interactions like clicking a button, type in a textbox, or select items from a treeview or listbox, and even less obvious things like when the right or left mouse button get’s pressed down, or let up … or when the mouse moves, of when the control gets focus or looses it, or “touch” and “stylus” events, drag-and-drop events, etc. There are also events that aren’t caused by users, like events for when databinding is updated, when the control is initialized, hidden, made visible, etc.

In ShowUI, all events are handled by assigning scriptblocks to a parameter who’s name starts with “On_” like -On_Click or -On_GotFocus or -On_MouseLeftButtonDown or -On_TextInput … and so on.

Let’s say that you want a quick dialog like this:

You’re going to need to handle the OK button click, of course, but in that scriptblock, you’re going to want to get the text from the textbox, and make sure that it gets returned when the window is closed … and you’re going to want to close the Window!

We’re here to help! Within the event handler script blocks, ShowUI defines a bunch of variables for you to help you handle the event: $this is the source of the event, $_ is the event arguments, and $window is the top-level window that contains your UI. Any named controls in your script are also exposed as variables, so if you started with this script:

You’re going to be able to get the text from the TextBox using $FullName.Text because you know the TextBox has a property named “Text” (since it’s exposed as a parameter for you in the TextBox command), and because now you know that ShowUI creates a variable for all the named controls.

In order to write output from a script like that one, you have to set the Tag property on the top level control (in this case, the StackPanel, which is obviously named “Prompt”). You can do that easily by hand, or you can use the Set-UIValue function.

In order to close the window, you’re going to have to do one of two things: first, you can use the handy Close-Control function, or you can call the Close method on the window. The Close-Control function will look at the “parent” (and it’s parent) to try and find the window that needs to be closed — but if it can’t find one, it will just hide the parent, so if your button were several layers deep (unlike ours), you’d have to specify the top level control as a parameter.

Here’s two versions of what it could have looked like when I was finished:

One thing you’ll notice right away is that I cheated and actually added another event handler too: For the “Loaded” event on the StackPanel. This event handler is called during the initialization of the user interface, and gives you a chance to do things like what I did here: set the initial keyboard focus where you want it (so the user can start typing as soon as the window pops up).

However, if you run them both, you’ll notice another thing: the output is different. In the second example I took advantage of the fact that Set-UIValue will actually call Get-UIValue if you don’t pass it a parameter! The cool thing about Get-UIValue is that if it doesn’t find a “Tag” on the specified control, it will look through the children to find one, and create a hashtable out of the values it finds. So in this case, rather than write the code to get the value from the right textbox and set it myself, I just let the built-in features of ShowUI do their thing.

A bigger example

Of course, in neither example did I need to do anything with the button or with the actual parameters that are passed in to the button’s “Click” event … so perhaps one last (more complicated) example would be useful:

Hopefully, by now this doesn’t need a whole lot of explanation, but let’s walk through it anyway. First of all, if you’re not familiar with them, this script uses the excellent PowerShell Commands for Active Directory from Quest software. This doesn’t represent a full, complete, useful user interface — it’s more of an example that you can hopefully work from (and please, contribute ammendments on PoshCode).

You can see that I used a Grid with four rows and two Columns: with one column “Auto“sized, and one using up all the rest of the UI (you can resize the window to make the fields bigger). The first thing in the grid is the definition of a scripblock which I assigned to a variable $GetGroups. The reason I did that is because I wanted to reuse the scriptblock as the event handler for both the UserName and EmailAddress fields.

Without dwelling a whole lot on it, you can see the last line is the “OK” button which get’s the parent grid and calls Set-UIValue to invoke, as before, the hashtable collection of all the textbox values.

The interesting stuff is in that GetGroup event handler:

You can see that first we call Get-QADUser with the Text of $this field. By using $this, we make it so the event handler will work on both Textboxes, since it will get the text of whatever triggered the event handler. Get-QADUser doesn’t return anything unless it finds a user, and setting the SizeLimit ensures that we won’t end up waiting for it to retrieve “all” the users just because the Textbox was left empty. In fact, the point of that line is to make sure that we matched a user.

On the next line, I’m making sure that either the LogonName or Email of the user that we found matches fully the text that the user typed. This makes sure that the user that we matched is a full match, so we know we’ve gotten the person typing into the form to type a full, complete username or email address.

When it does match, we set the color to Black (in case it was an error and set to Red before), and we call Get-QADGroup to get all the groups that the user is a member of. We set those groups as the source for the $Group listbox, and they’ll immediately show up for the user. And finally, we update the few fields we’re showing from the user object we retrieved earlier.

Of course, when it doesn’t match, we set the text red to indicate an error, and then we zero out the data on the group listbox.

I hope this has helped some of you figure out event handlers in ShowUI — please feel free to ask questions in the comments below or on the ShowUI discussion boards.

An introduction to ShowUI

ShowUI is the next generation PowerShell module for building user interfaces in script. It’s the merger of my previous PowerShell UI project (called PowerBoots) with one by James Brundage, former Microsoft PowerShell team member and founder of Start-Automating (called WPK) which shipped in the Windows 7 resource kit.

If you want to follow along, you need to:

1. Get a copy of the ShowUI Module from CodePlex
2. Install it by putting the “ShowUI” folder in one of your “Modules” folders (list them by typing $Env:PSMODULEPATH in PowerShell v2, and feel free to create the one you want if it doesn’t exist). You should end up with something like C:\Users\Jaykul\Documents\WindowsPowerShell\Modules\ShowUI\ShowUI.psm1
3. Run PowerShell ISE, or use PowerShell.exe with the -STA switch (the best way to do this is to add it to the shortcut you use to launch PowerShell: open the properties dialog, and on the Shortcut tab, add “ -STA” to the Target)¹.

Did I hear someone ask what is WPF? It was introduced as part of .Net 3.0 (and vastly improved in .Net 3.5, and again in 4.0), so you can expect to find it preinstalled on computers from Vista on, and of course you can download and install it on XP if it’s not already installed. The only thing you really need to know about WPF for the purposes of this tutorial is that it is the new GUI toolkit for .Net, and that it is container based — you put elements into other elements to control the layout, rather like HTML and Java Swing… you can pick up the rest as we go along.

A simple ShowUI program

This first example is a little bit more verbose than it needs to be, because the -Content parameter is positional, so the first non-named argument you pass will be used for that. The same is true for the -Children parameter of panels, and in fact, each of the other similar content parameters: Items, Blocks, and Inlines.

Additionally, each control is aliased without the New- verb, so you could just call Button instead of New-Button … and of course, since our button doesn’t do anything, we could just as easily have used a Label, and written:

Note: “Label” is also the name of an executable for labelling drives in Windows, make sure ShowUI is imported before you run that command.

One last point: ShowUI brings a lot of features from WPK to the table, and one you’ll use a lot is the ability to skip specifying the window and put the -Show parameter on almost any WPF element. This is partly because we’re back to running PowerShell 2.0 with the -STA switch, but in any case, we can now skip the “New-BootsWindow” command, and our examples can be that much simpler.

We can put controls in a stack

StackPanels are awesome. So are WrapPanels. Try that code with a WrapPanel instead of a StackPanel and see what the difference is (hint: try resizing the window). Actually, try it with a UniformGrid too. WPF has several other panel containers too: Grid, ToolBarPanel, TabPanel, DockPanel, Canvas … we’ll talk about some more of those later.

Ok, lets see some formatting

To scoot the buttons out from the edge we can use margins or padding: margins go on the outside of containers, padding goes on the inside. We can also specify the FontFamily, FontSize, FontWeight, and FontStyle, as well as Foreground and Background colors …

So you see, the pink background is on the StackPanel, which has a (default, white) margin around it. If you wanted the whole background of the window to be pink, you would need to set the background of the Window instead of the StackPanel.

An aside on Typography

ShowUI doesn’t need to create a full set of typography-specific top-level elements the way Shoes does, because we are based on WPF, which has a far more powerful typography system available than any we’ve used previously. So, with WPF we start by selecting a control based on how much text you want to put in it, and how much formatting you want to apply: Label and TextBox are the simplest, TextBlock supports limited text formattings, and FlowDocumentViewer or RichTextBox support full rich content. And of course, Hyperlink supports clicking

For the typography elements, the content model changes a little bit. There are basically two types of typographical elements: Inline and Block elements (where inline elements can’t contain block elements). In fact, he TextBlock Content Model is similar to that of an inline element. It is actually a type-restricted “Items” container. Instead of being able to have anything as content, it can only contain Inline flow content elements such as AnchoredBlock, Bold, Hyperlink, InlineUIContainer, Italic, LineBreak, Run, Span, and Underline, and it will create a run automatically if you just put a text string in it.

Note: If you want support for the full document model (which allows Paragraphs and Lists), you need to use a FlowDocumentReader, FlowDocumentPageViewer, RichTextBox, or a FlowDocumentScrollViewer ... there’s lots more information about those on msdn.

Time for some artwork

In WPF, everything always starts out white, and you must position things based on the container. You can see that the Margin can be specified as a single value as in the previous example, or as separate values for Left, Top, Right, Bottom. Oddly, to satisfy PowerShell’s type-casting, you have to quote them so they’re a single comma-separated string, instead of four separate values.

Some more advanced drawing

When you want to start getting clever and overlapping things, you need to use a Canvas container. The Canvas can contain multiple items which are all absolutely positioned, but unlike most other containers, it doesn’t automatically expand to contain it’s children, so you typically have to set it’s size.

We also have to set the Stroke and Fill. These are the two colors that make up every object, and again, if we don’t set them, they default to white. Note that you can use named colors, or you can specify a hex value using “#RRGGBB” or “#AARRGGBB” to set the alpha channel. The StrokeThickness controls the line thickness.

One other thing to notice is that we positioned the Rectangle by using the Margin, but we positioned the arrow, which we built using a Polygon, based purely on the x,y coordinates of the points. The available shapes are Ellipse, Line, Path, Polygon, Polyline, and Rectangle. You can, of course, make nearly any shape you want with the Polygon.

There are other more advanced shapes available in external libraries, and we can even do 3D, use gradient or image fills…

We can even get images straight off the web

WPF loads the image on a background thread, and caches it in memory, so the window will show up and be responsive while you’re waiting for the image, and because we’ve specified -AsJob, you can actually continue using PowerShell while the image loads. Note: it will load much faster the second time you run that script.

Events

If you were paying attention to the typography example, you’ll have noticed that we introduced event handling without making a big fuss about it. Event handlers in PowerBoots are specified in much the same way that Properties are, except that their parameter names always start with “On_” and they take a script block. The Hyperlink element in a WPF window doesn’t automatically open a browser (because you can use it to change “pages” in a WPF application), so to make simple web links work, you have to handle the “RequestNavigate” event as shown above.

In order to update your user interface when an event triggers, you’ll need to have variables that point at the control(s) you want to affect. In ShowUI event handlers, you get a $this variable which points at the object that caused the event, a $_ variable which is the event arguments, and a $window variable for the top-level window … you also get variables for each named control in your window.

WPF Elements all have a Tag property which can be used to store any object, so as you can see in the previous example, you can use that to keep track of things … but more importantly, the value of the Tag on the top-level control will be output. In other words, when the window is closed, this example actually outputs to the PowerShell pipeline how many times you clicked the button.

Working with User Input

There are helper functions in ShowUI for working with that output value: Set-UIValue and Get-UIValue, and Get-UIValue is particularly helpful because if the control it’s called on has no value, it collects the values of all the child controls, so you can use it to output a whole form at once:

I’ve made this example more complicated than it needed to be to demonstrate some best practices. We could have made it much simpler by using a UniformGrid control instead of a GridControl, thus avoiding needing to set the -Row and -Column special parameters, but I wanted to show those to you anyway, and the form looks a lot better when the two columns can have different sizes:

You’ll notice how easily I specified the width of the columns, but the COUNT of the rows in the Grid panel. If you provide an array of values, they’re converted to GridLengths, but if you provide just one, it’s treated as the count. You can make grid columnds and rows AUTOmatically size to their contents, and you can make them * width to make them take up any extra space. You can even split the extra space by setting * on more than one column (and specify the proportion by using numbers, like: 1*, 2*).

I should also point out that if you use MinHeight and MinWidth instead of the Height and Width values, your controls will be able to size up to fill space when the window is resized! Try that script with Width and Height instead and resize the window to see the difference.

We used the Set-UIValue shortcut in this form, which brings up another point: when creating data forms, you only need to name the controls you want output from. Then you’ll be able to just call Set-UIValue on the parent to collect all the values from the controls and output them as a hashtable!

Finally, remember your defaults: set the focus to something so the user doesn’t HAVE to click to get started, and set a button to -IsDefault with a On_Click handler so that when the user hits enter they can submit the form.

Further directions

There’s a lot more possible with ShowUI: we can use gradients for colors, create data templates and styles, and even make chromeless windows, but you have the basics for getting started already.

This first release of ShowUI is still missing some features from both WPK and PowerBoots, but we’ll get to them as we progress. For now we’d like to invite you to come download the latest release, and write up or vote up the features that you want the most in the next version. Keep an eye on the release page and on the discussions and we’ll be cranking out new releases on a monthly basis for now.

I hope you’ve enjoyed this tour through ShowUI, and will be able to start applying it soon for fun and profit.

¹ The -STA switch is necessary because the .Net framework requires the STA threading model in order to do graphical user interfaces. PowerShell ISE doesn’t require it because unlike the PowerShell.exe command console (which is a Win32 native “console” application that hosts the .Net framework), PowerShell ISE is a .Net framework “graphical” application, and is therefore running in the STA model already.

• PowerPoint Deck

• PDF Deck with notes

WPK:

Command : $boxes = 1..100 | % { New-TextBox -Text Foo -FontFamily Consolas -On_GotFocus { $_ } }
Duration : 5.25153s

Current PowerBoots 0.2:

Command : $boxes = 1..100 | % { TextBox -Text Foo -FontFamily Consolas -On_GotFocus { $_ } }
Average : 9.40994s

You can see why I thought I should probably work on improving that. It was bad.

PowerBoots 0.3 yesterday:

Command : $boxes = 1..100 | % { TextBox -Text Foo -FontFamily Consolas -On_GotFocus { $_ } }
Duration : 7.43874s

PowerBoots 0.3 tonight:

Command : $boxes = 1..100 | % { TextBox -Text Foo -FontFamily Consolas -On_GotFocus { $_ } }
Duration : 0.34103s

Now, if you’re like me, you’re probably thinking I screwed up something and that TextBox isn’t actually getting created right …

Postscript: ran another test. A little more useful. I have 248 fonts on my system. I have an “Samples” script which shows them all:

Old PowerBoots:

Duration : 19.39894s

New PowerBoots:

Duration : 3.53100s

So crank up your Visual Studio Express Edition and make yourself some user interfaces!

Basically, you just create a WPF project in C# or VB.Net or whatever … I chose to name my project “XamlForBoots” — your project will start off with an empty MainWindow.xaml file which will look something like this:

After you drag a few more controls onto the form, and you’ve created a complete user interface, you should delete the x:Class attribute. You need to make sure you know the name of the controls you want to interact with, so you might end up with something like this (I used the property pane, which you can’t see in this shot, to name each textbox and the button):

At this point, we’re ready to drop into PowerShell and write some script. Now … there is one catch here. The first script I’m going to show you here is for PowerBoots 0.3 (which will be the first release candidate for a gold 1.0 release, and will be out soon™). However, I’ll post below some code to make it work on the current release, but it requires an external function.

So, in the next release, you can just do something like this:

The key thing you’re supposed to notice here is that the named controls in the XAML are automatically surfaced as variables in the event handlers, and all you have to do is write your logic and hook it up to the controls. We provide a Register-BootsEvent cmdlet which is like Register-ObjectEvent except that it executes the event handlers on the UI thread (so they can do things to the UI) instead of in a new runspace, but basically it’s like calling Add_Click. Of course, you can use Register-ObjectEvent if you just want to spin off PowerShell tasks that don’t read/write the UI.

Backwards compatibility

To get this to work in the current release, you need a function Export-NamedControl to create variables for each of those named controls as variables. Once you’ve defined that function, you can write code very much like I did before, but you have to call Export-NamedControl yourself, and you won’t have that Register-BootsEvent cmdlet. You don’t really need it for this anyway, so that’s not a big deal, at least in this case. Here’s the function. and the actual code to create the window. You can just paste this into a script file:

And in order to try my demo, you’re going to need that MainWindow.xaml file:

Format-PoshTable (PowerBoots + DataGrid from WPFToolkit + PoshConsole) on ScreenCast or Vimeo (and PoshCode).

If you can’t view that (it requires Windows Media Player), you can check it out through Vimeo below. I apologize for the size and quality of that, I didn’t read the HD instructions ahead of time. Skip to the end for the code

A simple demo of some of the capabilities of PowerBoots and PoshConsole in the form of a grid-output function...

PowerShell 1.0 Compatibility

There are three huge changes in this release, actually. But the biggest one is that most of the functionality works in the released version of PowerShell 1.0! There are still a few glitches and bugs when it’s running in 1.0, but I’ve decided it’s past time I just release it and let you start using it! If you use it on 1.0, please let me know if you run into anything weird, or problems you can’t figure out workarounds for.

Cached Script Functions!

The second biggest change is that all of the functions are now cached. The first time it’s loaded, PowerBoots actually writes out a few hundred scripts files into a “Functions” subfolder, and from then on, they’re only loaded when they’re used — saving you a lot of time at startup, and a lot of memory. Additionally, when you load in additional controls, such as the Visifire WPF chart controls, those functions are cached permanently too, so you never even have to manually load the assembly again!

Dependency Properties

A few people have asked over the last few months about how to set attached properties and dependency properties in WPF from PowerShell, so in this release I’ve included full support for these in a way that will, I hope, simply work so well it will boggle your mind All you have to do to tell a control, for instance, to be in the 3rd column of a grid is to just pass Button "Click Me" -"Grid:Column" 2 … it’s THAT simple. In fact, for properties that have unique names, you don’t even have to specify the type, just the name, like -Row 3 to specify the grid row.

Regression and Backwards Compatibility

Of course, the downside of these changes is that some of the syntax has changed a little bit. All scripts and event handlers (ie: click handlers for WPF Buttons) are run from the dll module scope in PowerShell 2 (the global scope in PowerShell 1), which means that they can’t access “script” scope variables from your scripts (which ends up meaning you have to declare a lot of things global that you could leave in script scope before). Just to be clear on the quality of this release: once we have ironed out the minor problems we’re having with PowerShell 1.0 in a way that I’m comfortable with, I expect to push the version number up and release an 1.0 Release Candidate, barring any major issues.

In order to help with the transition, I’ve included a Samples.ps1 script which has 28 sample scripts in it (mostly from the original Tutorial Walk-through, which I will update soon). I’ve updated each of them to work with this release, in both PowerShell 1 and PowerShell 2 (which means they’re almost all written in PowerShell 1 syntax), so you can use them as good examples of how to get things done!

Please use the Discussions Forum and Issue Tracker on the CodePlex site to post any problems you have, and I’ll try to write up a few more posts describing changes and differences in the next couple of weeks.

Related articles by Zemanta

• PowerBoots: Loading XAML Windows in PowerShell 1.0 or 2.0 (huddledmasses.org)
• PowerBoots: PowerShell GUIs are now multi-threading (huddledmasses.org)
• PingMonitor: interactive WPF UIs from PowerShell (1.0 or 2.0) (huddledmasses.org)

An introduction to PowerBoots

Please excuse me if I start by just copying the basic ideas of the Shoes Tutorial, but I figured that since PowerBoots is inspired by Shoes, that was as good a place as any to start. PowerBoots (or just “Boots”) is a PowerShell 2.0 module with functions for writing Windows Presentation Framework (WPF) applications in the PowerShell scripting language. You should get the latest version of PowerBoots before continuing, and install it by putting the “PowerBoots” folder in one of your “Modules” folders (list them by typing $Env:PSMODULEPATH in PowerShell v2).

Don’t forget to start PowerShell.exe with the STA parameter (This is no longer required in PowerBoots 0.1).

Did I hear someone ask what is WPF? It was introduced as part of .Net 3.0 (and vastly improved in .Net 3.5), so you can expect to find it preinstalled on computers from Vista on, and of course you can download and install it on XP if it’s not already installed. The only thing you really need to know about WPF for the purposes of this tutorial is that it is the new GUI toolkit for .Net, and that it is container based — you put elements into other elements to control the layout, rather like HTML and Java Swing… you can pick up the rest as we go along.

A simple Boots program

I’ve recently changed this first example to pass a script block to the content instead of using parentheses, because although PowerBoots supports running in an MTA PowerShell host, the only UI-creation command that is MTA-safe is the New-BootsWindow command. All of the “new” functions must then be inside of a scriptblock which is passed to the New-BootsWindow cmdlet and executed on that STA thread. You can use parenthesis ( and ) as a container instead, but that requires the host to be in STA threading mode (run: PowerShell -STA) so the controls can be created:

This first example is a bit uglier than the Shoes syntax, so lets see if we can’t clean it up some. The -Content parameter is positional, so the first non-named argument you pass will be used for that. The same is true for the -Children parameter of panels, and in fact, each of the other similar parameters: Items, Blocks, and Inlines.

We have used a function New-BootsWindow which has an alias Boots. Boots takes all the same parameters as the Window function mentioned previously, but it uses slightly more useful defaults, and has a few other major benefits as well, the first of which is that it automatically “shows” the window, and the second is that it supports an -Async parameter which allows the window to come out in a new thread so that you can continue using PowerShell while the window remains alive and responsive. There is one catch: New-BootsWindow cannot take it’s content on the pipeline (the old function, now renamed “Out-BootsWindow” can take pipeline content, but is a script function, and requires -STA mode) — you have to specify it as a ScriptBlock. So now that we know this, we can rewrite our first example like this:

Just for the record, the simplest Boots program would just be a simple popup dialog to put some text in a Window, like: Boots { $msg } …

We can put controls in a stack

StackPanels are awesome. So are WrapPanels. Try that code with a WrapPanel instead of a StackPanel and see what the difference is. This brings up another point: those positional parameters we mentioned earlier: Content, Children, Items, Blocks, and Inlines, are also set to accept the value from the pipeline. Not only that, but they are intelligent about whether or not the content model accepts multiple items! So we can actually rewrite that script like this, and get the same results:

Now we’re really onto something! For most of the rest of these examples, I’m going to stick with the former syntax, because with the indenting and parenthesis, it’s much easier for you to follow, especially if you’re not already familiar with WPF. For instance, check out what this does:

Ok, lets see some formatting

To scoot the buttons out from the edge we can use margins or padding: margins go on the outside of containers, padding goes on the inside.

So you see, the pink background is on the StackPanel, which has a (white) margin around it. If you wanted the whole background of the window to be pink, you would need to set the background of the Window instead of the StackPanel.

Time for some artwork

In Boots, everything always starts out white, and you must position things based on the container. You can see that the Margin can be specified as a single value as in the previous example, or as separate values for Left, Top, Right, Bottom. Oddly, to satisfy PowerShell’s type-casting, you have to quote them so they’re a single comma-separated string, instead of four separate values.

Some more advanced drawing

We use a Canvas for this because it can contain multiple items which are all absolutely positioned. Unlike other containers, it doesn’t automatically expand to contain it’s children, so you typically have to set it’s size.

We also have to set the Stroke and Fill. These are the two colors that make up every object, if we don’t set them, they default to white. The StrokeThickness controls the line thickness. Notice that we positioned the Rectangle by using the Margin, and positioned the arrow, which we built using a Polygon, based purely on the x,y coordinates of the points. The available shapes are Ellipse, Line, Path, Polygon, Polyline, and Rectangle. You can, of course, make any shape you want to with the Polygon.

There are other more advanced shapes available in external libraries, and we can even do 3D, use gradient or image fills…

We can even get images straight off the web

Boots loads the image on a background thread, and caches it in memory, so the window will show up and be responsive while you’re waiting for the image, and because we’ve specified -Async, you can actually continue using PowerShell while the image loads. Note: it will load much faster the second time you run that script.

Typography

PowerBoots doesn’t try to create a full set of typography-specific top-level elements the way Shoes does, because we are based on WPF, which has a far more powerful typography system available than any we’ve ever used. So instead of having a bunch of named elements like banner, and title, and caption, and para and whatnot, we have controls based on how much text you want to put in them, and how much formatting you want to apply: Label is simplest, TextBlock supports limited text formattings, and FlowDocument supports full rich content. And of course, Hyperlink supports clicking

For the typography elements, the content model changes a bit. There are basically two types: Inline and Block elements. The TextBlock Content Model is similar to that of a FlowDocument, it is actually a type-restricted “Items” container. Instead of being able to have anything as content, it can only contain Inline flow content elements such as AnchoredBlock, Bold, Hyperlink, InlineUIContainer, Italic, LineBreak, Run, Span, and Underline, and it will create a run automatically if you just put a text string in it.

Note: If you want support for the full document model (which allows Paragraphs and Lists), you need to use a FlowDocumentReader, FlowDocumentPageViewer, RichTextBox, or a FlowDocumentScrollViewer ... there’s lots more information about those on msdn.

Events

If you were paying attention to that previous example, you’ll notice we just introduced event handling. Event handlers in PowerBoots are specified in much the same way that Properties are. Their parameter names always start with “On_” and they take a script block. The Hyperlink element in a WPF window doesn’t automatically open a browser (because you can use it to change “pages” in a WPF application), so to make simple web links work, you have to handle the “RequestNavigate” event as shown above.

In order to update your user interface when an event triggers, you’ll need to have a variable that points at the control(s) you want to affect. You get a $this variable for free which points at the object that caused the event (eg: the Hyperlink in our previous example), but otherwise you need to handle this yourself. You can do that one of two ways: you can set a variable the way you normally would, and then use the variable in the form, or you can specify the variable name using the -OutVariable parameter. Personally I prefer the latter, as it messes up the flow of code less, but it has the downside that the output variable is always an array, even when there’s only one item.

I’ve made these examples slightly more complicated than they had to be to demonstrate some best practices. When the Window is closed, the Out-Boots function returns the $BootsOutput variable — so if you want to output something from your gui, you need to set that variable. You can, of course, access global scope variables using the scope prefix $global:variableName, so you can set many different variables which you read later in your script. The catch is, sometimes the variables have to be explicitly set to script or even global scope in order to refer to the same variable in all of the event handlers…

However, if you want to have this block of code actually output something into the pipeline, you’ll always want to use the $BootsOutput variable. You can do that directly, the way the example above does, or you can simply use Write-Output! Inside the Out-Boots function, he Write-Output cmdlet just appends to the $BootsOutput variable … so it works pretty much exactly the way you would expect it to.

The first example outputs just the count of how many times you clicked. The second outputs a series of numbers from 1 to however many times you click. It’s your choice of how to work with it.

We can have fun with colors

Boots gives you access to all the capabilities of the Windows Presentation Framework, but in some cases that comes at a cost, because we haven’t simplified their composability. So we have RadialGradientBrush and LinearGradientBrush, but you have to specify the GradientStops etc …

We also have

So what does an InputBox look like?

Well, the simplest possible input box is just a TextBox, with the Width set (if you don’t set the Width, a TextBox will adjust to fit it’s contents, which can be really distracting). All you need to do is this:

Of course, the problem with that is that it pops up this rather confusing window, when what we really wanted was a prompt, and an “Ok” button, and some event handling to make the thing behave the way we expect it to. So lets try our first complicated form.

I’ll warn you ahead of time of one thing I’m going to do here. I’m using the “Border” element to apply a colored border to the StackPanel (because it doesn’t have it’s own border parameters), but then I’m also using the WindowStyle and AllowsTransparency properties to remove the normal window chrome, creating the bare little popup you see in the screenshot. I handle the mouse down event on the main window to allow the user to drag the window around by clicking anywhere on it (except in the TextBox or on the Button, of course). Now it looks slick, and —you know— it works!

Hopefully you can follow that, although it’s obviously over the top . We handle the KeyDown event on the TextBox (if the Key is the Return key), and we also handle the click on the Button. In both cases, we’ll write out the text that was entered, and use the special $BootsWindow variable to close the window. We also handle the Load event for the window, to make sure the focus is on the TextBox, so you can just start typing.

A final example

I’ve got quite a few more examples I want to show off in part two of this tutorial, but to get you thinking about ways to integrate this with your routine tasks, and give you some ideas of what you can do with what you know already, let me give you this example of browsing photos, with a visual indication of how big the image file is. Of course, the point is that you could be visualizing, you know … anything.

Notice that I had to manually handle the concept of a double click, because StackPanels don’t have a Click or DoubleClick event, just MouseDown and MouseUp. I could have stuck the stackpanel into something that does, but there’s really no need. Also, the [Diagnostics.Process]::Start is the equivalent of typing the name into the run dialog. I’m just executing the jpg, which makes it open in the default editor. It’s just a sample, after all.

End note

The current version of Boots does not add threading support, which means that when you run something through Boots, execution of your script stops until the window is closed. You can get around this somewhat in various different ways, but future releases will support running the WPF window in a separate thread, and even communicating to it … at the expense of a slightly different syntax. If you need that functionality, feel free to let me know … I could use some motivation.

I hope you’ve enjoyed this tour through PowerBoots, and will be able to start applying it for fun and profit.

Just for fun, I’m going to rehash an earlier post about updating windows to show how you can go about this using PowerBoots, and hopefully show that it’s a little easier (and a lot more async). Compare and contrast the code in this article with that one, just for fun.

This works with any version of PowerShell

Unlike the original article, most this code (except where explicitly mentioned) works on either PowerShell v2 with PowerBoots, or PowerShell 1.0 with PoshWPF, a snapin that is part of the PowerBoots module but is also released separately… Also, unlike those previous posts, this does not require you to be running PowerShell.exe with the -STA switch, since the New-BootsWindow cmdlet takes care of threading for us.

The simple splash screen

This is, of course, not a great example of why you would want to use XAML, since it reads virtually the same as it would if you wrote it in PowerBoots (if you were on PowerShell v2):

The big difference, of course, is that this is fully aync, so unlike the splash screen in the original post, we don’t have to do any tricks to get it to render, and we are able to add a MouseDown handler so you can drag the splash screen around while you wait for it to go away…

And now, for something completely different

Let’s skip over the very useful information I already wrote about the properties you can set on the “Window” object in WPF (all of which are parameters to New-BootsWindow, by the way) and cut straight to the second example … I’ve tweaked an old WPF sample I had and ported it to PowerShell, and now, adapted it for PoshWpf ... the xaml file is here and I’ll show you the code just as soon as you take a look at the screenshot (trust me, the code will make more sense if you’ve seen the output):

So basically, the UI is defined in a href=‘http://HuddledMasses.org/wpf-from-powershell-updating-windows/clock/’ rel=‘attachment wp-att-528’>that xaml file, and all we need to do in the script is update the time, update the CPU bar, and update the RAM bar…

Please notice the content block

PowerBoots passes the window object itself into the content scriptblock, and the content block must output the content you want in the window. Of course, if you’re loading a fully defined window in XAML, you don’t want to change the Window’s content, but you have to return something, so you should just return … the content that’s already in the window. Ie: $Args[0].Content

One other point, for those of you who are going to become XAML masters. In PowerBoots you can define just the styles and templates as resources in a separate XAML file which you can load with the Add-BootsTemplate, and then you can still create the UI in XAML or useing PowerBoots syntax. In my case, this XAML was edited using kaxaml (it could have been Expression Blend, or Visual Studio), and kaxaml doesn’t make it easy to separate out resource files, so I just left it all in one file:

So, meet Register-BootsEvent

If you’ve read the previous PowerBoots articles, you know that you can specify events as parameters to the PowerBoots functions, like -On_Click or -On_MouseLeftButtonDown, but in the case where you’re loading XAML, you can’t specify events in the XAML (WPF’s XamlReader won’t read XAML with events on it, or even with the Class specified, because you can’t use the associated code file anyway).

In any case, what I’m adding to the next version of PowerBoots/PoshWpf are two functions:

1. Find-BootsControl takes a boots window and the Name of a control, and will (try to) find the named control. Of course, for that to work, you need to know the name of the control (your best bet is to name it yourself, but in the next version I may also issue names for elements as they are created if you don’t specify the name).

1. Register-BootsEvent takes either a control, OR a boots window and control name, plus an event name and a ScriptBlock. If you pass the window and name, it calls Find-BootsControl to find the control; once it has a control, it registers the ScriptBlock as a handler for the specified event.

For now, both of these require that you’ve assigned a name to the control, but I’m working on setting things up so controls would be automatically named (based on their type, as with the old WinForms designer: like Button1, Button2, etc.), or allowing an XPath-like selection without named controls. In any case, this will work nicely for generating event handlers for WPF imported from XAML, and you can even specify the element directly (ie: if you don’t specify the -Name parameter, the event will be hooked on whatever element you pass in) so that last block of code can be written like this in the next release: