Building Microsoft ASP.NET Applications for Mobile Devices, Second Edition [Electronic resources] نسخه متنی

اینجــــا یک کتابخانه دیجیتالی است

با بیش از 100000 منبع الکترونیکی رایگان به زبان فارسی ، عربی و انگلیسی

Building Microsoft ASP.NET Applications for Mobile Devices, Second Edition [Electronic resources] - نسخه متنی

Andy Wigley; Peter Roxburgh

نمايش فراداده ، افزودن یک نقد و بررسی
افزودن به کتابخانه شخصی
ارسال به دوستان
جستجو در متن کتاب
بیشتر
تنظیمات قلم

فونت

اندازه قلم

+ - پیش فرض

حالت نمایش

روز نیمروز شب
جستجو در لغت نامه
بیشتر
افزودن یادداشت
افزودن یادداشت جدید






Core Controls

In this section, we'll examine the basic navigation controls: the Command control, the Link control, and—when used as a link—the Image control, and controls that affect simple output operations (the Label, TextView, and Image controls) and straightforward input (the TextBox control).

Your applications will largely consist of a user interface comprised of these controls and set in the Form and Panel container controls. Figure 4-7 shows the class hierarchy of the core controls.


Figure 4-7: Class hierarchy of the core controls


Command Controls


The Command control allows you to invoke a postback so that user input is transferred back to the server. Once control passes back to the server, the runtime invokes event handler routines that enable you to implement user interface logic. Although this control differs in appearance on different target platforms and in different contexts, it usually appears as a button on HTML browsers and as a hyperlink on WML browsers.

Syntax


You code the Command control in server control syntax as shown in the following listing. This control always causes a postback, regardless of whether you've specified an event handler in the OnClick or OnItemCommand property. CausesValidation is useful only when the Command control is on the same form as one of the Validator controls (described in Chapter 5). You use CommandName and CommandArgument only when you specify an OnItemCommand event handler.

<mobile:Command
runat="server"
id="id"
Alignment="{NotSet|Left|Centre|Right}"
BackColor="backgroundColor"
BreakAfter=="{True|False}"
Font-Bold="{NotSet|False|True}"
Font-Italic="{NotSet|False|True}"
Font-Name="fontName"
Font-Size="{NotSet|Normal|Small|Large}"
ForeColor="foregroundColor"
StyleReference="StyleReference"
Visible="{True|False}"
Wrapping="{NotSet|Wrap|NoWrap}"
CausesValidation="{True|False}"
CommandArgument="commandArgument"
CommandName="commandName"
ImageUrl="softkeyLabel"
OnClick="clickEventHandler"
OnItemCommand="commandEventhandler"
SoftkeyLabel="softkeyLabel"
Text="Text">
TextContent
</mobile:Command>


Properties and Events


Tables 4-1 and 4-2.) "Syntax" section for valid values when setting the property in server control syntax.







































Table 4-5: Significant Properties and Events of the Command Control


Property/Event


Type


Description


CausesValidation


True|False


This property is useful only when the Command control is placed in the same form as a CompareValidator, CustomValidator, RangeValidator, RegularExpressionValidator, or RequiredFieldValidator control. By default, any validator controls are triggered when a Command control causes a postback to the server. If you have a form containing validator controls, you might want to place one Command control that causes the validator controls to trigger (CausesValidation="True") and another that performs some subsidiary function, such as showing more data, but that isn't intended to signify closure of the form or submission of the form contents. In the latter case, set CausesValidation to False.


CommandArgument


String


Value of the CommandArgument property of the CommandEventArgs object delivered to an OnItemCommand event handler.


CommandName


String


Value of the CommandName property of the CommandEventArgs object delivered to an OnItemCommand event handler.


Format


System.Web.UI.MobileControls.CommandFor mat enumeration: Button|Link


Default rendering of a Command control is as a button on HTML browsers and as a link on WML browsers. You force rendering as a Link control on all devices by setting this property to CommandFormat.Link, but this is effective only if the device supports JavaScript.


ImageUrl


String


When the Command control is rendered as a button, set this property to the URL of an image source to render it as an image button. Ignore this property for those devices that don't support image buttons, such as WML browsers. You can also specify picture symbols or picture characters on those devices that support them. See the description of the ImageUrl property of the Image control in Table 4-6 for details.


Click (Event)


Event handler method name


Specifies the name of an event handler method. When a user clicks or invokes a Command control, the control returns to the server. The runtime calls the event handler method specified as the value of this property. The method must have the signature EventHandlerMethodName(Object sender, System.EventArgs e). The System.EventArgs argument contains no useful data.


ItemCommand (Event)


Event handler method name


