SUMMARY
This step-by-step article describes how to add a 16-by-16-pixel custom Toolbox icon to a Windows Forms control.
You can add a custom Toolbox icon to a Windows Forms control in the following three ways:
- Include the control and the image with your application as separate files.
- Use an image from a system control.
- Include the image as part of the assembly.
NOTE: If you want to distribute the image files, you must select a location based on how you want to deploy your control. If you want to deploy the control and the image in two separate files, you should save the image to a location that can be found in all operating systems. If you distribute the image as a resource in the assembly, this is not necessary.
back to the top
Create a New Image or Icon
The first step is to choose an icon to use for your control. You can add an existing icon to your project, or create the icon by using an editor.
To create a new icon, follow these steps:
- On the File menu, click New, and then click File.
- On the New File menu, select either Bitmap or Icon.
Note In Visual Studio 2005, click Bitmap File or Icon File. - Draw the image on the Visual Studio .NET Image Editor.
- Save the image.
back to the top
Add the Icon to the Control
To add the icon to the control, you can deploy the control and the image file as separate files, use an image from a system control, or include the image as part of the assembly.
back to the top
Deploy the Control and the Image File as Separate Files
This method does not include the image as a part of the assembly. The disadvantage of this method is that you are required to deploy the image with the control, and the image must be in the same location on both the destination computer and the development computer.
The signature of the
ToolboxBitmapAttribute constructor that is associated with this method is as follows:
[Visual Basic]
<AttributeUsage(AttributeTargets.Class)>
Public Sub New( _
ByVal imageFile As String _
)
NOTE: The
imageFile string should contain the full path of the file that you want to use as the icon with the control.
NOTE: The
ToolboxBitmapAttribute constructor does not have to contain the word
Attribute. It can be accessed as
ToolboxBitmap.
You can use the following code sample to set the
ToolboxBitmapAttribute constructor in your code:
<ToolboxBitmap("c:\MyIcon.bmp")> _
Public Class MyUserControl
Inherits System.Windows.Forms.UserControl
' Generate code.
' Code for the control.
End Class
In this example, the system looks for the Myicon.bmp file in the root folder as the control is loaded. If the file is not found, an error is generated and the control fails to load.
back to the top
Use an Image from a System Control
The control can also use a default image from a system control such as a
Button control (for example,
System.Windows.Forms.Button). In this case,
ToolboxBitmapAttribute requires a
System.Type parameter of the control image to be used with your control.
[Visual Basic]
<AttributeUsage(AttributeTargets.Class)>
Public Sub New( _
ByVal t As Type _
)
The following code demonstrates usage of the Toolbox icon using the
System.Windows.Forms.Button type.
<ToolboxBitmap(GetType(Button)> _
Public Class MyUserControl
Inherits System.Windows.Forms.UserControl
' Generate code.
' Code for your control.
End Class
This example causes the Control to use the same Toolbox icon that is associated with a
Button control.
back to the top
Include the Image as a Part of the Assembly
To use your image with the control, you must add the image file as a part of your project. To do this, follow these steps:
- In Visual Basic. NET or in Visual Basic 2005, open Solution Explorer.
- Right-click the name of the project to which you want to add your image, click Add, and then click Add Existing Item.
- In the Add Existing Item dialog box, change File Type to All Files or Image Files.
- Select the file that you want to use, and then click Open. You can now see the image file as a part of your project in Solution Explorer.
Note In Visual Studio 2005, click Add instead of Open. - In Solution Explorer, right-click your image file, click Properties, and then expand Advanced.
- Under Advanced, locate the Build Action property for the image. By default, this is set to Content. Click Content, and then select Embedded Resource. This includes the image as a resource in your assembly when the project is compiled.
- Access the image.
To access an image that is distributed as a part of the assembly, you can either deploy the icon as an embedded resource or access the icon as a resource.
- Deploy the Icon as an Embedded Resource
The signature of the ToolboxBitmapAttribute constructor that is associated with this method is as follows:
[Visual Basic]
<AttributeUsage(AttributeTargets.Class)>
Public Sub New( _
ByVal imageFile As String _
)
The constructor that is used in this method is the constructor that was used in the example in which an image from System.Control was used. This constructor takes its parameter as a type. The type that is used in this method is the class to which the ToolboxBitmap attribute is applied.
You must give the image the same name as the base class. You can use either of the following methods to change the name of an image in the project:
- In Solution Explorer, right-click the image name, select Rename, and then type the new name of the image.
-or-
- In the image properties, locate the File Name property. Click the name, type the new name of the file, and then press ENTER.NOTE: Be sure that you do not change the file name extension.
The following code demonstrates how to deploy the Toolbox icon as an embedded resource with the assembly. In this sample code, the file that is associated with the example is part of the project, and it is named Myusercontrol.bmp.
<ToolboxBitmap(GetType(MyUserControl)> _
Public Class MyUserControl
Inherits System.Windows.Forms.UserControl
' Generate code.
' Code for your control.
End Class
- Access the Icon as a Resource
You can use this method when the image has a different name than the class that uses it. To access the image as a resource, use the following constructor for ToolboxBitmapAttribute:
[Visual Basic]
<AttributeUsage(AttributeTargets.Class)>
Public Sub New( _
ByVal t As Type, _
ByVal name As String _
)
The ToolboxBitmapAttribute constructor requires two parameters: a System.Type parameter and the name of the resource to be accessed. You can obtain the type with the namespace of your project and the class that is used to declared the control. If you do not know the root namespace of your project, follow these steps to find it:
- Right-click the project and then click Properties.
- Click Common Properties, and then click General. The name of the namespace is located under Root Namespace on the right side of the dialog box.
As the first parameter for ToolboxBitmapAttribute, use this namespace with the class name that implements the control in the GetType function. The second parameter (string) should contain the name of the resource that you want to use with this control, including the file name extension. The following code demonstrates this usage of the constructor.
<ToolboxBitmap(GetType(MyNameSpace.MyUserControl),"MyIcon.bmp")> _
Public Class MyUserControl
Inherits System.Windows.Forms.UserControl
' Generate code
' Code for your control.
End Class
NOTE: When you pass GetType(MyNameSpace.MyUserControl) and "MyIcon.bmp" as parameters, the system is forced to look for a resource named MyNameSpace.MyIcon.bmp in the compiled assembly.
back to the top
Troubleshooting
If you encounter errors, verify the following:
- If the control and the image file are deployed separately, ensure that the image name and the path of the file are correct.
- If the image is deployed as part of the assembly as an embedded resource, ensure that only the file name is defined in the second parameter, that the file name is correct, that the correct file name extension is present, and that the file name is enclosed with quotation marks (for example, "filename.file_extension").
- If you deploy the icon as an embedded resource, ensure that Build Action is set to Embedded Resource.
- If you deploy the icon as an embedded resource, ensure that the root namespace and class are correct and that they are passed to constructor with the GetType function.
back to the top