Image Control

Article
09/14/2006

The ability to transmit images to wireless devices is important in building effective ASP.NET mobile Web applications. The Image control provides the capability to specify the image that you want to display on a wireless device.

Because of the nature of wireless devices, a single image file will not be appropriate for all devices. Some browsers are incapable of displaying certain image formats, and not all image sizes and color content are appropriate for all devices. For example, an image formatted as a .gif file will be displayed on HTML-capable browsers, but will not be displayed on WML-capable browsers. For WML-capable browsers, you need an image formatted as a .wbmp file.

With the Image control, you can specify multiple image files; thus, you can create the same image in multiple file formats. The control chooses the correct image file based on device characteristics. The Image control itself is independent of the type of image file that you use. You can use any type of image file that is compatible with the targeted browser.

Just as reusing code has become an effective technique in application design, so also is reusing images. With the Image control, you can reuse an image by creating a user control from it. For more information about user controls, see the Creating Custom ASP.NET Mobile Controls documentation.

Mobile Controls Syntax

Required properties, defaults, and code-featured elements are noted in bold type.

<mobile:Image
   runat="server"
   id="id"
   Font-Name="fontName"
   Font-Size="{NotSet|Normal|Small|Large}"
   Font-Bold="{NotSet|False|True}"
   Font-Italic="{NotSet|False|True}"
   ForeColor="foregroundColor"
   BackColor="backgroundColor"
   Alignment="{NotSet|Left|Center|Right}"
   StyleReference="styleReference"
   Wrapping="{NotSet|Wrap|NoWrap}"

   AlternateText="AltText"
   ImageUrl="masterImageSource"
   NavigateURL="targetURL"
   SoftkeyLabel="label">
Place DeviceSpecific/Choice construct here. (optional)
</mobile:Image>

Containment Rules

The following controls can contain an Image control.

Control	Comments
System.Web.UI.MobileControls.Form	Can contain any number of Image controls.
System.Web.UI.MobileControls.Panel	Can contain any number of Image controls.

An Image control can contain the following controls.

Control	Comments
System.Web.UI.MobileControls.DeviceSpecific	Specifies per-device image alternatives. 0 or 1 DeviceSpecific controls can be contained in an Image control.

Device Templates

None.

Device-Specific Behavior

When an Image control is activated on a mobile device, the control evaluates the capabilities of the device. Based on that evaluation, the following can occur:

The text in the AlternateText property is rendered as a Label control if the device is not capable of displaying images.
For image-capable devices, the control checks for a URI to a registered image specifically for the incoming device. To find a registered image, the control checks for a <DeviceSpecific> clause inside the Image control. If one exists, the control evaluates and extracts a value from a matching <Choice> clause. This value is treated as the URI of an image file and is used to render the file on the device.

Regardless of what is rendered, the control picks up the alignment and text properties from the Style object.

Using the symbol: URL Scheme

The ImageUrl property usually contains the URL for an image. However, when the Image control retrieves the URL, it also checks for a particular scheme that signals device-specific information to the control. This scheme or prefix-formatted text signals the control to generate specific markup that causes the target device to display the built-in image that matches the scheme.

The symbol: scheme, used as the value for the ImageUrl property, is the signal for the Image control to find the specified image and display it on the target device. For example, on an i-mode phone, if the value of the ImageUrl property is symbol:63726*,* it is emitted as &#63726*,* and then rendered on the target device as a heart icon.

The symbol: scheme is honored on i-mode and on WML version 1.1 phones that support glyphs.

HTML and WML Commonalities

At run time, the Image control usually generates an <img> tag with the src attribute set to the chosen Choice value. The alt attribute is set to the alternate text (if it exists).

If a NavigateURL property is specified, the image is enclosed in an appropriately rendered <a> tag (anchor).

The Image control does not render a <br> tag (line break) after the image. This allows images to be rendered next to each other. However, if you want to simulate a line break, you can insert an empty Label control after the image.

If the Alignment property is set, the Image control sets the align attribute to that value.

Note WML devices have varying limits for image size. Before proceeding, check the specifications for the device or devices that you are interested in.

Example

The following example presents three alternate images to be chosen by the control, based on device characteristics. The control chooses alternate text where no images are appropriate. Substitute the names of your images to run the control and add the device filters to your web.config file. For more information about device filters, see Device-Specific Rendering.

<%@ Page Inherits= "System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile"
    Namespace="System.Web.UI.MobileControls"
    Assembly="System.Web.Mobile" %>

<mobile:Form runat="server">
  <mobile:Image runat="server" id="myImages" AlternateText=
   "Sorry, this requested image cannot be displayed on this device.">
   <deviceSpecific>
     <choice Filter="IsColor"
      ImageUrl="myColor.gif"/>
     <choice Filter="Wml"
      ImageUrl="myWMLImage.wbmp"/>
     <choice ImageUrl="myColor.bmp"/>
   </deviceSpecific>
  </mobile:Image>
</mobile:Form>