wsx Wiki & Documentation Rss Feed

Updated Wiki: Overview

cdmac — Mon, 08 Sep 2008 20:31:20 GMT

Overview

The WSX library has become fairly large and complex, and many of you have struggled to begin using it without guidance. This overview is intended to explain how the library works internally, so that you can use it, derive classes, and make modifications. Before starting however, I would like to point out that the source code is comprehensively documented.

GUIManager

The obvious place to start is with the GUIManager class. This class is at the base of the control hierarchy, but is not actually a control as it doesn't derive from UIComponent. It's main purpose is to act as the DrawableGameComponent that gets updated and drawn by the framework. On top of that, it tracks which control has focus, and draws the mouse cursor on top of all the controls.

Updated Wiki: Tutorials

cdmac — Mon, 08 Sep 2008 20:09:20 GMT

Tutorials

Tutorial 1 - Setting up and handling events
Tutorial 2 - Creating a dialog window

Updated Wiki: Tutorial 2

cdmac — Mon, 08 Sep 2008 20:07:01 GMT

Tutorial 2

This next tutorial will cover how to create a class that inherits from Dialog, and retrieve some useful information from it. This method of using windows was developed while putting together my tile map editor application. It is the best way of using the GUI that I have discovered so far, and is pretty closely based on other window systems I've used in the past. I'm sure some other techniques will expose themselves in the future.

Setting Up The Project

I have already covered setting up a new project, and setting up the GUIManager in Tutorial 1, so you can go back and look it up there if necessary. Simply follow Tutorial 1 up until the Adding Controls heading, and you'll be ready to go.

Creating The Dialog

We will create a Dialog box, where the user can enter their name into a textbox. It will have OK and Cancel buttons, so that the dialog can return a result.

The first thing to do is to create a new class called UserDetailsDialog, which is inherited from Dialog. Dialog is inherited from Window, and the only addition is that it returns a result, which can be queried after the Dialog is closed.

using System;
using Microsoft.Xna.Framework;
using WindowSystem;
namespace WindowSystemTestbed
{
    public class UserDetailsDialog : Dialog
    {
    }
}

Next we can add a few fields to our new class.

private const int LargeSeparation = 10;
private const int SmallSeparation = 5;
private TextButton OKButton;
private TextButton cancelButton;
private TextBox nameTextBox;

The LargeSeparation and SmallSeparation constants are something I add to all my dialogs. They allow me to control the spacing between the window edge and between dialog controls. I use LargeSeparation for the window edge, and between unrelated controls. SmallSeparation is used for the space between related controls, like between a textbox and it's label.

The rest of the fields are controls that we will need to keep track of after they are set up. We will need to get the text from nameTextBox for example. Other controls like labels can just be added without keeping a reference if they don't need to change, or we don't need to query them after events are triggered.

Next we should add a property, so that the user's name can be queried from outside the class.

public string Name
{
    get { return this.nameTextBox.Text; }
}

The constructor sets the control properties and adds them as child controls, as well as settings it's own properties.

public UserDetailsDialog(Game game, GUIManager guiManager)
    : base(game, guiManager)
{
    // Name label

    Label nameLabel = new Label(game, guiManager);
    Add(nameLabel);
    nameLabel.Text = "Name:";
    nameLabel.X = LargeSeperation;
    nameLabel.Y = LargeSeperation;
    nameLabel.Width = 75;
    nameLabel.Height = nameLabel.TextHeight;
    // Name textbox

    this.nameTextBox = new TextBox(game, guiManager);
    Add(this.nameTextBox);
    this.nameTextBox.Initialize();
    this.nameTextBox.X = nameLabel.X;
    this.nameTextBox.Y = nameLabel.Y + nameLabel.Height + SmallSeperation;
    // Set the window width to the default textbox width

    ClientWidth = nameTextBox.Width + (2 * LargeSeperation);
    // Cancel button

    this.cancelButton = new TextButton(game, guiManager);
    Add(this.cancelButton);
    this.cancelButton.Text = "Cancel";
    this.cancelButton.X = ClientWidth - this.cancelButton.Width - LargeSeperation;
    this.cancelButton.Y = this.nameTextBox.Y + this.nameTextBox.Height + LargeSeperation;
    this.cancelButton.Click += new ClickHandler(OnButtonClicked);
    // OK button

    this.OKButton = new TextButton(game, guiManager);
    Add(this.OKButton);
    this.OKButton.Text = "OK";
    this.OKButton.X = this.cancelButton.X - SmallSeperation - this.OKButton.Width;
    this.OKButton.Y = this.cancelButton.Y;
    this.OKButton.Click += new ClickHandler(OnButtonClicked);
    // Set the window height to the amount needed to show all controls

    ClientHeight = this.OKButton.Y + this.OKButton.Height + LargeSeperation;
    // Set the window title

    TitleText = "User Details";
    // This dialog does not need to be resized by the user

    Resizable = false;
    CenterWindow();
}

Note that I add child controls before setting their properties. This is because some controls don't become fully set up until they are initialised, which happens automatically when they are added to the GUI or another control. You could also just call Initialize() manually, but who needs the extra typing?

Also notice that control positions are set in relation to each other. I find this keeps the layout quite dynamic, especially for resizeable windows. I will consider providing layout managers in a future release, perhaps similar to those found in the Java Swing library.

The TextBox and TextButton controls don't have their Width or Height properties set. That's because some controls have useful default sizes, which allows some flexibility when modifying the default GUI settings.

Next we will add an event handler to the class, which will be called whenever a button is clicked. The buttons had this event handler added for their Click events in the constructor.

protected void OnButtonClicked(UIComponent sender)
{
    if (sender == this.OKButton)
         SetDialogResult(DialogResult.OK);
    CloseWindow();}

This method simply checks which button was clicked, and sets the result accordingly before closing the dialog. We don't bother checking for the Cancel button because cancel is the default result. This is because that is also the result when the user clicks on the window close button. If necessary the close button can be removed by setting the HasCloseButton property to false.

Using The Dialog

Back to the main game class which I have called Tutorial2, and we're going to attempt to use our new dialog.

The application will show an information message box, explaining how to use our simple program, then show our User Details dialog box when the user presses enter. If the user clicks on the OK button, a message box will display the name entered into the dialog textbox.

Firstly, add a dialog reference to our Game class.

private UserDetailsDialog dialog;

Next add an event handler that will be called when the user presses a key. In the constructor add the following code.

// Add a key down event handler

this.input.KeyDown += new KeyDownHandler(OnKeyDown);

Then create the event handler method.

private void OnKeyDown(KeyEventArgs args)
{
    if (args.Key == Keys.Enter)
    {
        // Only create a new dialog if one isn't already shown

        if (this.gui.GetModal() == null)
        {
            // Create and show dialog

            this.dialog = new UserDetailsDialog(this, this.gui);
            this.dialog.Close += new CloseHandler(OnDialogClosed);
            this.dialog.Show(true);
         }
    }
}

Basically this function just checks that no other modal window is already opened, if not then it pops up a new User Details dialog. Modal just means any window that has exclusive focus, such as a message box, or our dialog. To show a window as modal, pass true to the Window.Show() method, otherwise pass false.

When your program calls a modal dialog in Windows, it takes full control of you're processing until the dialog is closed. Unfortunately, our system is a little different. We have to add an event handler to the window's Close event, that checks which window was closed, and acts accordingly.

