The <asp:ImageButton> control displays an image that responds to mouse clicks like a button. That is, the control responds to click and command events to call subprograms. The general format for this control is shown below.

<asp:ImageButton id="id" Runat="Server"
  AlternateText="string"
  CommandName="command"
  CommandArgument="argument"
  ImageAlign="Bottom|Left|Middle|Right|Top|TextTop
                     AbsBottom|AbsMiddle|AbsBaseLine|NotSet"
  ImageUrl="url"
  PostBackUrl="url"
    property="value"...

    OnClick="subprogram"
    OnCommand="subprogram"
/>

The URL of the image is given in the ImageUrl property, and alternate text is specified in the AlternateText property. Text alignment around an in-line image is on the Bottom of the image unless a different ImageAlign property is specified.

By coding the OnClick event handler the image responds to a mouse click and calls a subprogram. Like an <asp:Button> or <asp:LinkButton> control, an ImageButton supplies OnCommand, CommandName, and CommandArgument properties. These properties can be employed when more than one ImageButton calls the same subprogram and a way is needed to identify the image that is clicked. PostBackUrl posts to a different page from the current page.

Calling a Subprogram

The following ImageButton operates like a standard button. Its OnClick event handler calls a subprogram which assigns a text string to the accompanying Label control.

<SCRIPT Runat="Server">

Sub Image_Click (Src As Object, Args As ImageClickEventArgs)

  Message.Text = "The Image_Click subprogram was run."

End Sub

</SCRIPT>

<form Runat="Server">

<asp:ImageButton OnClick="Image_Click" Runat="Server"
  ImageUrl="F0.gif"
  AlternateText="Call Subprogram
  ImageAlign="AbsMiddle"/>

<asp:Label id="Message" Runat="Server"/>

</form>

A subprogram called by a ImageButton has a different signature from a regular button. Notice use of the ImageClickEventArgs argument. This argument type must be used when an ImageButton calls a subprogram through an OnClick event handler.

Scripting Command Images

An ImageButton control can be configured as a command button so that a single script that services multiple images can determine which one was clicked and take appropriate action on the chosen image. A command image uses an OnCommand event handler and supplies CommandName and CommandArgument properties to pass its processing request. In the following example, five ImageButtons call the same subprogram which reports the clicked button.

<SCRIPT Runat="Server">

Sub Choose_Image (Src As Object, Args As CommandEventArgs)

  Message.Text = "You clicked the " & Args.CommandName &  " button."
  Src.ImageUrl = Args.CommandName & "Shaded.gif"

End Sub

</SCRIPT>

<form Runat="Server">

<asp:ImageButton  Runat="Server"
  OnCommand="Choose_Image"
  CommandName="F1"
  ImageUrl="F1.gif"
  ImageAlign="AbsMiddle"
  EnableViewState="False"/>

<asp:ImageButton Runat="Server"
  OnCommand="Choose_Image"
  CommandName="F2"
  ImageUrl="F2.gif"
  ImageAlign="AbsMiddle"
  EnableViewState="False"/>

<asp:ImageButton Runat="Server"
  OnCommand="Choose_Image"
  CommandName="F3"
  ImageUrl="F3.gif"
  ImageAlign="AbsMiddle"
  EnableViewState="False"/>

<asp:ImageButton Runat="Server"
  OnCommand="Choose_Image"
  CommandName="F4"
  ImageUrl="F4.gif"
  ImageAlign="AbsMiddle"
  EnableViewState="False"/>

<asp:ImageButton Runat="Server"
  OnCommand="Choose_Image"
  CommandName="F5"
  ImageUrl="F5.gif"
  ImageAlign="AbsMiddle"
  EnableViewState="False"/>

<asp:Label id="Message" Runat="Server"/>

</form>

When using OnCommand to call a subprogram with an ImageButton, a CommandEventArgs argument must be used in the subprogram's signature. Note that this is a different signature from one called with an OnClick event handler using the ImageClickEventArgs argument.

The original images are named F1.gif, F2.gif, F3.gif, and so forth. The replacement images are named F1Shaded.gif, F2Shaded.gif, F3Shaded.gif, in parallel with the original names. The Args.CommandName argument supplies the strings "F1", "F2", "F3", etc. as command identifiers. Therefore, the name of the replacement image is given by appending "Shaded.gif" to the passed CommandName.

The above ImageButtons must be assigned EnableViewState="False" so that replacement images are not redisplayed on postbacks of the page; that is, assignment of a shaded image should not be retained in View State when the page is reloaded. An ImageButton reverts to its original image when any of the images are clicked.

If necessary, the CommandArgument property can be added to an ImageButton to provide addition information about the processing to perform. The reference Args.CommandArgument is tested for this passed value, which is not required in the above example.

Passing Coordinates

It is possible to test the x and y coordinates of a click on an ImageButton. These horizontal and vertical coordinates are relative to the top-left corner of the image. Coordinate testing can be done, for instance, to implement a simple image map where the location of the mouse click on the image determines the subprogram to call. Outlines of clickable areas on the ImageButton cannot be of complex shapes as they can with standard XHTML image maps. You are limited to testing coordinates within rectangular areas.

When using an ImageButton as an image map, the signature of the called subprogram must include the ImageClickEventArgs argument to match the image's OnClick event handler. The x coordinate of the mouse click is given by argument.x and the y coordinate is given by argument.y as demonstrated in the following code.

<SCRIPT Runat="Server">

Sub Show_Coordinates (Source As Object, Args As ImageClickEventArgs)

  Coordinates.Text = "Image clicked at coordinates: " & _
                     "X = " & Args.x & " and Y = " & Args.y

End Sub

</SCRIPT>

<form Runat="Server">

<asp:ImageButton Runat="Server"
  OnClick="Show_Coordinates"
  ImageUrl="aspnet2.gif"
  AlternateText="Click me to get coordinates"
  ImageAlign="AbsMiddle"/>

<asp:Label id="Coordinates" Runat="Server"/>

</form>

An ImageButton cannot be configured as a normal image map that links to different pages; it does not have Navigate.Url or Target properties necessary for page links. An ImageButton can only detect mouse clicks in order to call subprograms. It is an alternative to using multiple command images, in this case where different coordinates of a single image are used in place of different CommandNames passed by different images.

In the following example, a single image calls two different subprograms depending on where the image is clicked. If the click is on the left-half of the image, then Subprogram_1 is called; if the click is on the right-half of the image, then Subprogram_2 is called.

<SCRIPT Runat="Server">

Sub Run_Subprogram (Source As Object, Args As ImageClickEventArgs)
  If Args.x < 85 Then
    Subprogram_1
  ElseIf Args.x < 170 Then
    Subprogram_2
  End If
End Sub

Sub Subprogram_1
  WhichSubprogram.Text = "This is Subprogram_1"
End Sub

Sub Subprogram_2
  WhichSubprogram.Text = "This is Subprogram_2"
End Sub

</SCRIPT>

<form Runat="Server">

<asp:ImageButton id="TheImage" Runat="Server"
  ImageURL="aspnet2.gif"
  AlternateText="Click to run subprogram"
  ImageAlign="AbsMiddle"
  OnClick="Run_Subprogram"/>
	
<asp:Label id="WhichSubprogram" Runat="Server"/>

</form>

The horizontal center of the image is at x-coordinate 85. Therefore, if the x-coordinate mouse click is less than or equal to 85, then Subprogram_1 is called; otherwise, if the x-coordinate of the mouse click is less than or equal to 170, then Subprogram_2 is called. This is an example of a subprogram that calls other subprograms. Subprogram_1 and Subprogram_2 do not require signatures since no arguments are passed to them.