Click here to Skip to main content
Click here to Skip to main content

WinForm ImageButton

, 16 Sep 2008
Rate this:
Please Sign up or sign in to vote.
WinForm .NET class for an image button allowing for regular, hover, and depressed images, and allows for text.

Introduction

ImageButton is a simple .NET class for a WinForm version of the web hover button, supporting an "idle" image, hover, and "down" image. It can be really useful when designing custom UIs in .NET.

Background

A general knowledge of overriding, inheriting, hiding, images, and attributes in .NET would be useful if you will be modifying the source. You'll need to know how to work with an image editor to create your buttons, or use a button generator off the web.

Using the Code

With Text in the Image

Before you start working with the code, you'll need to create a set of images - normal, hover, and down - all of which are optional, but all together combined make the best effect.

You'll create something like this:

Normal: ExampleButton.png
Hover: ExampleButtonHover.png
Down: ExampleButtonDown.png

Now add ImageButton.dll from bin/Release as a reference to your project, and drag the ImageButton control to your form. You will have a PictureBox-like control on your form.

Change the NormalImage, HoverImage, and DownImage properties in the Property window to match the created set of images.

Without Text in the Image

You can create an image set without text in it so you will be able to set the text using the VS designer. This means you won't need to create a separate image-set for every button.

Note: There is no word wrap in the text feature, you'll have to add line-breaks (vbCrLf in VB or \n in C#) to the text yourself.

First, create an image set without the button text inside; something like this:

Normal: ExampleButtonA.png
Hover: ExampleButtonHoverA.png
Down: ExampleButtonDownA.png

Then, like before, add the ImageButton control and set the image properties, but this time, set the Text property to the text you want to show, and the Font property to the font you want to use.

How It Works

To create the control, I created my ImageButton class, overriding the PictureBox control and implementing IButtonControl. Implementing IButtonControl will allow the ImageButton to be used, as any other button on the form, as a default button or a cancel button.

Mouse Methods

The concept is simple - we create an image and display it on screen. If the user hovers over the image, we swap the image to the hover image, and if the user holds his mouse down, we change the image to the depressed ("down") image.

So, for this purpose exists the following method overrides:

#region HoverImage
private Image m_HoverImage;
[Category("Appearance")]
[Description("Image to show when the button is hovered over.")]
public Image HoverImage
{
get { return m_HoverImage; }
set { m_HoverImage = value; if (hover) Image = value; }
}
#endregion
#region DownImage
private Image m_DownImage;
[Category("Appearance")]
[Description("Image to show when the button is depressed.")]
public Image DownImage
{
get { return m_DownImage; }
set { m_DownImage = value; if (down) Image = value; }
}
#endregion
#region NormalImage
private Image m_NormalImage;
[Category("Appearance")]
[Description("Image to show when the button is not in any other state.")]
public Image NormalImage
{
get { return m_NormalImage; }
set { m_NormalImage = value; if (!(hover || down)) Image = value; }
}
#endregion
        private bool hover = false;
        private bool down = false;
        protected override void OnMouseMove(MouseEventArgs e)
        {
            hover = true;
            if (down)
            {
                if ((m_DownImage != null) && (Image != m_DownImage))
                    Image = m_DownImage;
            }
            else
                if (m_HoverImage != null)
                    Image = m_HoverImage;
                else
                    Image = m_NormalImage;
            base.OnMouseMove(e);
        }

        protected override void OnMouseLeave(EventArgs e)
        {
            hover = false;
            Image = m_NormalImage;
            base.OnMouseLeave(e);
        }

        protected override void OnMouseDown(MouseEventArgs e)
        {
            base.Focus();
            down = true;
            if (m_DownImage != null)
                Image = m_DownImage;
            base.OnMouseDown(e);
        }

        protected override void OnMouseUp(MouseEventArgs e)
        {
            down = false;
            if (hover)
            {
                if (m_HoverImage != null)
                    Image = m_HoverImage;
            }
            else
                Image = m_NormalImage;
            base.OnMouseUp(e);
        }

Let's go over them:

OnMouseMove

protected override void OnMouseMove(MouseEventArgs e)
{
    hover = true;
    if (down)
    {
        if ((m_DownImage != null) && (Image != m_DownImage))
            Image = m_DownImage;
    }
    else
        if (m_HoverImage != null)
            Image = m_HoverImage;
        else
            Image = m_NormalImage;
    base.OnMouseMove(e);
}

OnMouseMove is called when the button is moving on the form. We avoided using OnMouseHover, because of the delay before the method is called.

We set the hover boolean to true for other methods to know when the mouse is hovering over the control. Then we check if the mouse button is down or not. If it is, we set the button image to the DownImage if the down image is not null and if the image is not already the down image.

If the mouse isn't being pressed, we check if a hover image exists - if it does, we set the image to the hover image, otherwise, we set it to the normal image.

On the last line, we call the Picturebox's version of OnMouseMove.

OnMouseLeave