The following code is the method called when our dialog is closed.

private void OnDialogClosed(UIComponent sender)
{
    if (sender == this.dialog)
    {
        if (this.dialog.DialogResult == DialogResult.OK)
        {
            MessageBox message = new MessageBox(
                this,
                this.gui,
                "Name: " + this.dialog.Name,
                "User Name",
                MessageBoxButtons.OK,
                MessageBoxType.Info
                );
                message.Show(true);
        }
        // Remove event handler so garbage collector will pick it up

        this.dialog.Close -= OnDialogClosed;
        this.dialog = null;
    }
}

A message box is shown repeating the name entered by the user, only if the result was OK. Then the event handler is removed from the dialog and the dialog is set to null, to prevent it from lingering about in memory. This is very important to remember, especially in a real application. I've caught out by event handlers and the garbage collector on few occasions.

The final things to add is a message box explaining how to use the application. This should be placed in the Game class Initialize() method, to ensure it's shown at the start of the program.

// Show a message box informing the user how to use the program

MessageBox info = new MessageBox(
    this,
    this.gui,
    "Press enter to bring up the dialog.",
    "Info",
    MessageBoxButtons.OK,
    MessageBoxType.Info
    );
info.Show(true);

Conclusion

I hope this tutorial was helpful, it was definitely more difficult to write than the last one. I would really appreciate any feedback. I think in the next tutorial I will cover skinning and modifying the GUI.

All tutorial source code is included in the WindowSystemTestbed project.

Updated Wiki: Tutorial 1

cdmac — Mon, 08 Sep 2008 20:04:43 GMT

Tutorial 1

This first tutorial will cover setting up a GUIManager object, adding new controls, and handling their events.

Setting Up The Project

The simplest way to begin is to use the WindowSystemTestbed project as a starting template. I simply created a new source file containing a class called Tutorial1, and set that as the startup Game object in Main. You can use this if you don't feel like starting a project from scratch.

Setting Up The GUIManager

The first thing to do is to add a couple using statements for the InputEventSystem and WindowSystem namespaces.

using System;
using Microsoft.Xna.Framework;
...
using InputEventSystem;
using WindowSystem;

Now add some fields.

private GraphicsDeviceManager graphics;
private InputEvents input;
private GUIManager gui;

In the constructor we set up these objects, and add input and gui to the list of game components. It is important that the InputEvents object is created before the GUIManager object because it adds itself to the game services in the constructor, which the GUI will need access to. Not creating an InputEvents object at all will cause the program to crash.

public Tutorial1()
{
    this.graphics = new GraphicsDeviceManager(this);
    this.input = new InputEvents(this);
    Components.Add(this.input);
    this.gui = new GUIManager(this);
    Components.Add(this.gui);
    // GUI requires variable timing to function correctly

    IsFixedTimeStep = false;
    Window.Title = "Window System Tutorial 1";
}

The GUIManager object should be initialised in the overriden Initialize() method, before any child controls are added. This is so that order of resource loading can be predicted.

protected override void Initialize()
{
    // Has to be initialised before child controls can be added

    this.gui.Initialize();
    base.Initialize();
}

You will also want to override the Draw() method, to clear the screen each frame, although this probably doesn't affect the GUI as it handles drawing itself.

Adding Controls

I'm going to use a menu bar with various menus and menu items as an example. This will show how to create controls, how to add them to the GUI, and how to handle their events.

First we should add some fields, which are the menu bar and the menu items that the user will actually select. This means that we don't actually need to keep a reference to the 'File' menu for example, because it handles itself. We do need to keep references to child menu items that will actually be clicked, so that we can determine which one was selected. An example would be the 'New' or 'Save' menu items.

private MenuBar menuBar;
private MenuItem newMenuItem;
private MenuItem openMenuItem;
private MenuItem saveMenuItem;
private MenuItem saveAsMenuItem;
private MenuItem exitMenuItem;
private MenuItem undoMenuItem;
private MenuItem redoMenuItem;

Next we have to actually set up the GUI objects, and add them to the GUI. This should take place in Initialize(), after the GUIManager has been initialised.

this.menuBar = new MenuBar(this, gui);
MenuItem fileMenu = new MenuItem(this, gui);
fileMenu.Text = "File";
this.newMenuItem = new MenuItem(this, gui);
this.newMenuItem.Text = "New...";
fileMenu.Add(this.newMenuItem);
this.openMenuItem = new MenuItem(this, gui);
this.openMenuItem.Text = "Open...";
fileMenu.Add(this.openMenuItem);
this.saveMenuItem = new MenuItem(this, gui);
this.saveMenuItem.Text = "Save";
this.saveMenuItem.IsEnabled = false;
fileMenu.Add(this.saveMenuItem);
this.saveAsMenuItem = new MenuItem(this, gui);
this.saveAsMenuItem.Text = "Save As...";
this.saveAsMenuItem.IsEnabled = false;
fileMenu.Add(this.saveAsMenuItem);
this.exitMenuItem = new MenuItem(this, gui);
this.exitMenuItem.Text = "Exit";
fileMenu.Add(this.exitMenuItem);
menuBar.Add(fileMenu);
MenuItem editMenu = new MenuItem(this, gui);
editMenu.Text = "Edit";
this.undoMenuItem = new MenuItem(this, gui);
this.undoMenuItem.Text = "Undo";
this.undoMenuItem.IsEnabled = false;
editMenu.Add(this.undoMenuItem);
this.redoMenuItem = new MenuItem(this, gui);
this.redoMenuItem.Text = "Redo";
this.redoMenuItem.IsEnabled = false;
editMenu.Add(this.redoMenuItem);
this.menuBar.Add(editMenu);
// Add menubar to gui

this.gui.Add(this.menuBar);

You may notice that some of the menu items have a property called IsEnabled set to false. This basically makes the item grey and unclickable, just how Windows does it. This property only applies to MenuItem objects currently, but at some point in the future, I will probably make it apply to all controls.

Now if you run the application, it should show a menu bar with all the new menus and menu items.

Control Events

Next we will add event handlers that will be called whenever a menu item is clicked. The reason for holding references to menu items is for comparison with the clicked control, determining which one was actually clicked.

So add the following code to the Initialize() method, probably after the menu bar is added to the GUI.

// Add event handlers

this.newMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.openMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.exitMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.undoMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.redoMenuItem.Click += new ClickHandler(OnMenuItemClicked);

Finally we need to add a new method that is called whenever a menu item is clicked. We simply check which item was clicked, and act accordingly.

private void OnMenuItemClicked(UIComponent sender)
{
    if (sender == this.newMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "New clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.openMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Open clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.undoMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Undo clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.redoMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Redo clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.exitMenuItem)
        Exit();
}

Summary

This first tutorial was really simple, but should show you the basics of using the window system. It should be enough if all you want to do is add a couple buttons to your game. In the next tutorial I will show how to create a class that inherits from Window, to demonstrate how to begin to create a real application.

Updated Wiki: Home

cdmac — Mon, 08 Sep 2008 19:38:43 GMT

Project Description

Window System for XNA allows you to easily add GUI functionality to your games and tools that target the XNA Framework. It is being actively developed at the moment, so if anybody is interested in contributing to the project, then please leave a message in the forums.

Documentation

News - 18th May 2008

New release has the promised improved performance as well as various bug fixes. See release notes for more information.

Aaron

News - 17th May 2008

Last night I gave a demo of Window System for XNA to a group of XNA developers. The reception was good, and very much appreciated. The event was organised by XNA UK User Group (http://xna-uk.net), and sponsored by Microsoft. Thanks for all the food and drink!

The other projects I saw were really cool, some of which I can't wait until they are finished. Make sure you check out the site, especially if you're from the UK.

The evening also made me feel like working on my library again, so I've spent today bug fixing and thinking about new features. If you check out source control, you'll notice lot's of updates. The next thing I'll be working on it improving performance, by making my own implementation of SpriteFont, so I can do software clipping instead of using scissor rectangles.

Aaron

News - 26th March 2008

The promised release has finally been finished! The project has been updated to XNA 2.0, and adds XML skinning support.

In order to add XNA 2.0 support, I removed the remnants of the old render target system from Label. Scissor rectangles are now used, which has affected performance, but I will be doing some optimization for the next major release.

All the old static property calls have been removed, in favour of the new skinning system. During implementation I also cleaned up existing property interfaces and added new ones that were previously missing. These changes will likely break your current code, but it shouldn't be too difficult to fix.

The other changes are minor bug fixes.

I will be also adding full documentation to the wiki in the near future, with the possibility of new tutorials (if anybody suggests something). I also am looking for new team members to help contribute to the project.

At the moment I am working on a 2D game framework in XNA with a friend, that should have an alpha release in two weeks or so. I will post a link here when it is published on CodePlex.

News - 9th February 2008

There have been a lack of updates lately. Unfortunately I haven't really had time to work with XNA lately because of my job. I get to work on the PlayStation 3 every day, so I can't really complain!

The good news is that I have a release ready today! The bad news is that something seems wrong with the CodePlex site, so I can't upload the project. Below I've posted some information about the release. I'll try again later today.

"This release adds support for XML skin definitions. This method replaces the previous method of static properties to change GUI defaults, and is far more flexible. A skin definition can be applied to all subsequent controls, all existing controls, and also to individual controls.

I will add a short tutorial soon to explain the usage. For now check out the WindowSystemTestbed project that is included in the download, in particular DefaultSkin.skin, which is an XML skin featuring all possible properties set to their defaults.

Please note that many of the control properties have been changed, removed, or added to accommodate this new skinning system. It is likely that your existing code will break upon first compilation. It shouldn't be too difficult to go through the new class definitions to update your code.

Additionally, while implementing this I noticed some existing bugs that I had previously missed. I fixed most of them, but the ones remaining may prevent certain control skins from appearing as expected. Please submit all bugs to this site."

News - 5th November 2007

Sorry about the delay in uploading a new release, but it's finally ready! If anybody is thinking about a broadband provider in the UK, don't use Tiscali!

As promised, anti-aliased fonts are supported, and XNAExtras has been replaced with XNA SpriteFont. There is a chance it could break some code, as DrawableUIComponent has been removed, because it is now redundant with the new rendering code.

Now that these long-running problems have been fixed, look forward to new features in the near future.

News - 21st September 2007

Just to let everybody know that there should be a new release within the next week, basically when my internet connection is back up. The reason for the sudden release is because I've finally managed to fix the GUI rendering, with correct alpha values. The most important impact is that anti-aliased SpriteFont will be used from now on, and the old XNAExtras stuff is to be removed.

If anyone is interested in what the problem was, and how I fixed it, then read on.

In the old system, every control was rendered to its own texture using render targets. Each child control would have its texture combined with those of the other children, to make up the texture of the parent control (after drawing itself). It was quite efficient because only the top level controls (generally windows) actually get their textures drawn to the screen, with the textures only redrawn when necessary, such as when the mouse hovers over a button, and a different image must be displayed. Render targets were also an easy way to perform clipping of child controls within their parent, and allowed the alpha value of a control to affect all children as well.

The problem with render targets was that control textures had to be drawn to a transparent texture, causing incorrect colour and alpha values to be produced during the alpha blending operation. In practical terms, it means that the edges of sprites with partial transparency and anti-aliased text would be mixed with white (or any other colour depending on the clear colour of the render target). This made either anti-aliased text unreadable, or made the edges of some controls the wrong colour. The reason I couldn't use SpriteFont, was because it created anti-aliased fonts. With XNAExtras I could make a simple font bitmap with colour keyed transparency, which made the text problem go away.

After playing with render states and pre multiplied alpha for a long time, I finally got fed up and tried to find another way to get it working. I was advised to draw directly to the screen, and use scissor rectangles to handle clipping. This worked great, except performance was abysmal. With just 4 complex windows on the screen, the framerate would start to drop. That was without any game running in the background! The reason for the poor performance was because scissor rectangles must be the same until SpriteBatch.End() is called. This means that I had a SpriteBatch.Begin() and End() call for every single control!

Next I decided to implement my own texture clipping, which all worked great, but there wasn't an obvious way to clip text. When using scissor rectangles for just text, the performance was still really bad. The final method was to use a hybrid approach. I would clip sprites on the CPU, and render text to textures which would be cached to allow fast draw calls. The text texture can then be clipped in the same way as the rest of the GUI sprites. Of course there was still the problem of partial alpha pixels being blended with the transparent texture colour. Basically I set the render states to draw with pre multiplied alpha, and set the background clear colour of the texture to the text colour, with the alpha channel set to 0. This means that the blending still takes place, but it produces the correct results. The performance is good once again!

So yeah, the project isn't dead, I've just had some big problems to deal with. Now that this is working, I will go back to adding more features like Xbox 360 support, and more widgets.

Thanks,
Aaron

UPDATED WIKI: Home

cdmac — Sun, 18 May 2008 17:04:57 GMT

UPDATED WIKI: Home

cdmac — Sat, 17 May 2008 15:49:52 GMT

News - 17th May 2008

Last night I gave a demo of Window System for XNA to a group of XNA developers. The reception was good, and very much appreciated. The event was organised by XNA UK User Group (http://xna-uk.net), and sponsored by Microsoft. Thanks for all the food and drink!

The other projects I saw were really cool, some of which I can't wait until they are finished. Make sure you check out the site, especially if you're from the UK.

The evening also made me feel like working on my library again, so I've spent today bug fixing and thinking about new features. If you check out source control, you'll notice lot's of updates. The next thing I'll be working on it improving performance, by making my own implementation of SpriteFont, so I can do software clipping instead of using scissor rectangles.

Aaron

News - 26th March 2008

The promised release has finally been finished! The project has been updated to XNA 2.0, and adds XML skinning support.

In order to add XNA 2.0 support, I removed the remnants of the old render target system from Label. Scissor rectangles are now used, which has affected performance, but I will be doing some optimization for the next major release.

All the old static property calls have been removed, in favour of the new skinning system. During implementation I also cleaned up existing property interfaces and added new ones that were previously missing. These changes will likely break your current code, but it shouldn't be too difficult to fix.

The other changes are minor bug fixes.

I will be also adding full documentation to the wiki in the near future, with the possibility of new tutorials (if anybody suggests something). I also am looking for new team members to help contribute to the project.

At the moment I am working on a 2D game framework in XNA with a friend, that should have an alpha release in two weeks or so. I will post a link here when it is published on CodePlex.

News - 9th February 2008

There have been a lack of updates lately. Unfortunately I haven't really had time to work with XNA lately because of my job. I get to work on the PlayStation 3 every day, so I can't really complain!

The good news is that I have a release ready today! The bad news is that something seems wrong with the CodePlex site, so I can't upload the project. Below I've posted some information about the release. I'll try again later today.

"This release adds support for XML skin definitions. This method replaces the previous method of static properties to change GUI defaults, and is far more flexible. A skin definition can be applied to all subsequent controls, all existing controls, and also to individual controls.

I will add a short tutorial soon to explain the usage. For now check out the WindowSystemTestbed project that is included in the download, in particular DefaultSkin.skin, which is an XML skin featuring all possible properties set to their defaults.

Please note that many of the control properties have been changed, removed, or added to accommodate this new skinning system. It is likely that your existing code will break upon first compilation. It shouldn't be too difficult to go through the new class definitions to update your code.

Additionally, while implementing this I noticed some existing bugs that I had previously missed. I fixed most of them, but the ones remaining may prevent certain control skins from appearing as expected. Please submit all bugs to this site."

News - 5th November 2007

Sorry about the delay in uploading a new release, but it's finally ready! If anybody is thinking about a broadband provider in the UK, don't use Tiscali!

As promised, anti-aliased fonts are supported, and XNAExtras has been replaced with XNA SpriteFont. There is a chance it could break some code, as DrawableUIComponent has been removed, because it is now redundant with the new rendering code.

Now that these long-running problems have been fixed, look forward to new features in the near future.

News - 21st September 2007

Just to let everybody know that there should be a new release within the next week, basically when my internet connection is back up. The reason for the sudden release is because I've finally managed to fix the GUI rendering, with correct alpha values. The most important impact is that anti-aliased SpriteFont will be used from now on, and the old XNAExtras stuff is to be removed.

If anyone is interested in what the problem was, and how I fixed it, then read on.

In the old system, every control was rendered to its own texture using render targets. Each child control would have its texture combined with those of the other children, to make up the texture of the parent control (after drawing itself). It was quite efficient because only the top level controls (generally windows) actually get their textures drawn to the screen, with the textures only redrawn when necessary, such as when the mouse hovers over a button, and a different image must be displayed. Render targets were also an easy way to perform clipping of child controls within their parent, and allowed the alpha value of a control to affect all children as well.

The problem with render targets was that control textures had to be drawn to a transparent texture, causing incorrect colour and alpha values to be produced during the alpha blending operation. In practical terms, it means that the edges of sprites with partial transparency and anti-aliased text would be mixed with white (or any other colour depending on the clear colour of the render target). This made either anti-aliased text unreadable, or made the edges of some controls the wrong colour. The reason I couldn't use SpriteFont, was because it created anti-aliased fonts. With XNAExtras I could make a simple font bitmap with colour keyed transparency, which made the text problem go away.

After playing with render states and pre multiplied alpha for a long time, I finally got fed up and tried to find another way to get it working. I was advised to draw directly to the screen, and use scissor rectangles to handle clipping. This worked great, except performance was abysmal. With just 4 complex windows on the screen, the framerate would start to drop. That was without any game running in the background! The reason for the poor performance was because scissor rectangles must be the same until SpriteBatch.End() is called. This means that I had a SpriteBatch.Begin() and End() call for every single control!

Next I decided to implement my own texture clipping, which all worked great, but there wasn't an obvious way to clip text. When using scissor rectangles for just text, the performance was still really bad. The final method was to use a hybrid approach. I would clip sprites on the CPU, and render text to textures which would be cached to allow fast draw calls. The text texture can then be clipped in the same way as the rest of the GUI sprites. Of course there was still the problem of partial alpha pixels being blended with the transparent texture colour. Basically I set the render states to draw with pre multiplied alpha, and set the background clear colour of the texture to the text colour, with the alpha channel set to 0. This means that the blending still takes place, but it produces the correct results. The performance is good once again!

So yeah, the project isn't dead, I've just had some big problems to deal with. Now that this is working, I will go back to adding more features like Xbox 360 support, and more widgets.

Thanks,
Aaron

UPDATED WIKI: Home

cdmac — Wed, 26 Mar 2008 22:34:43 GMT

News - 26th March 2008

The promised release has finally been finished! The project has been updated to XNA 2.0, and adds XML skinning support.

In order to add XNA 2.0 support, I removed the remnants of the old render target system from Label. Scissor rectangles are now used, which has affected performance, but I will be doing some optimization for the next major release.

All the old static property calls have been removed, in favour of the new skinning system. During implementation I also cleaned up existing property interfaces and added new ones that were previously missing. These changes will likely break your current code, but it shouldn't be too difficult to fix.

The other changes are minor bug fixes.

I will be also adding full documentation to the wiki in the near future, with the possibility of new tutorials (if anybody suggests something). I also am looking for new team members to help contribute to the project.

At the moment I am working on a 2D game framework in XNA with a friend, that should have an alpha release in two weeks or so. I will post a link here when it is published on CodePlex.

News - 9th February 2008

There have been a lack of updates lately. Unfortunately I haven't really had time to work with XNA lately because of my job. I get to work on the PlayStation 3 every day, so I can't really complain!

The good news is that I have a release ready today! The bad news is that something seems wrong with the CodePlex site, so I can't upload the project. Below I've posted some information about the release. I'll try again later today.

"This release adds support for XML skin definitions. This method replaces the previous method of static properties to change GUI defaults, and is far more flexible. A skin definition can be applied to all subsequent controls, all existing controls, and also to individual controls.

I will add a short tutorial soon to explain the usage. For now check out the WindowSystemTestbed project that is included in the download, in particular DefaultSkin.skin, which is an XML skin featuring all possible properties set to their defaults.

Please note that many of the control properties have been changed, removed, or added to accommodate this new skinning system. It is likely that your existing code will break upon first compilation. It shouldn't be too difficult to go through the new class definitions to update your code.

Additionally, while implementing this I noticed some existing bugs that I had previously missed. I fixed most of them, but the ones remaining may prevent certain control skins from appearing as expected. Please submit all bugs to this site."

News - 5th November 2007

Sorry about the delay in uploading a new release, but it's finally ready! If anybody is thinking about a broadband provider in the UK, don't use Tiscali!

As promised, anti-aliased fonts are supported, and XNAExtras has been replaced with XNA SpriteFont. There is a chance it could break some code, as DrawableUIComponent has been removed, because it is now redundant with the new rendering code.

Now that these long-running problems have been fixed, look forward to new features in the near future.

News - 21st September 2007

Just to let everybody know that there should be a new release within the next week, basically when my internet connection is back up. The reason for the sudden release is because I've finally managed to fix the GUI rendering, with correct alpha values. The most important impact is that anti-aliased SpriteFont will be used from now on, and the old XNAExtras stuff is to be removed.

If anyone is interested in what the problem was, and how I fixed it, then read on.

In the old system, every control was rendered to its own texture using render targets. Each child control would have its texture combined with those of the other children, to make up the texture of the parent control (after drawing itself). It was quite efficient because only the top level controls (generally windows) actually get their textures drawn to the screen, with the textures only redrawn when necessary, such as when the mouse hovers over a button, and a different image must be displayed. Render targets were also an easy way to perform clipping of child controls within their parent, and allowed the alpha value of a control to affect all children as well.

The problem with render targets was that control textures had to be drawn to a transparent texture, causing incorrect colour and alpha values to be produced during the alpha blending operation. In practical terms, it means that the edges of sprites with partial transparency and anti-aliased text would be mixed with white (or any other colour depending on the clear colour of the render target). This made either anti-aliased text unreadable, or made the edges of some controls the wrong colour. The reason I couldn't use SpriteFont, was because it created anti-aliased fonts. With XNAExtras I could make a simple font bitmap with colour keyed transparency, which made the text problem go away.

After playing with render states and pre multiplied alpha for a long time, I finally got fed up and tried to find another way to get it working. I was advised to draw directly to the screen, and use scissor rectangles to handle clipping. This worked great, except performance was abysmal. With just 4 complex windows on the screen, the framerate would start to drop. That was without any game running in the background! The reason for the poor performance was because scissor rectangles must be the same until SpriteBatch.End() is called. This means that I had a SpriteBatch.Begin() and End() call for every single control!

Next I decided to implement my own texture clipping, which all worked great, but there wasn't an obvious way to clip text. When using scissor rectangles for just text, the performance was still really bad. The final method was to use a hybrid approach. I would clip sprites on the CPU, and render text to textures which would be cached to allow fast draw calls. The text texture can then be clipped in the same way as the rest of the GUI sprites. Of course there was still the problem of partial alpha pixels being blended with the transparent texture colour. Basically I set the render states to draw with pre multiplied alpha, and set the background clear colour of the texture to the text colour, with the alpha channel set to 0. This means that the blending still takes place, but it produces the correct results. The performance is good once again!

So yeah, the project isn't dead, I've just had some big problems to deal with. Now that this is working, I will go back to adding more features like Xbox 360 support, and more widgets.

Thanks,
Aaron

UPDATED WIKI: Home

cdmac — Sat, 09 Feb 2008 10:23:20 GMT

News - 9th February 2008

There have been a lack of updates lately. Unfortunately I haven't really had time to work with XNA lately because of my job. I get to work on the PlayStation 3 every day, so I can't really complain!

The good news is that I have a release ready today! The bad news is that something seems wrong with the CodePlex site, so I can't upload the project. Below I've posted some information about the release. I'll try again later today.

"This release adds support for XML skin definitions. This method replaces the previous method of static properties to change GUI defaults, and is far more flexible. A skin definition can be applied to all subsequent controls, all existing controls, and also to individual controls.

I will add a short tutorial soon to explain the usage. For now check out the WindowSystemTestbed project that is included in the download, in particular DefaultSkin.skin, which is an XML skin featuring all possible properties set to their defaults.

Please note that many of the control properties have been changed, removed, or added to accommodate this new skinning system. It is likely that your existing code will break upon first compilation. It shouldn't be too difficult to go through the new class definitions to update your code.

Additionally, while implementing this I noticed some existing bugs that I had previously missed. I fixed most of them, but the ones remaining may prevent certain control skins from appearing as expected. Please submit all bugs to this site."

News - 5th November 2007

Sorry about the delay in uploading a new release, but it's finally ready! If anybody is thinking about a broadband provider in the UK, don't use Tiscali!

As promised, anti-aliased fonts are supported, and XNAExtras has been replaced with XNA SpriteFont. There is a chance it could break some code, as DrawableUIComponent has been removed, because it is now redundant with the new rendering code.

Now that these long-running problems have been fixed, look forward to new features in the near future.

News - 21st September 2007

Just to let everybody know that there should be a new release within the next week, basically when my internet connection is back up. The reason for the sudden release is because I've finally managed to fix the GUI rendering, with correct alpha values. The most important impact is that anti-aliased SpriteFont will be used from now on, and the old XNAExtras stuff is to be removed.

If anyone is interested in what the problem was, and how I fixed it, then read on.

In the old system, every control was rendered to its own texture using render targets. Each child control would have its texture combined with those of the other children, to make up the texture of the parent control (after drawing itself). It was quite efficient because only the top level controls (generally windows) actually get their textures drawn to the screen, with the textures only redrawn when necessary, such as when the mouse hovers over a button, and a different image must be displayed. Render targets were also an easy way to perform clipping of child controls within their parent, and allowed the alpha value of a control to affect all children as well.

The problem with render targets was that control textures had to be drawn to a transparent texture, causing incorrect colour and alpha values to be produced during the alpha blending operation. In practical terms, it means that the edges of sprites with partial transparency and anti-aliased text would be mixed with white (or any other colour depending on the clear colour of the render target). This made either anti-aliased text unreadable, or made the edges of some controls the wrong colour. The reason I couldn't use SpriteFont, was because it created anti-aliased fonts. With XNAExtras I could make a simple font bitmap with colour keyed transparency, which made the text problem go away.

After playing with render states and pre multiplied alpha for a long time, I finally got fed up and tried to find another way to get it working. I was advised to draw directly to the screen, and use scissor rectangles to handle clipping. This worked great, except performance was abysmal. With just 4 complex windows on the screen, the framerate would start to drop. That was without any game running in the background! The reason for the poor performance was because scissor rectangles must be the same until SpriteBatch.End() is called. This means that I had a SpriteBatch.Begin() and End() call for every single control!

Next I decided to implement my own texture clipping, which all worked great, but there wasn't an obvious way to clip text. When using scissor rectangles for just text, the performance was still really bad. The final method was to use a hybrid approach. I would clip sprites on the CPU, and render text to textures which would be cached to allow fast draw calls. The text texture can then be clipped in the same way as the rest of the GUI sprites. Of course there was still the problem of partial alpha pixels being blended with the transparent texture colour. Basically I set the render states to draw with pre multiplied alpha, and set the background clear colour of the texture to the text colour, with the alpha channel set to 0. This means that the blending still takes place, but it produces the correct results. The performance is good once again!

So yeah, the project isn't dead, I've just had some big problems to deal with. Now that this is working, I will go back to adding more features like Xbox 360 support, and more widgets.

Thanks,
Aaron

UPDATED WIKI: Home

cdmac — Mon, 05 Nov 2007 23:30:09 GMT

News - 5th November 2007

Sorry about the delay in uploading a new release, but it's finally ready! If anybody is thinking about a broadband provider in the UK, don't use Tiscali!

As promised, anti-aliased fonts are supported, and XNAExtras has been replaced with XNA SpriteFont. There is a chance it could break some code, as DrawableUIComponent has been removed, because it is now redundant with the new rendering code.

Now that these long-running problems have been fixed, look forward to new features in the near future.

News - 21st September 2007

Just to let everybody know that there should be a new release within the next week, basically when my internet connection is back up. The reason for the sudden release is because I've finally managed to fix the GUI rendering, with correct alpha values. The most important impact is that anti-aliased SpriteFont will be used from now on, and the old XNAExtras stuff is to be removed.

If anyone is interested in what the problem was, and how I fixed it, then read on.

In the old system, every control was rendered to its own texture using render targets. Each child control would have its texture combined with those of the other children, to make up the texture of the parent control (after drawing itself). It was quite efficient because only the top level controls (generally windows) actually get their textures drawn to the screen, with the textures only redrawn when necessary, such as when the mouse hovers over a button, and a different image must be displayed. Render targets were also an easy way to perform clipping of child controls within their parent, and allowed the alpha value of a control to affect all children as well.

The problem with render targets was that control textures had to be drawn to a transparent texture, causing incorrect colour and alpha values to be produced during the alpha blending operation. In practical terms, it means that the edges of sprites with partial transparency and anti-aliased text would be mixed with white (or any other colour depending on the clear colour of the render target). This made either anti-aliased text unreadable, or made the edges of some controls the wrong colour. The reason I couldn't use SpriteFont, was because it created anti-aliased fonts. With XNAExtras I could make a simple font bitmap with colour keyed transparency, which made the text problem go away.

After playing with render states and pre multiplied alpha for a long time, I finally got fed up and tried to find another way to get it working. I was advised to draw directly to the screen, and use scissor rectangles to handle clipping. This worked great, except performance was abysmal. With just 4 complex windows on the screen, the framerate would start to drop. That was without any game running in the background! The reason for the poor performance was because scissor rectangles must be the same until SpriteBatch.End() is called. This means that I had a SpriteBatch.Begin() and End() call for every single control!

Next I decided to implement my own texture clipping, which all worked great, but there wasn't an obvious way to clip text. When using scissor rectangles for just text, the performance was still really bad. The final method was to use a hybrid approach. I would clip sprites on the CPU, and render text to textures which would be cached to allow fast draw calls. The text texture can then be clipped in the same way as the rest of the GUI sprites. Of course there was still the problem of partial alpha pixels being blended with the transparent texture colour. Basically I set the render states to draw with pre multiplied alpha, and set the background clear colour of the texture to the text colour, with the alpha channel set to 0. This means that the blending still takes place, but it produces the correct results. The performance is good once again!

So yeah, the project isn't dead, I've just had some big problems to deal with. Now that this is working, I will go back to adding more features like Xbox 360 support, and more widgets.

Thanks,
Aaron

UPDATED WIKI: Home

cdmac — Fri, 21 Sep 2007 17:10:34 GMT

News - 21st September 2007

Just to let everybody know that there should be a new release within the next week, basically when my internet connection is back up. The reason for the sudden release is because I've finally managed to fix the GUI rendering, with correct alpha values. The most important impact is that anti-aliased SpriteFont will be used from now on, and the old XNAExtras stuff is to be removed.

If anyone is interested in what the problem was, and how I fixed it, then read on.

In the old system, every control was rendered to its own texture using render targets. Each child control would have its texture combined with those of the other children, to make up the texture of the parent control (after drawing itself). It was quite efficient because only the top level controls (generally windows) actually get their textures drawn to the screen, with the textures only redrawn when necessary, such as when the mouse hovers over a button, and a different image must be displayed. Render targets were also an easy way to perform clipping of child controls within their parent, and allowed the alpha value of a control to affect all children as well.

The problem with render targets was that control textures had to be drawn to a transparent texture, causing incorrect colour and alpha values to be produced during the alpha blending operation. In practical terms, it means that the edges of sprites with partial transparency and anti-aliased text would be mixed with white (or any other colour depending on the clear colour of the render target). This made either anti-aliased text unreadable, or made the edges of some controls the wrong colour. The reason I couldn't use SpriteFont, was because it created anti-aliased fonts. With XNAExtras I could make a simple font bitmap with colour keyed transparency, which made the text problem go away.

After playing with render states and pre multiplied alpha for a long time, I finally got fed up and tried to find another way to get it working. I was advised to draw directly to the screen, and use scissor rectangles to handle clipping. This worked great, except performance was abysmal. With just 4 complex windows on the screen, the framerate would start to drop. That was without any game running in the background! The reason for the poor performance was because scissor rectangles must be the same until SpriteBatch.End() is called. This means that I had a SpriteBatch.Begin() and End() call for every single control!

Next I decided to implement my own texture clipping, which all worked great, but there wasn't an obvious way to clip text. When using scissor rectangles for just text, the performance was still really bad. The final method was to use a hybrid approach. I would clip sprites on the CPU, and render text to textures which would be cached to allow fast draw calls. The text texture can then be clipped in the same way as the rest of the GUI sprites. Of course there was still the problem of partial alpha pixels being blended with the transparent texture colour. Basically I set the render states to draw with pre multiplied alpha, and set the background clear colour of the texture to the text colour, with the alpha channel set to 0. This means that the blending still takes place, but it produces the correct results. The performance is good once again!

So yeah, the project isn't dead, I've just had some big problems to deal with. Now that this is working, I will go back to adding more features like Xbox 360 support, and more widgets.

Thanks,
Aaron

UPDATED WIKI: Home

cdmac — Sun, 26 Aug 2007 16:47:34 GMT

UPDATED WIKI: Tutorial 2

cdmac — Sun, 26 Aug 2007 16:33:46 GMT

Tutorial 2

Setting Up The Project

Creating The Dialog

using System;
using Microsoft.Xna.Framework;
using WindowSystem;
 
namespace WindowSystemTestbed
{
    public class UserDetailsDialog : Dialog
    {
    }
}

Next we can add a few fields to our new class.

private const int LargeSeparation = 10;
private const int SmallSeparation = 5;
private TextButton OKButton;
private TextButton cancelButton;
private TextBox nameTextBox;

public string Name
{
    get { return this.nameTextBox.Text; }
}

The constructor sets the control properties and adds them as child controls, as well as settings it's own properties.

public UserDetailsDialog(Game game, GUIManager guiManager)
    : base(game, guiManager)
{
    // Name label
    Label nameLabel = new Label(game, guiManager);
    Add(nameLabel);
    nameLabel.Text = "Name:";
    nameLabel.X = LargeSeperation;
    nameLabel.Y = LargeSeperation;
    nameLabel.Width = 75;
    nameLabel.Height = nameLabel.TextHeight;
 
    // Name textbox
    this.nameTextBox = new TextBox(game, guiManager);
    Add(this.nameTextBox);
    this.nameTextBox.Initialize();
    this.nameTextBox.X = nameLabel.X;
    this.nameTextBox.Y = nameLabel.Y + nameLabel.Height + SmallSeperation;
 
    // Set the window width to the default textbox width
    ClientWidth = nameTextBox.Width + (2 * LargeSeperation);
 
    // Cancel button
    this.cancelButton = new TextButton(game, guiManager);
    Add(this.cancelButton);
    this.cancelButton.Text = "Cancel";
    this.cancelButton.X = ClientWidth - this.cancelButton.Width - LargeSeperation;
    this.cancelButton.Y = this.nameTextBox.Y + this.nameTextBox.Height + LargeSeperation;
    this.cancelButton.Click += new ClickHandler(OnButtonClicked);
 
    // OK button
    this.OKButton = new TextButton(game, guiManager);
    Add(this.OKButton);
    this.OKButton.Text = "OK";
    this.OKButton.X = this.cancelButton.X - SmallSeperation - this.OKButton.Width;
    this.OKButton.Y = this.cancelButton.Y;
    this.OKButton.Click += new ClickHandler(OnButtonClicked);
 
    // Set the window height to the amount needed to show all controls
    ClientHeight = this.OKButton.Y + this.OKButton.Height + LargeSeperation;
 
    // Set the window title
    TitleText = "User Details";
 
    // This dialog does not need to be resized by the user
    Resizable = false;
    CenterWindow();
}

protected void OnButtonClicked(UIComponent sender)
{
    if (sender == this.OKButton)
         SetDialogResult(DialogResult.OK);
 
    CloseWindow();}

Using The Dialog

private UserDetailsDialog dialog;

Next add an event handler that will be called when the user presses a key. In the constructor add the following code.

// Add a key down event handler
this.input.KeyDown += new KeyDownHandler(OnKeyDown);

Then create the event handler method.

private void OnKeyDown(KeyEventArgs args)
{
    if (args.Key == Keys.Enter)
    {
        // Only create a new dialog if one isn't already shown
        if (this.gui.GetModal() == null)
        {
            // Create and show dialog
            this.dialog = new UserDetailsDialog(this, this.gui);
            this.dialog.Close += new CloseHandler(OnDialogClosed);
            this.dialog.Show(true);
         }
    }
}

private void OnDialogClosed(UIComponent sender)
{
    if (sender == this.dialog)
    {
        if (this.dialog.DialogResult == DialogResult.OK)
        {
            MessageBox message = new MessageBox(
                this,
                this.gui,
                "Name: " + this.dialog.Name,
                "User Name",
                MessageBoxButtons.OK,
                MessageBoxType.Info
                );
                message.Show(true);
        }
 
        // Remove event handler so garbage collector will pick it up
        this.dialog.Close -= OnDialogClosed;
        this.dialog = null;
    }
}

// Show a message box informing the user how to use the program
MessageBox info = new MessageBox(
    this,
    this.gui,
    "Press enter to bring up the dialog.",
    "Info",
    MessageBoxButtons.OK,
    MessageBoxType.Info
    );
info.Show(true);

Conclusion

UPDATED WIKI: Tutorial 2

cdmac — Sun, 26 Aug 2007 16:29:57 GMT

Tutorial 2

Setting Up The Project

Creating The Dialog

using System;
using Microsoft.Xna.Framework;
using WindowSystem;
 
namespace WindowSystemTestbed
{
    public class UserDetailsDialog : Dialog
    {
    }
}

Next we can add a few fields to our new class.

private const int LargeSeparation = 10;
private const int SmallSeparation = 5;
private TextButton OKButton;
private TextButton cancelButton;
private TextBox nameTextBox;

public string Name
{
    get { return this.nameTextBox.Text; }
}

The constructor sets the control properties and adds them as child controls, as well as settings it's own properties.

public UserDetailsDialog(Game game, GUIManager guiManager)
    : base(game, guiManager)
{
    // Name label
    Label nameLabel = new Label(game, guiManager);
    Add(nameLabel);
    nameLabel.Text = "Name:";
    nameLabel.X = LargeSeperation;
    nameLabel.Y = LargeSeperation;
    nameLabel.Width = 75;
    nameLabel.Height = nameLabel.TextHeight;
 
    // Name textbox
    this.nameTextBox = new TextBox(game, guiManager);
    Add(this.nameTextBox);
    this.nameTextBox.Initialize();
    this.nameTextBox.X = nameLabel.X;
    this.nameTextBox.Y = nameLabel.Y + nameLabel.Height + SmallSeperation;
    // Set the window width to the default textbox width
 
    ClientWidth = nameTextBox.Width + (2 * LargeSeperation);
 
    // Cancel button
    this.cancelButton = new TextButton(game, guiManager);
    Add(this.cancelButton);
    this.cancelButton.Text = "Cancel";
    this.cancelButton.X = ClientWidth - this.cancelButton.Width - LargeSeperation;
    this.cancelButton.Y = this.nameTextBox.Y + this.nameTextBox.Height + LargeSeperation;
    this.cancelButton.Click += new ClickHandler(OnButtonClicked);
    // OK button
 
    this.OKButton = new TextButton(game, guiManager);
    Add(this.OKButton);
    this.OKButton.Text = "OK";
    this.OKButton.X = this.cancelButton.X - SmallSeperation - this.OKButton.Width;
    this.OKButton.Y = this.cancelButton.Y;
    this.OKButton.Click += new ClickHandler(OnButtonClicked);
 
    // Set the window height to the amount needed to show all controls
    ClientHeight = this.OKButton.Y + this.OKButton.Height + LargeSeperation;
 
    // Set the window title
    TitleText = "User Details";
 
    // This dialog does not need to be resized by the user
    Resizable = false;
    CenterWindow();
}
 
Note that I add child controls before setting their properties. This is because some controls don't become fully set up until they are initialised, which happens automatically when they are added to the GUI or another control. You could also just call Initialize() manually, but who needs the extra typing?
 
Also notice that control positions are set in relation to each other. I find this keeps the layout quite dynamic, especially for resizeable windows. I will consider providing layout managers in a future release, perhaps similar to those found in the Java Swing library.
 
The TextBox and TextButton controls don't have their Width or Height properties set. That's because some controls have useful default sizes, which allows some flexibility when modifying the default GUI settings.
 
Next we will add an event handler to the class, which will be called whenever a button is clicked. The buttons had this event handler added for their Click events in the constructor.
 
{{
protected void OnButtonClicked(UIComponent sender)
{
    if (sender == this.OKButton)
         SetDialogResult(DialogResult.OK);
 
    CloseWindow();}

Using The Dialog

private UserDetailsDialog dialog;

Next add an event handler that will be called when the user presses a key. In the constructor add the following code.

// Add a key down event handler
this.input.KeyDown += new KeyDownHandler(OnKeyDown);

Then create the event handler method.

private void OnKeyDown(KeyEventArgs args)
{
    if (args.Key == Keys.Enter)
    {
        // Only create a new dialog if one isn't already shown
        if (this.gui.GetModal() == null)
        {
            // Create and show dialog
            this.dialog = new UserDetailsDialog(this, this.gui);
            this.dialog.Close += new CloseHandler(OnDialogClosed);
            this.dialog.Show(true);
         }
    }
}

private void OnDialogClosed(UIComponent sender)
{
    if (sender == this.dialog)
    {
        if (this.dialog.DialogResult == DialogResult.OK)
        {
            MessageBox message = new MessageBox(
                this,
                this.gui,
                "Name: " + this.dialog.Name,
                "User Name",
                MessageBoxButtons.OK,
                MessageBoxType.Info
                );
                message.Show(true);
        }
 
        // Remove event handler so garbage collector will pick it up
        this.dialog.Close -= OnDialogClosed;
        this.dialog = null;
    }
}

// Show a message box informing the user how to use the program
MessageBox info = new MessageBox(
    this,
    this.gui,
    "Press enter to bring up the dialog.",
    "Info",
    MessageBoxButtons.OK,
    MessageBoxType.Info
    );
info.Show(true);

Conclusion

UPDATED WIKI: Tutorial 1

cdmac — Sun, 26 Aug 2007 15:30:32 GMT

Tutorial 1

This first tutorial will cover setting up a GUIManager object, adding new controls, and handling their events.

Setting Up The Project

Setting Up The GUIManager

The first thing to do is to add a couple using statements for the InputEventSystem and WindowSystem namespaces.

using System;
using Microsoft.Xna.Framework;
...
using InputEventSystem;
using WindowSystem;

Now add some fields.

private GraphicsDeviceManager graphics;
private InputEvents input;
private GUIManager gui;

public Tutorial1()
{
    this.graphics = new GraphicsDeviceManager(this);
    this.input = new InputEvents(this);
    Components.Add(this.input);
    this.gui = new GUIManager(this);
    Components.Add(this.gui);
    // GUI requires variable timing to function correctly
    IsFixedTimeStep = false;
    Window.Title = "Window System Tutorial 1";
}

The GUIManager object should be initialised in the overriden Initialize() method, before any child controls are added. This is so that order of resource loading can be predicted.

protected override void Initialize()
{
    // Has to be initialised before child controls can be added
    this.gui.Initialize();
    base.Initialize();
}

You will also want to override the Draw() method, to clear the screen each frame, although this probably doesn't affect the GUI as it handles drawing itself.

Adding Controls

private MenuBar menuBar;
private MenuItem newMenuItem;
private MenuItem openMenuItem;
private MenuItem saveMenuItem;
private MenuItem saveAsMenuItem;
private MenuItem exitMenuItem;
private MenuItem undoMenuItem;
private MenuItem redoMenuItem;

Next we have to actually set up the GUI objects, and add them to the GUI. This should take place in Initialize(), after the GUIManager has been initialised.

this.menuBar = new MenuBar(this, gui);
MenuItem fileMenu = new MenuItem(this, gui);
fileMenu.Text = "File";
this.newMenuItem = new MenuItem(this, gui);
this.newMenuItem.Text = "New...";
fileMenu.Add(this.newMenuItem);
this.openMenuItem = new MenuItem(this, gui);
this.openMenuItem.Text = "Open...";
fileMenu.Add(this.openMenuItem);
this.saveMenuItem = new MenuItem(this, gui);
this.saveMenuItem.Text = "Save";
this.saveMenuItem.IsEnabled = false;
fileMenu.Add(this.saveMenuItem);
this.saveAsMenuItem = new MenuItem(this, gui);
this.saveAsMenuItem.Text = "Save As...";
this.saveAsMenuItem.IsEnabled = false;
fileMenu.Add(this.saveAsMenuItem);
this.exitMenuItem = new MenuItem(this, gui);
this.exitMenuItem.Text = "Exit";
fileMenu.Add(this.exitMenuItem);
menuBar.Add(fileMenu);
MenuItem editMenu = new MenuItem(this, gui);
editMenu.Text = "Edit";
this.undoMenuItem = new MenuItem(this, gui);
this.undoMenuItem.Text = "Undo";
this.undoMenuItem.IsEnabled = false;
editMenu.Add(this.undoMenuItem);
this.redoMenuItem = new MenuItem(this, gui);
this.redoMenuItem.Text = "Redo";
this.redoMenuItem.IsEnabled = false;
editMenu.Add(this.redoMenuItem);
this.menuBar.Add(editMenu);
// Add menubar to gui
this.gui.Add(this.menuBar);

Control Events

// Add event handlers
this.newMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.openMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.exitMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.undoMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.redoMenuItem.Click += new ClickHandler(OnMenuItemClicked);

Finally we need to add a new method that is called whenever a menu item is clicked. We simply check which item was clicked, and act accordingly.

private void OnMenuItemClicked(UIComponent sender)
{
    if (sender == this.newMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "New clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.openMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Open clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.undoMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Undo clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.redoMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Redo clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.exitMenuItem)
        Exit();
}

Summary

UPDATED WIKI: Tutorials

cdmac — Sun, 26 Aug 2007 15:30:11 GMT

Tutorials

UPDATED WIKI: Tutorial 1

cdmac — Sun, 26 Aug 2007 15:27:13 GMT

Tutorial 1

This first tutorial will cover setting up a GUIManager object, adding new controls, and handling their events.

Setting Up The Project

Setting Up The GUIManager

The first thing to do is to add a couple using statements for the InputEventSystem and WindowSystem namespaces.

using System;
using Microsoft.Xna.Framework;
...
using InputEventSystem;
using WindowSystem;

Now add some fields.

private GraphicsDeviceManager graphics;
private InputEvents input;
private GUIManager gui;

public Tutorial1()
{
    this.graphics = new GraphicsDeviceManager(this);
    this.input = new InputEvents(this);
    Components.Add(this.input);
    this.gui = new GUIManager(this);
    Components.Add(this.gui);
    // GUI requires variable timing to function correctly
    IsFixedTimeStep = false;
    Window.Title = "Window System Tutorial 1";
}

The GUIManager object should be initialised in the overriden Initialize() method, before any child controls are added. This is so that order of resource loading can be predicted.

protected override void Initialize()
{
    // Has to be initialised before child controls can be added
    this.gui.Initialize();
    base.Initialize();
}

You will also want to override the Draw() method, to clear the screen each frame, although this probably doesn't affect the GUI as it handles drawing itself.

Adding Controls

private MenuBar menuBar;
private MenuItem newMenuItem;
private MenuItem openMenuItem;
private MenuItem saveMenuItem;
private MenuItem saveAsMenuItem;
private MenuItem exitMenuItem;
private MenuItem undoMenuItem;
private MenuItem redoMenuItem;

Next we have to actually set up the GUI objects, and add them to the GUI. This should take place in Initialize(), after the GUIManager has been initialised.

this.menuBar = new MenuBar(this, gui);
MenuItem fileMenu = new MenuItem(this, gui);
fileMenu.Text = "File";
this.newMenuItem = new MenuItem(this, gui);
this.newMenuItem.Text = "New...";
fileMenu.Add(this.newMenuItem);
this.openMenuItem = new MenuItem(this, gui);
this.openMenuItem.Text = "Open...";
fileMenu.Add(this.openMenuItem);
this.saveMenuItem = new MenuItem(this, gui);
this.saveMenuItem.Text = "Save";
this.saveMenuItem.IsEnabled = false;
fileMenu.Add(this.saveMenuItem);
this.saveAsMenuItem = new MenuItem(this, gui);
this.saveAsMenuItem.Text = "Save As...";
this.saveAsMenuItem.IsEnabled = false;
fileMenu.Add(this.saveAsMenuItem);
this.exitMenuItem = new MenuItem(this, gui);
this.exitMenuItem.Text = "Exit";
fileMenu.Add(this.exitMenuItem);
menuBar.Add(fileMenu);
MenuItem editMenu = new MenuItem(this, gui);
editMenu.Text = "Edit";
this.undoMenuItem = new MenuItem(this, gui);
this.undoMenuItem.Text = "Undo";
this.undoMenuItem.IsEnabled = false;
editMenu.Add(this.undoMenuItem);
this.redoMenuItem = new MenuItem(this, gui);
this.redoMenuItem.Text = "Redo";
this.redoMenuItem.IsEnabled = false;
editMenu.Add(this.redoMenuItem);
this.menuBar.Add(editMenu);
// Add menubar to gui
this.gui.Add(this.menuBar);

Control Events

// Add event handlers
this.newMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.openMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.exitMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.undoMenuItem.Click += new ClickHandler(OnMenuItemClicked);
this.redoMenuItem.Click += new ClickHandler(OnMenuItemClicked);

Finally we need to add a new method that is called whenever a menu item is clicked. We simply check which item was clicked, and act accordingly.

private void OnMenuItemClicked(UIComponent sender)
{
    if (sender == this.newMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "New clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.openMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Open clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.undoMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Undo clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.redoMenuItem)
    {
        MessageBox messageBox = new MessageBox(
            this,
            gui,
            "Redo clicked!",
            "Tutorial 1",
            MessageBoxButtons.OK,
            MessageBoxType.Info
        );
        messageBox.Show(true);
    }
    else if (sender == this.exitMenuItem)
        Exit();
}