As with the Click event, this parameter specifies an event handler method. At the server, the runtime calls the ItemCommand event handler after the Click event handler. The method must have the signature EventHandlerMethodName(Object sender, System.Web.UI.WebControls. CommandEventArgs e). You can specify values to be inserted into the CommandEventArgs argument of the event handler using the CommandName and CommandArgument properties of the Command control. Unlike the Click event, this event bubbles up to parent controls. (We'll explain event bubbling shortly.)


SoftkeyLabel


String


Certain mobile devices, such as mobile phones with Openwave WML browsers, enable users to press a softkey under the screen to select a hyperlink. You set this property to override the default label displayed for this softkey. By default, this property is an empty string, which equates to a Go label on browsers that support this feature.


Text


String


You can designate the text to be displayed for the link either by using the Text attribute or by specifying the text as the content of the <Control> element. If you specify both, when the control is rendered, the attribute takes precedence. However, setting the Text property programmatically overrides any existing setting.


If a user has completed some input fields, you can use the Command control to perform further processing based on that input. Typically, the Command control appears as a button on HTML browsers and as a hyperlink or softkey button on WML browsers. As with the Link control, you shouldn't make assumptions about the rendering of a Command control. For example, helpful prompts to the user (such as Click The Link Below) might not be appropriate on all client platforms. You don't have to specify an event handler with this control. Even if you don't specify an event handler, activating this control will still cause a postback to the server, allowing the runtime to fire any events associated with controls that don't themselves trigger postback, such as the TextBox or SelectionList controls.

The Command control raises two events that you can trap in event handlers. The simplest is the OnClick event handler, which passes no useful values in its System.EventArgs argument. The OnItemCommand event offers more flexibility. When the code calls the event handler associated with an ItemCommand event, the handler passes a CommandEventArgs object as an argument. This object has two properties, CommandName and CommandValue, which you can set using the CommandName and CommandArgument properties of the Command control. This allows you to create a form that offers two or more Command controls, providing different options to the user. Each control specifies the same ItemCommand event handler method but has different CommandArgument and CommandName attributes. This enables you to determine in your event handler code which button the user has pressed, as shown in Listing 4-3.

Listing 4-3: Source for CommandExample.aspx






<%@ Register TagPrefix="mobile" Namespace="System.Web.UI.MobileControls"
Assembly="System.Web.Mobile" %>
<%@ Page language="c#" Codebehind="CommandExample.aspx.cs"
Inherits="MSPress.MobWeb.CmdEx.MyWebForm" %>
<mobile:Form id="Form1" runat="server">
<mobile:Command id="Command1" runat="server" CommandName="RED"
OnItemCommand="Command_SelectEvent" BackColor="Red">
Red
</mobile:Command>
<mobile:Command id="Command2" runat="server" CommandName="BLUE"
OnItemCommand="Command_SelectEvent" BackColor="Blue" ForeColor="White">
Blue
</mobile:Command>
<mobile:Command id="Command3" runat="server" CommandName="GREEN"
OnItemCommand="Command_SelectEvent" BackColor="Lime">
Green
</mobile:Command>
<mobile:Label id="Message" runat="server"></mobile:Label> </mobile:Form>











The ItemCommand event also supports something called event bubbling. In normal usage, you write event handler routines that execute as a direct result of something happening to a control. In complex applications, however, you might have a design that uses templating features of a control such as List, providing a richer user interface or additional functionality for more capable client devices. Rather than write event handlers for the ItemCommand event of the child Command controls in the template, you can let the event bubble up to the parent control (the List control), and handle the event in the ItemCommand event handler of the List control. The topic "Event Handling for Controls Embedded in Templates" in Chapter 10 gives more information on event bubbling.

Using the Command Control


When run, the code in Listing 4-3 and Listing 4-4 displays a Form containing three Command controls, all using the same OnItemCommand event handler. Each Command control has a different CommandName property so that you can determine which control activated the event handler method.

Listing 4-4: The code-behind module CommandExample.aspx.cs






using System;
using System.Web.UI.WebControls;
namespace MSPress.MobWeb.CmdEx
{
public class MyWebForm :
System.Web.UI.MobileControls.MobilePage
{
protected System.Web.UI.MobileControls.Label Message;
protected void Command_SelectEvent(
Object sender, CommandEventArgs e)
{
if(e.CommandName=="RED")
Message.Text="You selected the Red option";
else if(e.CommandName=="BLUE")
Message.Text="You selected the Blue option";
else
// Catchall case
Message.Text="You selected the Green option";
}
}
}












Image Controls


The Image control allows you to display graphics files. This control presents unique problems to the developer because of the differing graphics formats supported by different handheld devices. Even within devices that support the same formats, screen display size constraints often dictate that a graphic of one size might not be appropriate for another device. Although the Image control is programmed in the same way regardless of which clients will access your application, in most cases, you'll have to supply graphics in multiple formats and use DeviceSpecific/Choice constructs and property overrides to send the correct format to each client.





Tip

The DynamicImage control described in Chapter 7 is a useful alternative to the standard Image control. It has the ability to take an image and dynamically convert it to the preferred image format of the requesting device. The DynamicImage control makes it easier to work with graphics when an application will be accessed by clients requiring different graphics file formats.


Syntax


You code the Image control in server control syntax as shown in the following listing. ImageUrl specifies the location of the graphics file that is displayed or the identity of an icon or a symbol resident in the device. If you set the NavigateUrl property, the image functions as a link to that location.

<mobile:Image
runat="server"
id="id"
Alignment="{NotSet|Left|Centre|Right}"
BackColor="backgroundColor"
BreakAfter=="{True|False}"
Font-Bold="{NotSet|False|True}"
Font-Italic="{NotSet|False|True}"
Font-Name="fontName"
Font-Size="{NotSet|Normal|Small|Large}"
ForeColor="foregroundColor"
StyleReference="StyleReference"
Visible="{True|False}"
Wrapping="{NotSet|Wrap|NoWrap}"
AlternateText="AltText"
ImageUrl="masterImageSource"
NavigateUrl="targetURL"
SoftkeyLabel="softkeyLabel">
Optional DeviceSpecific/Choice construct here.
</mobile:Image>

Properties


"Syntax" section for valid values when setting the property in server control syntax.





















Table 4-6: Significant Properties of the Image Control


Property


Type


Description


AlternateText


String


Specifies the text to be displayed on devices that don't support graphics files. This text is also displayed when the page first appears to the user, while the server retrieves the image file.


ImageURL


String


URL of the graphics file you're using. You can use a relative URL if the image file resides in the same directory or a subdirectory of the application. (For example, just use the name filename.gif if the image file resides in the same directory as the application files.) Or you can use a full URL to a different location. Alternatively, you can specify ImageURL in the form symbol:image, where image indicates a device-resident glyph. See the section "Using Device-Resident Glyphs," later in this chapter, for more details.


NavigateURL


String


If you set this property, the image becomes a hyperlink. When the user activates the image, the program flow jumps to the form or resource specified in NavigateURL. If the value of NavigateURL begins with a pound sign (#), the application interprets the rest of the value as the ID of a Form control on the same mobile Web Forms page. Otherwise, the application interprets the value as the URI of a resource.


Table 4-7 lists the support that different mobile platforms provide for the various graphics file formats.
























Table 4-7: Mobile Platform Support for Graphics Files


File Extension


Type


Where Found


.gif


Graphics Interchange Format


HTML browsers such as Pocket Internet Explorer and Microsoft Mobile Explorer support GIF files. Pocket PCs feature a usable screen size of 240 pixels wide by 320 pixels high, although they support a virtual screen size of twice that. Some i-mode phones support 256-color GIF files. The maximum size of a GIF image is 94 by 72 pixels. Palm OS devices that feature Web Clipping support both GIF and JPEG graphics. The typical usable screen size on such devices is 153 pixels wide by 144 pixels high.


.jpg


JPEG files


Supported on HTML browsers such as Pocket Internet Explorer and Microsoft Mobile Explorer; also supported by the Palm Web Clipping system as described for GIF files.


.wbmp


Wireless Bitmap (monochrome graphics)


All WML 1.1–compliant WAP devices must support Wireless Bitmap (WBMP) image files. The majority of WAP-enabled mobile phones support this format, as do RIM BlackBerry devices and other personal digital assistants (PDAs) equipped with a WML browser. Usable screen dimensions on a WAP mobile phone range from 90 by 40 pixels on smaller devices to 310 by 100 pixels on landscape-oriented devices such as the Ericsson R380. RIM devices using the GoAmerica browser have a usable screen size of 64 by 132 pixels on smaller devices. Palm devices using a WAP browser and larger RIM devices support up to 160 by 160 pixels.


.png


Portable Network Graphics


In time, this format might come to replace GIF files in general usage. WAP-enabled devices that support WML version 1.2 and offer color must support Portable Network Graphics (PNG) format. However, support for this format is rare, so you should check your device capabilities before attempting to use it.


Even within a particular genre of browser (such as the HTML browsers), your application might have to provide different graphics files if you want to support both small mobile devices and those with a larger screen. Consequently, you'll usually use this control with a DeviceSpecific/Choice construct, using the Property Override feature to set an alternative value for the ImageURL property if the requesting device is of a particular type. You'll learn more about property overrides, DeviceSpecific/Choice constructs, and device filters in Chapter 9.

Using the Image Control


Consider Listing 4-5, which doesn't specify a value for the ImageUrl property within the <mobile:Image …> tag. However, based on the Web.config file shown in Listing 4-6, if the target device supports HTML 3.2 (device filter isHTML32 is True), a property override applies to set ImageUrl to Northwind.gif. If the device supports WML version 1.1, ImageUrl is set to Northwind.wbmp. If no device filter matches, ImageUrl doesn't have a value, so the AlternateText string is displayed instead of a graphics file.

Listing 4-5: ImageExample.aspx, showing the use of choice filters and the Image control






<%@ Page Inherits="System.Web.UI.MobileControls.MobilePage"
Language="c#" %>
<%@ Register TagPrefix="mobile"
Namespace="System.Web.UI.MobileControls"
Assembly="System.Web.Mobile" %>
<mobile:Form runat="server">
<mobile:Image runat="server" id="Image1"
AlternateText="Northwind Corp.">
<DeviceSpecific>
<Choice Filter="isHTML32"
ImageUrl="Northwind.gif"/>
<Choice Filter="isWML11"
ImageUrl="Northwind.wbmp"/>
</DeviceSpecific>
</mobile:Image>
</mobile:Form>











Listing 4-6: Web.config containing the device filters required by ImageExample.aspx






<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<system.web>
<deviceFilters>
<!-- Markup Languages -->
<filter name="isHTML32"
compare="preferredRenderingType" argument="html32" />
<filter name="isWML11"
compare="preferredRenderingType" argument="wml11" />
</deviceFilters>
</system.web>
</configuration>











As with other mobile controls, if you set the BreakAfter property to False, the runtime attempts to render the image without a trailing line break, subject to it being able to lay out the page as requested in the client's available display space. This allows you to insert an image inline with text or other images. Note, however, that certain WML browsers, such as the Nokia 7110, always display images on their own line, with a following line break enforced by the browser.


Using Device-Resident Glyphs


As was described in Table 4-6, you can specify the ImageURL property in the form symbol:0000, where the 0000 decimal code is a valid identifier for a device-resident glyph, or icon. Many of these glyphs are available on i-mode devices. For example, symbol: 63648 is a glyph depicting cloudy weather. (See http://www.nttdocomo.co.jp/english/i/tag/emoji/index.html for an online reference.) If you're developing applications for J-Phone devices (devices available on the SkyWeb network in Japan), you use glyphs with the syntax symbol:X00, where X is the group picture character G, E, or F, and 00 is the hexadecimal picture character code for the glyph.

Many WML 1.1 browsers also support device-resident icons. To use these icons, you must specify the icon name. For example, symbol:cloudy indicates a cloud icon on an Openwave browser. Unfortunately, the icons available are device-specific, so you must consult the device documentation for details about supported glyphs. To use them, you must use DeviceSpecific/Choice constructs to identify the major browsers, and you must apply a property override for the ImageUrl property to set it to the appropriate symbol name for that browser. (See Listing 4-7 for an example.) You should always ensure that you specify a suitable text alternative by using the AlternateText property for devices that you don't cover. Listing 4-7 shows a form that displays two images. The first image specifies a graphic (cloudy.jpg) and alternative text (Cloudy!) that will appear if the graphic can't be displayed. If the device is an Openwave UP.Browser V4.x, you can use a DeviceSpecific/Choice construct with the isUP4x device filter that overrides the ImageURL property and instead specifies a device-resident icon called cloud.

Listing 4-7: Source for ImageGlyphExample.aspx






<%@ Register TagPrefix="mobile"
Namespace="System.Web.UI.MobileControls"
Assembly="System.Web.Mobile" %>
<%@ Page Inherits="System.Web.UI.MobileControls.MobilePage"
Language="c#" %>
<mobile:Form runat="server">
<mobile:Label runat="server">
The Weather today will be...</mobile:Label>
<mobile:Image runat="server"
AlternateText="Cloudy!"
ImageUrl="cloudy.jpg">
<DeviceSpecific>
<Choice ImageUrl="symbol:cloud" Filter="isUP4x">
</Choice>
</DeviceSpecific>
</mobile:Image>
<br>
<mobile:Image runat="server"
AlternateText="GoTo MSN"
ImageUrl="MSNlogosmall.gif"
NavigateUrl="http://mobile.msn.com">
<DeviceSpecific>
<Choice ImageUrl="MSNlogo.gif" Filter="isPocketIE">
</Choice>
</DeviceSpecific>
</mobile:Image>
</mobile:Form>











By default, the second Image control specifies a graphic named MSNlogosmall.gif. However, a DeviceSpecific/Choice construct overrides this graphic if the browser is Pocket Internet Explorer (device filter isPocketIE)—in this case, the code uses the larger MSNlogo.gif. This control also links to the MSN Web site. Listing 4-8 shows the device filter entries you must have in your Web.config for this example.

Listing 4-8: Web.config containing the device filters required by ImageGlyphExample.aspx






<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<system.web>
<deviceFilters>
<!-- Device Browsers -->
<filter name="isGoAmerica"
compare="browser" argument="Go.Web" />
<filter name="isMME" compare="browser"
argument="Microsoft Mobile Explorer" />
<filter name="isMyPalm" compare="browser" argument="MyPalm" />
<filter name="isPocketIE" compare="browser" argument="Pocket IE" />
<filter name="isUP3x"
compare="type" argument="Phone.com 3.x Browser" />
<filter name="isUP4x"
compare="type" argument="Phone.com 4.x Browser" />
</deviceFilters>
</system.web>
</configuration>











Figure 4-8 shows the results of running this code. On Pocket Internet Explorer, the cloudy.jpg graphic is displayed with the large MSN link. On the Openwave V4.1 simulator, the device-resident icon is displayed for the first image, but because the device doesn't support GIF files, it uses the alternative text for the second image. The Nokia simulator supports the JPEG of the first image, and it also supports GIFs, so it displays the small MSN logo for the second image.


Figure 4-8: Image control output on Pocket Internet Explorer, Openwave simulator, and Nokia simulator


Label Controls


The Label control allows you to place small, read-only text strings on the output device screen. We've already used it a number of times in this book.

Syntax


You code the Label control in server control syntax, as shown here. Apart from the common properties, Text is the only property of note.

<mobile:Label
runat="server"
id="id"
Alignment="{NotSet|Left|Centre|Right}"
BackColor="backgroundColor"
BreakAfter=="{True|False}"
Font-Bold="{NotSet|False|True}"
Font-Italic="{NotSet|False|True}"
Font-Name="fontName"
Font-Size="{NotSet|Normal|Small|Large}"
ForeColor="foregroundColor"
StyleReference="StyleReference"
Visible="{True|False}"
Wrapping="{NotSet|Wrap|NoWrap}"
Text="Text">
TextContent
</mobile:Label>

The text that the Label control generates will be displayed on all output devices and will include the requested style attributes if the target device supports them.

You must place the Label control within a Form or Panel container control, or within the template of a templated control. (You'll learn more about control templates in Chapter 9.)

Properties


The Label control inherits the common properties and events from the MobileControl class, as listed in Table 4-1 and Table 4-2, and exposes the Text property, as described in Table 4-8.















Table 4-8: Significant Property of the Label Control


Property


Type


Description


Text


String


You can designate the text to be displayed either by setting the Text attribute or by specifying the text as the content of the <Label> element. If you specify both, when the control is rendered, the attribute takes precedence. However, setting the Text property programmatically overrides any existing setting.


As an alternative to using the Label control, you can enter text directly onto the background of a Form control in the Mobile Internet Designer (or switch to HTML View and type literal text between the <mobile:Form> and </mobile:Form> tags). However, the Label control lets you change the text at run time; the Form control does not. If you set the Wrapping attribute on either of these controls to Wrap, the text will wrap onto the next display line. For large blocks of text, you should use the TextView control, which offers built-in pagination support. We'll discuss the TextView control later in this chapter.

Using the Label Control


Listing 4-9 defines the properties of a Label control named Label1 solely within the .aspx file. The code in Listing 4-10 sets the properties of a second label, named Label2.

Listing 4-9: Source for LabelExample.aspx






<%@ Register TagPrefix="mobile"
Namespace="System.Web.UI.MobileControls"
Assembly="System.Web.Mobile" %>
<%@ Page Inherits="MSPress.MobWeb.LblEx.MyWebForm" AutoEventWireup="False"
Language="c#" CodeBehind="LabelExample.aspx.cs" %>
<mobile:Form runat="server" id="Form1">
<mobile:Label id="Label1" runat="server"
StyleReference="title"
Alignment="Center">
Centered Title
</mobile:Label>
<mobile:Label id="Label2" runat="server"></mobile:Label>
</mobile:Form>











Listing 4-10: Code-behind module LabelExample.aspx.cs






using System;
using System.Web.UI.MobileControls;
namespace MSPress.MobWeb.LblEx
{
public class MyWebForm : System.Web.UI.MobileControls.MobilePage
{
protected System.Web.UI.MobileControls.Label Label2;
override protected void OnInit(EventArgs e)
{
InitializeComponent();
base.OnInit(e);
}
private void InitializeComponent()
{
this.Load += new System.EventHandler(this.Page_Load);
}
protected void Page_Load(Object sender, EventArgs e)
{
Label2.Text = "This was set in code";
Label2.Font.Italic = BooleanOption.True;
}
}
}











Figure 4-9 shows the output of this application in Microsoft Internet Explorer and in the Openwave simulator.


Figure 4-9: Output from the Label control examples


Link Controls


The Link control allows you to place a hyperlink on a page in order to link to another Form control or to an arbitrary Internet resource such as a URL.

Syntax


The Link control is represented in server control syntax as shown in the following listing. NavigateUrl is the most significant property. You can set this property to the ID of a Form control within your application, in which case, Link causes a postback to the server and control remains within your application. If you set NavigateUrl to the URL of some other resource, the client browser fetches from that resource and the execution of your application on that client ends.

<mobile:Link
runat="server"
id="id"
Alignment="{NotSet|Left|Centre|Right}"
BackColor="backgroundColor"
BreakAfter=="{True|False}"
Font-Bold="{NotSet|False|True}"
Font-Italic="{NotSet|False|True}"
Font-Name="fontName"
Font-Size="{NotSet|Normal|Small|Large}"
ForeColor="foregroundColor"
StyleReference="StyleReference"
Visible="{True|False}"
Wrapping="{NotSet|Wrap|NoWrap}"
NavigateUrl="target"
SoftkeyLabel="softkeyLabel"
Text="Text">
TextContent
</mobile:Link>

Properties


The Link control inherits the common properties from the MobileControl class (again, refer back to Table 4-1) and uses the Text property, as described in Table 4-9. The server control syntax doesn't expose any events.





















Table 4-9: Significant Properties of the Link Control


Property


Type


Description


NavigateUrl


String


If the value of the NavigateUrl property begins with a pound sign (#), the code interprets the rest of the value as the ID of a Form control on the same mobile Web Forms page. Otherwise, the code interprets the value as the resource's Uniform Resource Identifier (URI). A URI is the identification of any content on the Internet. The most common form of URI is a Web address, which is a subset of URI, called a Uniform Resource Locator (URL).


SoftkeyLabel


String


Certain mobile devices, such as Nokia mobile phones with WML browsers, enable users to press a softkey under the screen to select a hyperlink. You set this property to override the default label displayed for this softkey. By default, this property is set to a blank string, which equates to a Go label on browsers that support this feature.


Text


String


You can designate the text to be displayed for the link either by using the Text attribute or by specifying the text as the content of the <Link> element. If you specify both, when the control is rendered, the attribute takes precedence. However, setting the Text property programmatically overrides any existing setting.


When a user selects the Link, the browser navigates to the resource that you have specified in the NavigateUrl property. You can use this control to allow the user to move between different Form controls within your application or to the URI of a resource on the Web.

The way a user selects a hyperlink differs between HTML and WML browsers. On HTML browsers, a user can click the link using a pointing device, such as a mouse or a stylus. But on WML browsers, the user usually selects the link by pressing a softkey or by selecting the link from a menu. (Mobile phones with WML browsers often have two softkeys, which are programmable buttons positioned beneath the display screen.) Therefore, if you're targeting your application at multiple browsers, you shouldn't supply your users with text prompts such as Click the link below, because the link below might actually be a softkey, or it might not even be below!

Using the Link Control


The first form shown in Listing 4-11 contains three links. The first two of these links access the other two forms, and the third link accesses a different application—the MSN Mobile service.

Listing 4-11: Source code for LinkExample.aspx






<%@ Register TagPrefix="mobile"
Namespace="System.Web.UI.MobileControls"
Assembly="System.Web.Mobile" %>
<%@ Page Inherits="System.Web.UI.MobileControls.MobilePage"
Language="c#" %>
<mobile:Form runat="server" id="Form1">
<mobile:Link id="Link1" runat="server"
SoftkeyLabel="->Hello"
NavigateURL="#Form2">
GoTo Hello
</mobile:Link>
<mobile:Link id="Link2" runat="server"
SoftkeyLabel="->Bye"
NavigateURL="#Form3">
GoTo Goodbye
</mobile:Link>
<mobile:Link id="Link3" runat="server"
StyleReference="subcommand" SoftkeyLabel="MSN"
NavigateURL="http://mobile.msn.com">
MSN Mobile
</mobile:Link>
</mobile:Form>
<mobile:Form id="Form2" runat="server">
<B><I>Hello!</I></B>
</mobile:Form>
<mobile:Form id="Form3" runat="server">
<B><I>Goodbye</I></B>
</mobile:Form>











Figure 4-10 shows how the page appears on two mobile devices, demonstrating how the SoftkeyLabel property is used on a WML browser.


Figure 4-10: Links on the Pocket PC and the Nokia simulator


TextBox Controls


The TextBox control enables single-line input. Using this control, you can either display an initial default value or allow user input to modify or replace that initial value.

Syntax


You code the TextBox control in server control syntax, as shown in the following listing. Only the most commonly used attributes are listed. The common style attributes, such as Font-*, BackColor and ForeColor, are ignored when the TextBox control is rendered, so they're not listed here. The wmlFormat attribute is a custom attribute used for defining the Format property of the WML <input> element. To use this attribute, custom attributes must be enabled, as described later in this section.

<mobile:TextBox
runat="server"
id="id"
Alignment="{NotSet|Left|Centre|Right}"
BreakAfter=="{True|False}"
StyleReference="StyleReference"
Visible="{True|False}"
Wrapping="{NotSet|Wrap|NoWrap}"
MaxLength="maxlength"
Numeric="{True|False}"
Password="{True|False}"
OnTextChanged="textChangedEventHandler"
Size="textBoxLength"
Text="Text"
Title="Text"
WmlFormat="formatMask">
TextContent
</mobile:TextBox>

Properties


In addition to the common properties, methods, and events that the TextBox control inherits from the MobileControl class (as listed in Table 4-1 and Table 4-2), it contains the properties described in "Syntax" section for valid values when setting the property in server control syntax.




































Table 4-10: Significant Properties of the TextBox Control


Property


Type


Description


MaxLength


Integer


Sets or gets the maximum length allowed for the input text. Default is 0, which means that no limit exists.


Numeric


True|False


Sets or gets whether the input is to be forced to be numeric. This property has no effect with HTML browsers. When used with WML browsers, this property enforces numeric input on the device. On mobile phones, the browser usually switches the input mode of the phone keys from alphanumeric to numeric only.


Password


True|False


Sets or gets whether the input is accepted in a password style—that is, asterisks or another character masks the characters a user enters so that they're not readable.


Size


Integer


Desired length, in characters, of the rendered TextBox control. If you don't specify this property, the code uses a default length that's suitable for the target device. If the text the user enters exceeds the rendered control size, the input scrolls to allow further input.


Text


String


This property is blank by default. You can designate the text to display either by using the Text attribute or by specifying the text as the content of the <TextBox> element. If you specify both, when the TextBox control is rendered, the Text attribute takes precedence. However, setting the Text property programmatically overrides any text defined through server control syntax.


Title


String


This property is ignored for HTML browsers. On WML browsers (for example, the Ericsson R320), Title can be used as a prompt. On the R320, if you don't specify Title, the browser supplies a default prompt of Input.


TextChanged (Event)


Event handler method name


Specifies the name of an event handler routine. When a user changes the text in the TextBox control and the changed value posts back to the server, the code calls the event handler routine specified as the value of this attribute. The routine must be of the type EventHandlerMethodName(Object sender, System.EventArgs e).


wmlFormat


String


WML markup allows input to be constrained according to an input mask. For example, an input mask of NNNNNN forces the input to be exactly six numeric characters. For information about what formats can be applied, consult a WML language reference. This is a custom attribute, so custom attributes must be enabled to specify this attribute in server control syntax.


You can supply a default value to be displayed in the TextBox control by setting the Text property or by specifying the text as the content of this element. However, it's possible to supply a value that exceeds the maximum length you've set using the MaxLength property. The MaxLength property limits the length of the value the user can enter, but if he or she accepts the default value that you've provided, the text passed back to your program can exceed this length.

The TextChanged event allows you to specify the name of an event handler method that the code calls when a user changes the value of the Text property. The TextBox control doesn't itself trigger a postback, so when the user changes the text in a TextBox control, the event isn't raised immediately. The Form control still must contain a control that does trigger postback, such as a Command control to post the changes back to the server.

The TextBox control is rendered in the appropriate style for the input box on each target platform. This control can't contain any other controls.





Warning

If you want devices with WML browsers to access your application, you can't use the same ID property for TextBox controls that reside on different mobile Web Forms pages within the same application—in other words, controls that are fetched from the same Web site. For example, your application could start in one .aspx file and contain a link that at some point transfers execution to a second .aspx file. Each Web Forms page might contain a TextBox control with the ID TextBox1. This is programmatically correct because each TextBox1 ID exists in a different ASP.NET class and therefore has a different fully qualified name.

However, pages with controls of the same name can lead to unexpected behavior on some WML version 1.1 browsers. Values entered in a WML <input> element are stored in variables, which in turn are stored in a browser cache. Because the runtime uses the ID of the TextBox control to derive the variable name, TextBox controls that use the same ID will use the same variable. When some WML 1.1 browsers encounter an <input> element that uses the same variable name that was used by another <input> element in a card from the same site, they display the cached value that was entered in the first <input> element as the default value for the second.


Using Custom Attributes


Custom attributes, such as the wmlFormat property mentioned in the preceding section, differ from the primary attributes of a control. You enable custom attributes in one of two ways:



Set an attribute for the <mobileControls> section in the application Web.config file, which applies to all pages in the application, as shown here:

<configuration>
<system.web>


<mobileControls allowCustomAttributes="True" />


</system.web>
</configuration>




Set the AllowCustomAttributes property of the MobilePage object to True in code. This setting applies to all controls on the page, as shown here:

private void Page_Load(object sender, System.EventArgs e)
{
this.AllowCustomAttributes = true;


}




If you don't enable custom attributes, you'll get a parsing error when you attempt to use the wmlFormat attribute. Be careful when custom attributes are enabled, however, because any misspellings of standard attributes will no longer be detected during parsing. For example, the misspelled Alignmet attribute will be saved as a custom attribute of that name—the parser doesn't report it as an error.

Using the TextBox Control


In Chapter 5.

Listing 4-12: Source code for TextBoxExample.aspx






<%@ Register TagPrefix="mobile"
Namespace="System.Web.UI.MobileControls"
Assembly="System.Web.Mobile" %>
<%@ Page Inherits="MSPress.MobWeb.TBEx.MyWebForm" AutoEventWireup="False"
Language="c#" CodeBehind="TextBoxExample.aspx.cs" %>
<mobile:Form runat="server" id="Form1" title="Confirm Password">
<mobile:Label runat="server" id="Label1">
Enter new password</mobile:Label>
<mobile:Label runat="server" id="Label2" Visible="False"/>
<mobile:TextBox runat="server" id="TextBox1"
Password="True">
</mobile:TextBox>
<mobile:Label runat="server" id="Label3">
Confirm password
</mobile:Label>
<mobile:TextBox runat="server" id="TextBox2"
Password="True"/>
<mobile:Label runat="server" id="Label4"/>
<mobile:Command runat="server" id="cmdButton">OK</mobile:Command>
</mobile:Form>











Listing 4-13: Code-behind file TextBoxExample.aspx.cs






using System;
using System.Web.UI.MobileControls;
namespace MSPress.MobWeb.TBEx
{
public class MyWebForm : System.Web.UI.MobileControls.MobilePage
{
protected System.Web.UI.MobileControls.Label Label1;
protected System.Web.UI.MobileControls.Label Label2;
protected System.Web.UI.MobileControls.Label Label3;
protected System.Web.UI.MobileControls.Label Label4;
protected System.Web.UI.MobileControls.TextBox TextBox1;
protected System.Web.UI.MobileControls.Command cmdButton;
protected System.Web.UI.MobileControls.Form Form1;
protected System.Web.UI.MobileControls.TextBox TextBox2;
override protected void OnInit(EventArgs e)
{
InitializeComponent();
base.OnInit(e);
}
private void InitializeComponent()
{
this.TextBox2.TextChanged +=
new System.EventHandler(this.Verify_OnTextChanged);
this.cmdButton.Click +=
new System.EventHandler(this.cmdButton_Click);
}
protected void Verify_OnTextChanged(Object sender, EventArgs e)
{
if (TextBox1.Text != TextBox2.Text)
{
Label2.Visible = true;
Label2.StyleReference = "error";
Label2.Text = "No match - please reenter";
}
}
protected void cmdButton_Click(Object sender, EventArgs e)
{
if (TextBox1.Text == TextBox2.Text)
{
Label1.Visible = false;
Label2.Visible = false;
Label3.Visible = false;
TextBox1.Visible = false;
TextBox2.Visible = false;
Label4.Text = "Confirmed - Thanks";
}
}
}
}












Figure 4-11: Output generated by the TextBox control sample


TextView Controls


The TextView control allows you to display text that's too long for the Label control. Unlike Label, TextView supports internal pagination, so very long blocks of text are split across multiple display pages when the enclosing Form control has pagination enabled. TextView also supports embedded markup tags, in the same way as literal text on a Form control. (See Table 4-3 for details of the allowable tags.)

Syntax


In server control syntax, you code the TextView control like this:

<mobile:TextView
runat="server"
id="id"
Alignment="{NotSet|Left|Centre|Right}"
BackColor="backgroundColor"
BreakAfter=="{True|False}"
Font-Bold="{NotSet|False|True}"
Font-Italic="{NotSet|False|True}"
Font-Name="fontName"
Font-Size="{NotSet|Normal|Small|Large}"
ForeColor="foregroundColor"
StyleReference="StyleReference"
Visible="{True|False}"
Wrapping="{NotSet|Wrap|NoWrap}"
Text="Text">
TextContent
</mobile:TextView>

Properties


The significant property of the TextView control is the Text property. Table 4-11 describes the use of this property.















Table 4-11: Significant Property of the TextView Control


Property


Type


Description


Text


String


This is blank by default. You can designate the text to be displayed either by using the Text attribute or by specifying the text as the content of the <TextView> element. If you specify both the content and the attribute, the element's content takes precedence at run time. However, setting the Text property programmatically overrides any text defined through server control syntax.


The TextView control allows you to display larger amounts of text. As Table 4-11 shows, you can specify the text that you want to display in ASP.NET server control syntax using the Text attribute or the TextView element content. However, you'll probably specify the content you want to display programmatically, by setting the Text property of the TextView class.

The text content you display in the control can include literal text as well as certain markup elements such as <br>, <i> and so on. This behavior is the same as literal text in a Form control. (Refer to Table 4-3 for details of the markup elements you can use.)

With Visual Studio .NET, you don't have to code the text directly into the HTML view of the mobile Web Forms page. Instead, you can click the TextView control in Design view and then click the ellipsis (…) button adjacent to the Text property in the Properties window.

Doing so opens the text editor shown in Figure 4-12. When you enter text in this editor, don't type in the literal tags (for example, <b>This text is in boldface</b>). If you do, the tags will be treated as literal text—they will appear on the target device and won't format the text. Instead, use the Bold, Italic, and Anchor buttons at the top of the text editor screen.


Figure 4-12: Visual Studio .NET text editor for the TextView control

The TextView control supports internal pagination, which means it can split its content across multiple display screens if the Form.Paginate property is set to True in the enclosing Form control. The Form control will then ensure that any text that's too big to display on a single screen of a particular device gets split onto multiple screens. The Mobile Internet Controls Runtime will provide the necessary navigation support.

Using the TextView Control


Listing 4-14 displays the text as literal text within the server control syntax of the mobile Web Forms page.

Listing 4-14: Source code for TextViewExample.aspx






<%@ Page language="c#"
Inherits="System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile"
Namespace="System.Web.UI.MobileControls"
Assembly="System.Web.Mobile" %>
<mobile:Form runat="server" id="Form1" Paginate="True">
<mobile:Label id="Label1" runat="server" StyleReference="title"
Alignment="Center">
TextView In Use
</mobile:Label>
<mobile:TextView id="TextView1" runat="server">
The TextView control is used for larger blocks of text.
<br />
<br />
This control supports internal pagination so that if you set
the <b>Paginate</b> control of the <b>Form</b> control to
<b>true</b>, this control will page its output as
appropriate for the client browser.<br />
<br />
It also supports a set of markup elements so that <b>bold</b>,
<b><i>bold&amp;italic</i></b>, or <i>italic </i>are supported.
The line breaks in this text are actually &lt;br/&gt; tags.
You can also embed &lt;a&gt; hyperlinks to other resources:
<br />
<a href='http://mobile.msn.com'>http://mobile.msn.com</a>
</mobile:TextView>
</mobile:Form>











Figure 4-13 shows how this text would appear on both a Pocket PC and the Openwave simulator.


Figure 4-13: Larger blocks of text displayed on two mobile devices

/ 145