protected override void OnMouseLeave(EventArgs e)
{
    hover = false;
    Image = m_NormalImage;
    base.OnMouseLeave(e);
}

This needs a little explanation. Smile | :) If the mouse has left the bounds of the control, we set a switch about if the mouse is hovering over the button or not to false, and set the image to the "normal" image. We let the PictureBox take the job from there.

OnMouseDown

protected override void OnMouseDown(MouseEventArgs e)
{
    base.Focus();
    down = true;
    if (m_DownImage != null)
        Image = m_DownImage;
    base.OnMouseDown(e);
}

If the mouse has pressed down on the control, we shift focus to the image button (this is not default behavior, so we must implement it) and set the down boolean to true. If the down image has been set by the designer, we change the image to the down image. Then we call the picturebox's own copy of OnMouseDown.

OnMouseUp

protected override void OnMouseUp(MouseEventArgs e)
{
    down = false;
    if (hover)
    {
        if (m_HoverImage != null)
            Image = m_HoverImage;
    }
    else
        Image = m_NormalImage;
    base.OnMouseUp(e);
}

The mouse button is no longer being pressed, so we set down to false. If we are hovering over the control and have let go, then we set the image to the hover image if it isn't nothing, otherwise, we set it to the "normal image". After that, we tell the PictureBox to keep going and handle OnMouseUp.

Null Values

As you may have noticed, we are checking if the hover and down images are null or not before we change the image, but when dealing with NormalImage, we don't. This is to prevent the hover/down images from sticking when the user isn't hovering or clicking on the control if the user didn't specify a normal image. In the demo application, this is demonstrated in Example F.

Text

The PictureBox control has Text and Font properties as required by the Control class, but they are not implemented and are hidden in the Property window. We can change this so that text is rendered:

[Browsable(true)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]
[Category("Appearance")]
[Description("The text associated with the control.")]
public override string Text
{
    get
    {
        return base.Text;
    }
    set
    {
        base.Text = value;
    }
}
[Browsable(true)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]
[Category("Appearance")]
[Description("The font used to display text in the control.")]
public override Font Font
{
    get
    {
        return base.Font;
    }
    set
    {
        base.Font = value;
    }
}
protected override void OnPaint(PaintEventArgs pe)
{
    base.OnPaint(pe);
    if ((!string.IsNullOrEmpty(Text)) && (pe != null) && (base.Font != null))
    {
        SolidBrush drawBrush = new SolidBrush(base.ForeColor);
        SizeF drawStringSize = pe.Graphics.MeasureString(base.Text, base.Font);
        PointF drawPoint;
        if (base.Image != null)
            drawPoint = new PointF(base.Image.Width / 2 - drawStringSize.Width / 2, 
		base.Image.Height / 2 - drawStringSize.Height / 2);
        else
            drawPoint = new PointF(base.Width / 2 - drawStringSize.Width / 2, 
		base.Height / 2 - drawStringSize.Height / 2);
        pe.Graphics.DrawString(base.Text, base.Font, drawBrush, drawPoint);
    }
}
protected override void OnTextChanged(EventArgs e)
{
    Refresh();
    base.OnTextChanged(e);
}

Overrides

The PictureBox hides the Text and Font properties from the Property window. To get around this, we create "dummy" overrides for the Text and Font properties which simply set the base class properties, but assign them the Browsable and DesignerSerializationVisibility attributes which will tell the Designer to "notice" these properties.

Painting

Since the PictureBox control from which we are inheriting does not render the text, we must add the code to paint the text on the button, in OnPaint. First we call the PictureBox base class method for OnPaint, which handles painting of the image and everything else. After that, we paint the text on top of the painted image in the middle, by measuring the size of the Text when in the selected Font, and comparing it to the size of the ImageButton, to find where to begin painting the text.

OnTextChanged

When the text of the control is changed, we must repaint the control. Therefore, we override the OnTextChanged method, and in it add the call to the Refresh method (which is inherited from PictureBox), which repaints the button.

Hiding Properties

There are some properties which are not as useful for the ImageButton as the PictureBox, and we want to hide them from the Property window. To do this, we do the opposite of what we did with the Text and Font properties, using the code below:

