BadCorporateLogo: Programming

Managed Designer Resources: The Restaurant Supply Store

Sun, 13 Jul 2008 02:26:54 GMT

Recently, I've been pretty swamped by work. Nights, weekends, holidays... I've been in the office so long, my wife has forgotten my name! This year, crunch time is like the playoffs - I'm not shaving and my beard is growing out. It's my first time with a beard, really. Honestly, it drives me nuts. I hate having food or drinks touch my my moustache and leave a lasting flavor. So besides working all the time, I'm also constantly wiping my mouth. Bleah!

Anyway, I've gotten a few messages from people asking for more about designers. Well, I still don't have time to put into writing. I did a couple weeks ago, but a hardware failure destroyed several hours of work and I didn't feel like starting again right away. Then I got too busy.

So instead of writing my own article on designers, I'm going to post a number of links where you can get information from the source: MSDN.

If I'd found the second link earlier, I probably wouldn't have written one of my posts since it covers the same stuff. I think I remember reading it several years ago, but I didn't find it when I looked again.

Here's a topic on developing components:

http://msdn.microsoft.com/en-us/library/51sc2s5c(VS.71).aspx

This specific sub-topic discusses design-time attributes:

http://msdn.microsoft.com/en-us/library/tk67c2t8(VS.71).aspx

That page links to the docs on customizing the design-time, which is what I'm writing about:

http://msdn.microsoft.com/en-us/library/37899azc(VS.71).aspx

The set of topics above actually provides a great deal of information and several samples. I think that's the best set of documentation for this kind of stuff.

After having posted these links, I'll try to focus on XNA Framework-specific customizations from now on. It'll probably be another week before my schedule is back to normal. After that, I'll be back to writing.

Making a Designer of Your Own - House Salad

Wed, 11 Jun 2008 06:36:47 GMT

Last time, I started to write about the managed designer infrastructure in Visual Studio. This infrastructure is all part of the .NET Framework's System.ComponentModel namespace, and so it naturally deals with components (things that implement System.ComponentModel.IComponent) as the base unit. The component model is meant to provide a generic framework for any kind of designer, but in Visual Studio it was implemented specifically to support Windows Forms and source code generation. It was later made more generic, with the intention of supporting any components, but there is still a lot of implementation that works only with Controls.

So what does the Control designer have to do with making a designer for XNA Framework game components? Nothing, except that in order to re-use the existing infrastructure, you'll need to know a bit about Control designers.

Combining all the ingredients available in the Component Model to create a visual programming experience for XNA game components takes a fair bit of background knowledge. As I said in my last post, you can't just look at my recipe for a Game State designer and know how to build your own Input designer. The bulk of the implementation isn't in my code - it's in the designer infrastructure. If you want to make your own dishes, you need to know what's in the pantry, and how to combine certain things to get the desired flavor.

Last time, I showed how any class deriving from Component will support a design view in Visual Studio. This design view is based on the concept of composition. You add objects to the class by dragging them from the Toolbox onto the design surface. Doing so results in a field being declared for the new object instance, and code to instantiate and initialize it. The designer lets you select and name objects on the design surface so that you can further edit them in the Properties Window. After making these changes, the entire design surface is serialized to code so that the composite class can be compiled and then re-created at runtime.

When you design a Control, the objects on the design surface are usually represented at design time by the same objects you'll use at runtime. So when you add a Button to the Form designer, a real Button instance is created on the design surface to represent the Button instance you'll get at runtime. When you change the Text property on the Button in the Properties Window, the text on the button changes on the design surface because you've actually changed the Text property of that Button instance.

You can change the BackColor and ForeColor properties for more visual evidence that the Properties Window is letting you edit the actual control instance on the design surface. At first glance, you might imagine that the Properties Window is using reflection to enumerate the properties of the selected object, get their values, and allow you to set them.

That makes sense and might even seem pretty obvious at first... But if you change the Visible property to false, suddenly things are not so obvious. The button is still visible on the design surface! (If you aren't sure what Visible is intended to do, you can run the project at this point to see that the button isn't visible at runtime.)

Figure 1 - Something invisible is revealed when you set the Visible property to false.

The reason the Button didn't disappear is because the Visible property in the Properties Window doesn't belong to the Button the way the Text, BackColor, and ForeColor properties do. Instead, it belongs to the Button's designer. :-)

At this point, things are undoubtedly going to get confusing. The term "designer" is overloaded, and I need to use it to mean something other than the visually-oriented composition editor we've been discussing until now.

Every component created on the design surface has a designer associated with it. The designer is another class that modifies the design-time appearance and behavior of the component. One role of the component designer is to filter or enhance an object's metadata. To put it another way, it can change the attributes on a component or its properties, and can remove, replace, or add properties. A designer can do this to change both the appearance and behavior of a control at design-time.

As an example, the Button's designer replaces the Visible property with a different property that comes from the designer instance. In designer-speak, this is called shadowing. In the Properties Window, the Visible property appears to belong to the Button, but in fact it belongs to the Button's designer. When you change the Visible property value, it's the designer's property that is changed (you don't see the effect because the designer was never visible in the first place). This prevents the Button instance from becoming invisible, which would make it hard to select or reposition it on the design surface.

If you look more closely at the properties of the Button instance, you'll notice there are a few listed that aren't actually properties of the Button class. To pick out just a few, in the Design category, you'll find "GenerateMember", "Locked", and "Modifiers". These control whether the instance will be declared as a field of the class or a local variable, whether the control can be moved or resized on the design surface, and the visibility modifier of the field declaration (if there is one), respectively. Changing these properties affects the code generated for the Button instance, but they don't represent actual properties of any object on the design surface.

A basic designer implementation is provided by System.ComponentModel.Design.ComponentDesigner. This class makes it easy to override just the parts you want to modify. As the documentation says, you associate a designer with a component through the DesignerAttribute.

Now, a word of caution when using the DesignerAttribute. Its constructor has overloads to use System.Type or System.String arguments to specify the designer's type. If you implement the designer in the same assembly as the component, you can use the System.Type constructor. However, if you implement the designer in a separate assembly, it is almost always a good idea to use the System.String constructor. The reason is that the designer is always given a reference to the component instance, and if you want the designer to be able to reference that component by its proper type, it will be dependent on the component's assembly. That precludes having a reference to the designer assembly from the component assembly, because then you have a circular dependency. So the way to avoid it is to allow you component to be ignorant of its designer, except for its name.

A very good reason to have the designer in a different assembly is because the designer will often depend on a bunch of assemblies that you don't ever need at runtime, or that maybe aren't redistributable. In fact, the designer class itself is not needed at runtime! So if you keep it in a separate assembly, then you can keep your runtime libraries lightweight and your redist small. Your customers will appreciate that!

I think I'll wrap it up here. Next time, I'll write more about how designers affect the behavior of controls on the design surface. At this point, it's also appropriate to start using code samples to illustrate, and I don't have anything ready right now.

Making a Designer of Your Own - A Starter Course

Tue, 03 Jun 2008 06:41:31 GMT

A couple people have e-mailed me recently about my "teaser" screen shots, because they want to know how I did it. As much as I'd like to explain the menu designer I'm working on, it's complicated. Writing long blog entries just isn't as interesting as writing code (for me, at least), so in all honesty, I'd rather work on the designer than try to explain what I'm doing. The easiest way to explain it is, I'm using the Windows Forms designer framework. It's reasonably well-documented, but not all in one place. You can't read it like a book.

Someone ~~demanded~~ asked me for my source code today because he wants to build his own designer. Source code isn't the place to start in this case. That would be like looking at a big turkey dinner I just prepared, and then asking me for the recipe because you want to grill a salmon. What you really want to know is how to cook.

For that reason, I'm not going to share my recipe -- not yet, at least. Instead, I'll try to focus on explaining how to cook. Let's start with an appetizer, and work our way up to the entree.

In Visual Studio, there is already an extensible designer infrastructure for components (types that implement System.ComponentModel.IComponent). This infrastructure has further specialization to support Components (types that derive from System.ComponentModel.Component) and Controls (types that derive from System.Windows.Forms.Control). Note that the general infrastructure is for the IComponent interface, while there is extra stuff for the Component class, which is a default implementation of the IComponent interface. There is even more extra stuff for Controls and various specialized subclasses, like Form.

The extra stuff is the interesting part. Windows Forms has an editor registered in Visual Studio that will handle any code file in a code project that contains a class declaration for a class that derives from Component. The IDE determines this by asking the language service (the thing that gives you Intellisense) for the first class declaration in a code file. Then it uses another service (probably ITypeResolutionService, but I forget, and it doesn't matter enough to check), to determine whether the base class of the type declaration derives from Component. If so, then the file is treated as a "component" file.

Let's take a look at an example.

Figure 1 shows a regular Class Library project in VC# Express. Look what happens when I edit the declaration for Class1 to derive from Component.

Figure 2 shows the subtle change. In the Solution Explorer, the icon next to the Class1.cs file is the "component file" icon. Even though the file is already open in the code editor, now when you double-click on the file in Solution Explorer, it will open the Component Designer.

Figure 3 shows the Class1 class in the the Component Designer.

The Component Designer provides a basic, visual code editing experience. You can drag and drop components onto the Class1 design view from the Toolbox, and edit those objects in the Properties Window. The changes you make will be serialized to code in a method called InitializeComponent in the Class1 class declaration.

After some experimentation, an observant person will note several things. First, the generated code appears in InitializeComponent, but that function is never called. This is because the designer generally ignores everything else in the class except that function. The standard practice is to define a default constructor that calls InitializeComponent. Since Class1 was not created from a Component template, I'll need to add that code myself.

Second, the name of Class1 in the Properties Window refers to the name of the type Class1. Every other component dropped onto the design surface has a name that refers to the name of the member variable that the component is assigned to.

Third, the properties in the Properties Window aren't the properties of Class1. If you add a new property to the class definition in Class1.cs, it won't appear in the Properties Window at all.

For example, let's add a string property to Class1.

    public class Class1 : Component
    {
        private string myProperty;

        public string MyProperty
        {
            get { return myProperty; }
            set { myProperty = value; }
        }
    }

Going back to the design view, MyProperty is nowhere to be seen. If you look closely at the Properties Window, you'll see the reason why. It shows Class1 to be an instance of System.ComponentModel.Component. This is important -- the designer creates an instance of the component's base class at design time. The same goes for editing Forms or Controls.

This only applies to the root component, however -- the type being designed -- and not for components that are dragged onto the design surface. Part of the reason for this is because you are changing the source code for the type as you edit it in the designer -- making it difficult to keep a compiled instance of the type-being-edited up to date with the latest changes.

Now that you know the designer creates an instance of the base type instead of the actual type, you might already have guessed what I will do next. I'm going to add another class to the project in its own file, Class2.cs, and declare a new class Class2 that derives from Class1.

Now, as long as I've compiled the project first, I can double-click on Class2.cs and have it open up in the designer. This happens because Class2 derives from Component. Except this time, the instance on the design surface is an instance of Class1! See how the Properties Window shows MyProperty?

Figure 4 shows that you can design your own types in the Component Designer.

Getting your own class into the Component Designer is the first step. Now it's time to customize!

There are a lot of ways to customize the design-time experience for particular components. Most of it is driven through metadata, or custom attributes.

For example, using attributes, I can change the way MyProperty appears in the Properties Window.

    public class Class1 : Component
    {
        private string myProperty = "elephant";

        [DefaultValue("elephant")]
        [Category("Animals")]
        [DisplayName("My Property")]
        [Description("Set this property to the first thing that comes to mind.")]
        public string MyProperty
        {
            get { return myProperty; }
            set { myProperty = value; }
        }
    }

After rebuilding the project, the Properties Window for Class2 reflects the changes.

Figure 5 provides an example of how you can customize the design-time behavior of your components. The MyProperty property is now displayed as My Property (note the space), it is in the Animals category instead of Misc, and it has a description at the bottom of the Properties Window. The value of the property is "elephant", which is the default value. This is important to the designer because when a property has its default value, it is not serialized to code. Imagine having a component with two hundred properties, and all but one is set to its default value (the value it has when constructed from a default constructor). You would want the code generated for that component to only set the one property that was different from its default, not all 200 values. Otherwise, such a class would initialize 199 of its properties twice!

It's important to note here that the DefaultValueAttribute custom attribute is used as a hint to the designer, and doesn't actually set the property to anything. It's purpose is to tell the designer what the default value is, so the designer can compare the property's actual value against it when it's time to generate code. The Properties Window also uses it to visually indicate which properties need to be serialized -- that is, if a property's value is anything but the default, then that value will appear in bold in the Properties Window. If you specify the wrong value in the attribute, the designer will behave incorrectly -- so be careful!

There are a bunch of attributes in System.ComponentModel that are interesting. A few noteworthy attributes in terms of editing properties are:

BrowsableAttribute -- use Browsable(false) to prevent a property from appearing in the Properties Window.
DesignerSerializationVisibilityAttribute -- choose not to generate code for a property (often used in combination with Browsable(false)), or serialize only the object returned by the property (like a read-only property that returns an editable collection).
ReadOnlyAttribute -- make a read/write property appear read-only in the Properties Window.
TypeConverterAttribute -- allows you to specify a custom type converter (hint: this is where you can do neat stuff!). Usually, you want to convert between a custom type and its string representation. This way, your custom type can both be displayed in the Properties Windows, and be edited by a user typing in a new value.
EditorAttribute -- allows you to specify a custom editor for the property (hint: this is another place to do neat stuff!). By creating a custom UITypeEditor, you can make rich design-time experiences for your properties, like the color picker for System.Drawing.Color properties on Control classes.

In my menu designer, I've been getting a lot of mileage out of creating custom type converters. I created one to enumerate all types that derive from GameScreen to assign to a System.Type property, I created one to enumerate the names of all SpriteFonts in the nested Content project to assign to a string property, and I created another to enumerate the names of all Texture2D content to assign to another string property.

Okay, that's as far as I'm going to get in one sitting. Our starter course is looking pretty modest -- more like cheese and crackers than shrimp cocktail -- but at least there's something on the plate!

Going Somewhere? Menu Navigation Woes.

Tue, 20 May 2008 08:37:40 GMT

There have been about a billion views of my blog since I posted screen shots of the menu designer I started working on last week. For those of you who are keenly interested in that particular topic, I am still working on it. I mean you, Eli! ;-)

Getting a design surface going took some technical trickery, but I've done it before so it was no big deal. The real difficult part is making a set of classes that are intuitively designable. What does that mean? Well, I guess I'm trying to figure out the right set of classes to support, the right properties to put on all the classes, and the right set of toolbox items to have available. I want something that is both simple enough to get people started right away, and easy enough to customize that not every game looks like it came from the same designer.

I've been building this designer and its components in Visual C# 2005 Express Edition. A few of you might be surprised at that, mainly because you can't use the VS SDK to build customizations for VC# Express (except for some very special cases like XNA Game Studio, but my personal projects are no exception). The fact is, a visual designer doesn't require customizations to the IDE. There's already a powerful designer infrastructure built-in to VC# Express -- the very same one used by Windows Forms! To create custom design-time experiences, you don't need to modify anything in the IDE. All you need is the right metadata on your classes, and you can take control of that infrastructure for yourself.

Anyway, tonight I am trying to make sense of the mess I made with respect to navigation items. I've created an item that you can drop onto the menu and then specify what type of screen it navigates to. Selecting this menu item when the menu is running will transition to the next screen. I also gave it the option of specifying a custom background for the next screen, and for loading it on a separate thread with a load screen. The trouble is that if you use the load screen, you can't "cancel" back to the previous screen. If you don't use it, then you can. I'm having trouble figuring out what to call the properties so the resulting behavior will be obvious.

Clearly, this one navigation item is too complex. The best thing to do is probably to have more than one navigation item -- say, one that pushes new screens onto the screen manager's stack (allowing back-button navigation), and another that clears the stack to start from scratch (like a gameplay or level screen). That would definitely be easier to understand, but what do I call them? Argh!

The thing I like about the navigation items is that it gives you an easy way to build a complex menu system without writing any code.

This screen clipping above shows how the NextScreen property has a dropdown combobox to select the type of the next screen. The combobox will list all the game screens in your project (or referenced by it). It's neat and easy, but the resulting behavior is not yet intuitive.

Coming up with good names is hard. It reminds me of a quote from Knuth:

The most important thing in the programming language is the name. A language will not succeed without a good name. I have recently invented a very good name and now I am looking for a suitable language.
Donald Knuth

Once again, it's time for bed.