This chapter is from the book
This chapter is from the book
This chapter is from the book
Creating Custom Control Properties
Adding properties to a custom control is the same method used to add properties to any other managed class. In the ShapeControl project, open the ShapeControl.h file. Within the public section of the ShapeControl class, you will create a property using the __property keyword. As you'll recall from other hours within this book, such as Hour 17, "Interfaces," each property can have a getter and setter function. Because you want clients using the control to both retrieve the current shape and set the current shape of your control, you will be creating both.
The property you will be creating, however, will be a String object. If you were to create a property to a Shape enumerated data type, then when the person using your control changes that property within the Property Browser, he will either see the number 0 or the number 1, rather than the string "Rectangle" or "Ellipse." Create a property named DrawShape with both a get and set function using the __property keyword, as shown starting on line 51 of Listing 23.3. Within the get_DrawShape function, return either the string "Rectangle" or the string "Ellipse," based on the current value of your private Shape enumerated data type. Within the set_DrawShape property function, do the reverse by changing the value of the private enumerated data variable based on the value received as a parameter to the property function. Also, because setting this property means that the shape of your control needs to change, call the Invalidate function so that PaintHandler is invoked, which in turn redraws your control using the proper shape.
As mentioned earlier, simply adding a public property to your control ensures that a person using your control can change that property using the Property Browser within the IDE. Currently, however, the user must manually type in the strings to change the property. You will now learn how to change the field within the Property Browser for your property so that rather than having to manually type in a string for the property, you can select a shape from a drop-down list.
You can specify how the value of a property is displayed within the Property Browser using three different methods. The first, which has already been mentioned, is to just add a property requiring the user to manually enter in the value. The second method is to associate your control with a TypeConverter, which will create a drop-down list with the possible values available to choose from. The third way is to associate your control with a UITypeEditor object. This allows you to create any type of control that is shown when the user clicks in the property field. For example, you could create a drop-down list that graphically shows a rectangle and an ellipse rather than just the strings. (Note that you interacted with a property that used a UITypeEditor when you changed the various color properties earlier.)
For this lesson, you will be using the second method, which uses a TypeConverter. Within the ShapeControl class, create another managed class before the ShapeControl class named ShapeConverter. Because the property uses String objects as its property, derive from the StringConverter base class, as shown in Listing 23.3. In order to avoid any forward declaration issues and class dependencies, you will declare the class at the top of the project file and implement the functions following the ShapeControl class.
The StringConverter class contains three virtual functions that you will need to override to control the behavior of the drop-down box. The first function, named GetStandardValuesSupported, is called to determine whether your control contains a set of standard values that a user can choose from. Because your control supports two standard values, simply return True from this function, as shown on line 100 of Listing 23.3. The second function, named GetStandardValuesExclusive, is used to determine whether the standard values of your control are the only values possible. Because they are the only values supported (in other words, the user cannot manually enter any other value for the property), the function returns True, as shown on line 106 of Listing 23.3. Finally, the last function that the ShapeConverter class will override from the StringConverter base class is the method used to retrieve the collection of standard values displayed in the drop-down list. To do this, create an array of String objects and return a new instance of a StandardValuesCollection using the array of String objects you just created as a parameter to the constructor dynamically cast to an ICollection interface, as shown on line 118 of Listing 23.3. In order to use the functions you just overwrote, you will have to reference three additional namespaces. These three namespaces can be seen starting on line 12 of Listing 23.3.
Listing 23.3 Creating a Custom Control and Controlling Its Appearance in the Property Browser
1: // ShapeControl.h
2:
3: #pragma once
4:
5: #using <System.dll>
6: #using <System.Drawing.dll>
7: #using <System.Windows.Forms.dll>
8:
9: using namespace System;
10: using namespace System::Drawing;
11: using namespace System::Windows::Forms;
12: using namespace System::Drawing::Design;
13: using namespace System::ComponentModel;
14: using namespace System::Collections;
15:
16: namespace ShapeControl
17: {
18: public __gc class ShapeConverter : public StringConverter
19: {
20: public:
21:
22: // StringConverter Overrides
23: bool GetStandardValuesSupported( ITypeDescriptorContext* context);
24: bool GetStandardValuesExclusive( ITypeDescriptorContext* context);
25: TypeConverter::StandardValuesCollection*
26: GetStandardValues( ITypeDescriptorContext* context);
26: };
27:
28: public __gc class ShapeControl :
29: public System::Windows::Forms::UserControl
30: {
31: public:
32:
33: ShapeControl()
34: {
35: InitializeControl();
36: SetStyle(ControlStyles::ResizeRedraw, true);
37: }
38:
39: __value enum Shape
40: {
41: Rectangle = 0,
42: Ellipse = 1
43: };
44:
45: [
46: TypeConverter(__typeof(ShapeConverter)),
47: Category("Appearance"),
48: Description("Sets the shape for the control"),
49: DefaultValue("Rectangle"),
50: ]
51: __property String* get_DrawShape()
52: {
53: if( m_eDrawShape == Shape::Rectangle )
54: return S"Rectangle";
55: else if( m_eDrawShape == Shape::Ellipse )
56: return S"Ellipse";
57:
58: return 0;
59: }
60:
61: __property void set_DrawShape( String* Value )
62: {
63: if( Value == S"Rectangle" )
64: m_eDrawShape = Shape::Rectangle;
65: else if( Value == S"Ellipse" )
66: m_eDrawShape = Shape::Ellipse;
67:
68: Invalidate();
69: }
70:
71: protected:
72: void PaintHandler( Object* sender, PaintEventArgs* e )
73: {
74: System::Drawing::Rectangle rcRect = ClientRectangle;
75:
76: // deflate rect so circle isn't cut off
77: rcRect.Inflate( -5, -5 );
78:
79: // Draw the rectangle or circle
80: if( m_eDrawShape == Shape::Rectangle )
81: e->Graphics->DrawRectangle(
82: new Pen(this->ForeColor, 1), rcRect );
83:
84: else if( m_eDrawShape == Shape::Ellipse )
85: e->Graphics->DrawEllipse(
86: new Pen(this->ForeColor, 1), rcRect );
87 : }
88:
89: private:
90: Shape m_eDrawShape;
91:
92: void InitializeControl()
93: {
94: m_eDrawShape = Shape::Rectangle;
95:
96: add_Paint( new PaintEventHandler(this, PaintHandler ));
97: }
98: };
99:
100: bool ShapeConverter::GetStandardValuesSupported(
101 ITypeDescriptorContext* context)
102: {
103: return true;
104: }
105:
106: bool ShapeConverter::GetStandardValuesExclusive(
107: ITypeDescriptorContext* context)
108: {
109: return true;
110: }
111:
112: TypeConverter::StandardValuesCollection*
113: ShapeConverter::GetStandardValues(
114: ITypeDescriptorContext* context)
115: {
116: String* pShapes? = { S"Rectangle", S"Ellipse" };
117:
118: return new StandardValuesCollection(
119: dynamic_cast<ICollection*>(pShapes) );
120: }
121: }
The last step before you can view the drop-down list in the Property Browser is to associate your ShapeConverter class with the DrawShape property contained within the ShapeControl. Changing how the property is displayed within the Property Browser is accomplished by applying attributes to the property. To associate the ShapeConverter with the property, use the TypeConverter attribute with the parameter __typeof(ShapeConverter), as shown on line 46 of Listing 23.3. The final three attributes you see within the listing control various property attributes that the Property Browser uses to display the property. The Category attribute is used to place your property in the associated category within the Property Browser. Because the DrawShape property affects the appearance of the control, place that property within the Appearance category. The next attribute, Description, simple displays a description of what the property is used for. Finally, the DefaultValue attribute specifies what the initial value for the property should be.
You can now compile your control. If you receive an error when linking your project that states that the linker cannot open the file, this is due to something I mentioned earlier when you created your Visual C# project. If you receive this error, it means your project is open and you are currently using the Windows Form Designer. Because the ShapeControl is in use, the linker cannot update your DLL. However, simply closing the Windows Form Designer does not fix this problem. You must close the Visual Studio .NET instance containing the Visual C# .NET project before updating your control. The fact that Visual C++ .NET does not contain a Windows Form Designer is actually a blessing in this case, because you can still keep that project open as you work on your custom control. Close the Visual Studio .NET windows containing the C# project and rebuild your control.
After your control is built, start a new instance of Visual Studio .NET and open the C# project you created to test your control. Open the main Windows Form and select the ShapeControl contained on the form by clicking it. If you look in the Property Browser window now, you will see the DrawShape property with the word Rectangle as its value. Clicking that value will display a down-arrow button. When you click that button, you will see the drop-down list containing the two possible values to select from, as shown in Figure 23.11.
){kind=link}
Figure 23.11 Creating a drop-down list in the Property Browser for your custom control.