[Browsable(false)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public new Image Image { get { return base.Image; } set { base.Image = value; } }
[Browsable(false)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public new ImageLayout BackgroundImageLayout {
	get { return base.BackgroundImageLayout; }
	set { base.BackgroundImageLayout = value; } }
[Browsable(false)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public new Image BackgroundImage {
	get { return base.BackgroundImage; }
	set { base.BackgroundImage = value; } }
[Browsable(false)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public new String ImageLocation {
	get { return base.ImageLocation; }
	set { base.ImageLocation = value; } }
[Browsable(false)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public new Image ErrorImage {
	get { return base.ErrorImage; }
	set { base.ErrorImage = value; } }
[Browsable(false)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public new Image InitialImage {
	get { return base.InitialImage; }
	set { base.InitialImage = value; } }
[Browsable(false)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public new bool WaitOnLoad {
	get { return base.WaitOnLoad; }
	set { base.WaitOnLoad = value; } }

Description Changes

The SizeMode and BorderStyle properties mention PictureBox instead of ImageButton. To solve this, we simply use attributes and "dummy" properties to change the description of the properties with this code:

[Description("Controls how the ImageButton will handle
			image placement and control sizing.")]

public new PictureBoxSizeMode SizeMode {
	get { return base.SizeMode; }
	set { base.SizeMode = value; } }

[Description("Controls what type of border the ImageButton should have.")]

public new BorderStyle BorderStyle {
	get { return base.BorderStyle; }
	set { base.BorderStyle = value; } }

IButtonControl

We must also implement IButtonControl. This is simple to do, all we must do is implement the methods as such:

private bool isDefault = false;

        private bool isDefault = false;
        private DialogResult m_DialogResult;
        public DialogResult DialogResult
        {
            get
            {
                return m_DialogResult;
            }
            set
            {
                m_DialogResult = value;
            }
        }

        public void NotifyDefault(bool value)
        {
            isDefault = value;
        }

        public void PerformClick()
        {
            base.OnClick(EventArgs.Empty);
        }

Keyboard Methods

We must implement keyboard events so that the user can use the spacebar and the enter key to "click" the button, just like any other button on any other Windows form.

private const int WM_KEYDOWN = 0x0100;
private const int WM_KEYUP = 0x0101;
private bool holdingSpace = false;
public override bool PreProcessMessage(ref Message msg)
{
    if (msg.Msg == WM_KEYUP)
    {
        if (holdingSpace)
        {
            if ((int)msg.WParam == (int)Keys.Space)
            {
                OnMouseUp(null);
                PerformClick();
            }
            else if ((int)msg.WParam == (int)Keys.Escape
                || (int)msg.WParam == (int)Keys.Tab)
            {
                holdingSpace = false;
                OnMouseUp(null);
            }
        }
        return true;
    }
    else if (msg.Msg == WM_KEYDOWN)
    {
        if ((int)msg.WParam == (int)Keys.Space)
        {
            holdingSpace = true;
            OnMouseDown(null);
        }
        else if ((int)msg.WParam == (int)Keys.Enter)
        {
            PerformClick();
        }
        return true;
    }
    else
        return base.PreProcessMessage(ref msg);
}
protected override void OnLostFocus(EventArgs e)
{
    holdingSpace = false;
    OnMouseUp(null);
    base.OnLostFocus(e);
}

Simply put, we trap the message sent to the control if it is a key up or key down event. If it is, we check what key it is. If it's the enter key, we simply invoke a click event. If it's the spacebar, we hold the button down while it's being pressed until:

  1. the user lets go of the spacebar, in which case we perform a click, or 
  2. the user presses Escape, Tab, or the control loses focus, in which case we do not invoke the click event

If it is not the spacebar and it is not the enter key, we let the PictureBox base class method handle the message.

Demo Application

A demo application is included in the ZIP. Here's a screenshot:

imagebuttondemo.png

Enjoy!

License

This article, along with any associated source code and files, is licensed under The Creative Commons Attribution-ShareAlike 2.5 License

About the Author

Vartan Simonian

United States United States
The 13 year old programmer and composer

Comments and Discussions

 
Questionhere is click-shift update to your code. PinmemberSamoxin6-Apr-14 8:10 
GeneralMy vote of 5 Pinmembermauro7928-Sep-13 6:05 
GeneralMy vote of 5 PinmemberOrganicHuman20-Mar-11 5:32 
GeneralError Pinmemberdownhillchris9-Sep-09 21:06 
QuestionHow to wrap drawn text in a rectangle? PinmemberAlan Burkhart2-Jul-09 9:30 
GeneralMy vote of 1 PinmemberJunner200618-Jun-09 1:49 
GeneralRe: My vote of 1 PinmemberOrganicHuman3-Sep-11 6:07 
QuestionHow to wrap text in the control - code attached PinmemberSimon Steed (MadSi)22-Jan-09 0:24 
AnswerRe: How to wrap text in the control - code attached Pinmemberjackegg14-Jan-10 22:22 
GeneralI've written it too ;) PinmemberSiavash Mortazavi22-Sep-08 9:23 
GeneralRe: I've written it too ;) PinmemberVartan Simonian22-Sep-08 9:43 
QuestionCool - It is now part of the Toolbox! Pinmemberbranko.rieck10-Sep-08 22:15 
AnswerRe: Cool - It is now part of the Toolbox! PinmemberVartan Simonian11-Sep-08 11:31 
GeneralVery good PinmemberRoger Zhao9-Sep-08 22:06 
GeneralRe: Very good PinmemberVartan Simonian10-Sep-08 9:05 
Generalcool ! Pinmemberyassir hannoun8-Sep-08 9:48 
GeneralRe: cool ! PinmemberVartan Simonian9-Sep-08 1:46 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.140721.1 | Last Updated 16 Sep 2008
Article Copyright 2008 by Vartan Simonian
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid