|Delphi Clinic||C++Builder Gate||Training & Consultancy||Delphi Notes Weblog||Dr.Bob's Webshop|
Delphi XE and TMS iPhone Controls
Delphi XE includes IntraWeb XI, a third-party WYSIWYG web development framework.TMS Software offers a number of IntraWeb components, including a special TMW IntraWeb iPhone controls pack, which we’ll cover here for iPhone and iPad web application development.
TMS IntraWeb iPhone Controls Pack
For this section, I’ve used version v18.104.22.168 (Jan 27, 2011) of the TMS IntraWeb iPhone Controls pack, available from http://www.tmssoftware.com/site/tmsiwiphone.asp.These controls can work with IntraWeb 10.0.x and 11.0.x, and work with Delphi 7, 2006, 2007, 2009, 2010 and XE.Obviously, I’ll use them with IntraWeb XI in Delphi XE here.
After installation, the TMS IW iPhone components can be found in the Tool Palette of Delphi XE with the following alphabetical list of component names and icons:
All components have the TTIWiPhone prefix in their classname.
Below, I will first give a short description of each of these iPhone controls, before building a first little demo application showing these iPhone controls in practice.
After the first demo, which is just build to demonstrate the most important features and properties of the TMS IntraWeb iPhone controls, we’ll see a more useful example application for the iPhone: my weblog and the game of tic-tac-toe.
The TTIWiPhoneButton is a button in the iPhone style, with optionally rounded corners, which can respond to synchronous or asynchronous click events.Apart from Round, the button can also be Square or in the shape of a Back button.The TIWiPhoneButton can respond to the OnButtonClick but also the asynchronous OnAsyncButtonClick events.
The TTIWiPhoneEmailLabel is a special label control that will turn into a “hot” hyperlink if we assign values to the EmailAddress and optionally CCAddress, BCCAddress, Subject and Body properties.When you click on it during runtime, the standard iPhone e-mail application will be started, and all specified property values will be passed on to the e-mail application.
The TTIWiPhoneFooter is a special footer control for the bottom of your iPhone form, which can hold a footer caption and optionally two images (left and right), for which you can write click events.
The TTIWiPhoneGeolocation component can be used to determine the current location of the iPhone.It has one useful event: OnAsyncLocationRetrieved that can be used to provide feedback if the location is retrieved.Warning: if you have no or limited internet connection, then using this component will show down the rendering of the page!
The TTIWiPhoneHeader is a special header control for the top of your iPhone form, which can contain a caption and two buttons (left and right), for which you can write click events, for either synchronously or asynchronously button clicks.
The TTIWiPhoneList is a list control in the iPhone style (in standard list mode and settings mode), where each item can have an image, a value, a main caption and a subtext (notes).We can asynchronously insert or delete items from the list, and respond to click events in a synchronous and asynchronous way using OnItemClick, OnImageClick as well as OnAsyncItemClick and OnAsyncImageClick.Apart from these click events, there are also OnAsyncLoadExtraItems, OnAsyncExtraItemsLoaded, and OnRenderListItem events. The individual items of type TiPhonelistItem have Caption, Data (TStringList), Detail, Image, Name, Notes, Section and Value properties.The events are triggered at the parent side, passing the ItemIndex of the item or image that was clicked.
The detail information for the items can be shown using the TIWiPhonePageFlip component.
The TTIWiPhoneLocationLabel is a special label control that will turn into a “hot” hyperlink if we assign values to the predefined Location (Latitude and Longitude) and optionally Destination.When you click on it during runtime, the iPhone maps application will be started, showing your current location and optionally the destination.
The TTIWiPhoneMenu is a special footer control that can contain a collection of menu items with images and text, plus the iPhone style status indicators.We can update the status of the menu items, and respond to a user click, both synchronous and asynchronous. The Items property of the TIWiPhoneMenu control holds the TiPhoneMenuItems which each contain properties for Caption, Image, IndicatorCaption, IndicatorVisible, Name, and SelectedImage.
The individual items do not have a click event of their own, but the parent TTIWiPhoneMenu has the OnItemClick or OnAsyncItemClick events, passing the ItemIndex of the button that was clicked (starting to count at 0).
The TTIWiPhoneOnOffButton is a special iPhone style button with an “On” mode and an “Off” mode, that can be displayed in three styles: normal, system and custom.We can use the asynchronous events to update the button and to respond to the click events.Using the OffCaption and OnCaption you can translate the Off and On captions on this button. The actual state of the TTIWiPhoneOnOffButton can be retrieved or set using the ButtonState property, which can be bsOff or bsOn.
The TTIWiPhonePageFlip is a control that can be used to flip between TIWiPhoneRegion controls, featuring asynchronous updates.Ideal in combination with the TIWiPhoneList component to provide details for a list item. The TTIWiPhonePageFlip has a FrontRegion and a BackRegion property.Both can be assigned to a TWIWiPhoneRegion control.Switching between the front region and the back region can be done using the SlideToFront and SlideToBack methods of the TTIWiPhonePageFlip, or by assigning arFront or arBack to the ActiveRegion property. The transition can be controlled using AnimationSpeed and AnimationType (which can be set to atDrop, atFlip, atSlide, atSwing or atTurn).
This is a special label control that will turn into a “hot” hyperlink if we assign a value to the TelephoneNumber property.When you click on it during runtime, the iPhone will make a call to the specified number.
A region component that we can use to place IntraWeb and TMS iPhone controls, which automatically shows itself at the correct iPhone, iPod and iPad screen sizes. The TTIWiPhoneRegion has properties for AutoClientAlignAtRuntime, ClipRegion, Device (which can be set to iPhone or iPad), DevizeOrientation (oVertical or oHorizontal, although the iPhone and iPad will automatically cause the orientation to switch),
This is a special TIWiPhoneRegion component that offers iPhone style scrolling and scroll indicator, and also keeps the Header and Footer or Menu fixed, so only the content of the Region itself will scroll. Note that if you want to display a scrollable list of items, you should consider using a TTIWiPhoneList on a TTIWiPhoneRegion instead of using a TTIWiPhoneScollRegion.
This is a special label control that will turn into a “hot” hyperlink if we assign a value to the SMSNumber property.When you click on it during runtime, the iPhone will start an SMS message (initially empty) to the specified number.
The TWITiPhoneStyle component is responsible for the style of the iPhone/iPad application, and has a number of useful properties that we should set. The BGColor and BGColorTo properties, default both set to $00D4CCC5 can be used to set the gradient background color of the page. The StartupImage can contain the URL for a splash screen that will be used on the iPhone or iPad when the application starts.Even more useful is the IconImage property which can be set to the URL of the icon that’s used if we place the IntraWeb application on the home screen (desktop) of the iPhone.Note that for best results you should use PNG files, and specify a URL that can be found by the client (i.e.do not use localhost).The images will be resolved when the application is started and cached (so if you change the remote image, it will take another startup for the splash screen to be changed for example).
The TIWiPhoneTrackbas is an iPhone style horizontal trackbar, like a slider control, which can be updated asynchronously, and can produce both synchronous OnEndDrag and asynchronous events OnAsyncStartDrag, OnAsyncDrag and OnAsyncEndDrag.
TMS iPhone Controls Demo
For the TMS IntraWeb iPhone Controls demo, I’ve used Delphi XE, IntraWeb XI version 11.0.32 and TMS IntraWeb iPhone Controls pack version 1.5.
In order to show the TMS IntraWeb iPhone Controls in action, we should create a new VCL for the Web (IntraWeb) application, and place a TTIWiPhoneStyle control on the form to ensure that the correct iPhone/iPad styles are used. You can change the BGColor (top) and BGColorTo (bottom) colours form the default $00D4CCC5 to something else like clSkyBlue for the BGColorTo.
You should also set the IconImage and StartupImage in case you want other people to use your application and create a shortcut on their iPhone desktop.
Next, you should place a TIWiPhoneRegion on the form, which will show us the correct height (355) and width (320) of the browser page in the iPhone or iPod.
With the TIWiPhoneRegion component selected, place a TIWiPhoneHeader component on the TIWiPhoneRegion. It will automatically be positioned at the top of the TIWiPhoneRegion.You can configure the TIWiPhoneHeader, for example by changing the Caption to “iPhone Demo” (don’t make the header caption too long, or it will mess up the “Home” and “About” buttons that are also placed on the TIWiPhoneHeader).
With the TIWiPhoneRegion component selected, also place a TIWiPhoneFooter component on the TIWiPhoneRegion.It will automatically be positioned at the bottom of the TIWiPhoneRegion.You can configure the TIWiPhoneFooter by changing the Caption as well, for example to © 2011 by Bob Swart
Without placing any content in the middle of the TIWiPhoneRegion, we can already respond to two events: the left button and the right button on the header.The TIWiPhoneHeader component has no less than four events for them: both synchronous and asynchronous events.The synchronous events can be handled by implementing the OnLeftButtonClick and OnRightButtonClick, the more efficient AJAX-based asynchronous ones using OnAsyncLeftButtonClick and OnAsyncRightButtonClick.
As a first demo, let’s implement the About button (right button click) to put the current date and time in the Caption of the TIWiPhoneFooter. This can be done as follows using the synchronous approach:
procedure TIWForm1.TIWIPhoneHeader1RightButtonClick(Sender: TObject); begin TIWiPhoneFooter1.Caption := DateTimeToStr(Now) end;
Clicking on the right button with this event will cause the entire page to refresh, which is not always a good idea. The asynchronous approach is implemented as follows (make sure to remove the implementation of the synchronous event, as you cannot have both at the same time):
procedure TIWForm1.TIWIPhoneHeader1AsyncRightButtonClick(Sender: TObject; EventParams: TStringList); begin TIWiPhoneFooter1.Caption := DateTimeToStr(Now) end;
Using the iPhone Simulator on the Mac, we can see the application with the Header, Footer and two buttons in the header.Clicking on the About button on the right will put the current date and time in the footer, just as expected:
I leave it as exercise for the reader to compare the behaviour of the synchronous approach (with a full screen refresh) to the asynchronous version.
Note that the TIWiPhoneFoot can also have two buttons: one on the left and one on the right.The TIWiPhoneHeader has LeftButton and RightButton properties, consisting of Appearance, ButtonType, Caption, Font, ImageURL (so you can place small images on the buttons as well) and the Visible property to control if they are shown or not. The Appearance subproperty of the LeftButton and RightButton can control the BGColor and BGColorTo, the disabled colour, the “hot” colour, mirror colour, and a different colour for each of the borders (top, bottom, leftright, and disabled).
The ButtonType can be set to btBack (the left-pointing shape you see as the “Home” button in the above screenshots), btDefault (used for the About button on the right), btRound, or btSquare.Changing the ButtonType will have no effect at design time, but below you can see the btRound (at the left side) and btSquare (at the right side) on the Header of the page.
The TIWiPhoneFooter does not have a LeftButton and RightButton property, but it offers a LeftImageURL and a RightImageURL property together with a similar set of click events: OnLeftImageClick, OnRightImageClick and the asynchronous counterparts OnAsyncLeftImageClick and OnAsyncRightImageClick.
The button images will not appear at design-time, but an area will appear to indicate where they will be shown on the footer (so you may want to decrease the size of the font of the TIWiPhoneFooter or shorten the Caption.
In the OnLeftImageClick and OnRightImageClick events (not the asynchronous ones) you can also change the LeftImageURL and RightImageURL for a dynamic effect:
procedure TIWForm1.TIWIPhoneFooter1LeftImageClick(Sender: TObject); begin if TIWiPhoneFooter1.LeftImageURL = 'http://192.168.62.42/star_s.png' then TIWiPhoneFooter1.LeftImageURL := 'http://192.168.62.42/star.png' else TIWiPhoneFooter1.LeftImageURL := 'http://192.168.62.42/star_s.png' end; procedure TIWFormBlog.TIWIPhoneFooter1RightImageClick(Sender: TObject); begin if TIWiPhoneFooter1.RightImageURL = 'http://192.168.62.42/preferences_s.png' then TIWiPhoneFooter1.RightImageURL := 'http://192.168.62.42/preferences.png' else TIWiPhoneFooter1.RightImageURL := 'http://192.168.62.42/preferences_s.png' end;
Of course, you should also do some “real” work in these event handlers, but you get the idea.
Both the TIWiPhoneHeader and TIWiPhoneFooter have a property StatusText which will not show up at design-time, but will appear on the iPhone at runtime.
Apart from TMS iPhone controls, we can also place “regular” controls like a TIWEdit and TIWLabel for example.
Place both a TIWEdit and TIWLabel on the TIWiPhoneRegion, change the Caption of the Label to “What’s your name?” and clear the Text property of the Edit.Next, place a TIWiPhoneButton component below these two, make it a bit wider, set the ButtonType property to btRound, and the Caption property to “Say Hello”.
In the OnAsyncButtonClick event handler, we can use the value of the Edit to write a new caption in the Footer for example, as follows:
procedure TIWForm1.TIWIPhoneButton1AsyncButtonClick(Sender: TObject; EventParams: TStringList); begin TIWiPhoneFooter1.Caption := 'Hello ' + IWEdit1.Text end;
When you run this application and click on the Edit control to enter a name, the iPhone keyboard will slide-up, allowing you to use the keyboard to enter a name.If you click on the “Done” button, the keyboard will slide down again.
There are also four special label controls included in the TMS iPhone Control pack: namely TIWiPhoneEmailLabel, TIWiPhoneLocationLabel, TIWiPhonePhoneLabel and TIWiPhoneSMSLabel.These labels look like simple labels at design-time, but can perform a specific action at runtime.
The screenshot below has the four special labels placed on the TIWiPhoneRegion:
The TIWiPhoneEmailLabel component has string properties EmailAddress, CCAddress, and BCCAddress to control the people receiving the e-mail, as well as a property Subject and a TStringList property Body to contain the actual message.There are no less than 6 possible OnAsync event handlers we can use: OnAsyncClick being the most obvious, but also OnAsyncMouseDown, OnAsyncMouseMove, OnAsyncMouseOut, OnAsyncMouseOver and OnAsyncMouseUp. Even if we do not implement any of these on Async events, if we click on the label at runtime it will automatically start the email application on the iPhone with the values we entered for the properties.
TIWiPhoneLocationLabel has Destination, DestinationLatitude, DestinationLongitude, Location, Latitude, and Longitude properties.
The TIWiPhonePhonelabel has a TelephoneNumber property and will automatically make a phone call when you click on the label at runtime.
The TIWiPhoneSMSLabel has a SMSNumber property and will automatically start the SMS application on the iPhone to send an SMS message.
Note that neither of these special labels appear to work in the iPhone Simulator on the Mac, but they work just fine on a real iPhone. They may have limited functionality on the iPad and iPod Touch (who generally cannot phone or send SMS messages, but may be able to send e-mail messages if a wifi connection is active, and they may also be able to use the Location link).
When clicking on the Email label for example, the default email application of the iPhone will start.
Of course, we can also tilt the iPhone and allow the page to be displayed in horizontal orientation.
This will automatically happen, without any required coding from our side.Of course, it may be a good idea to make sure all controls will remain visible.In case of a normal TIWiPhoneRegion, this may not happen at all times.In that case, it may be wise to start using a TIWiPhoneScrollRegion, which is a IWiPhoneRegion control that offers iPhone style scrolling and a scroll indicator.The Header and Footer will remain fixed!
Two TMS iPhone controls that haven’t been used yet are the TIWIPhoneOnOffButton and the TIWiPhoneTrackbar component.We can place them on the TIWiPhoneRegion control to view them in action.Note that the design-time look is much simpler than the runtime look.The TIWiPhoneOnOffButton component has both an OnButtonClick and an asynchronous OnAsyncButtonClick event that we can respond to.Usually, this button is used to enable or disable options in a settings page of the iPhone application.However, we can also use it to demonstrate another control that we haven’t covered, yet, the TIWiPhonePageFlip component, which can be used to flip from one Region to another.
Place a TTIWiPhonePageFlip component on the form, set the align property to alClient, and then we can use the FrontRegion and BackRegion properties to assign two different TIWiPhoneRegion controls to it. As example second region, place another TIWiPhoneRegion component on the form, and put a TIWiPhoneHeader control on it (which will automatically move to the top) followed by a TIWiPhoneMenu control.
The TIWiPhoneMenu control will be placed at the bottom of the new region, and can be used to display menu items.We can use the Items property to add a collection of TiPhoneMenuItems, each with a Caption, Image, IndicatorCaption, IndicatorVisible, and SelectedImage property.Adding three menu items, the form designer could now resemble the following layout (with the new TIWiPhoneOnOffButton, TIWiPhoneTrackbar as well as a new TIWiPhoneRegion on the right with a header and an TIWiPhoneMenu control).
In order to demonstrate the power and ease of use of the TIWiPhonePageFlip control, we can implementing the slding between the front region and the back region.First of all, the actual sliding technique itself can be controlled by the AnomationType property, which by default is set to atSlide, but can also be atDrop, atFlip, atSwing or atTurn.The AnomationSpeed controls the speed that it takes for the animation to be shown; by default 500 ms.
In order to switch from Front to Back, we can call the TIWIPhonePageFlip1.SlideToBack method.And in a similar way, to get back to the Front, we can call the SlideToFront method. Just for fun, we can make sure that the TIWiPhoneOnOffButton will slide to the second region when we set the button to “On” , and the Back button on the Header of the secong region will slide back to the first region.These two event handlers were implemented as follows:
procedure TIWForm1.TIWIPhoneHeader2AsyncLeftButtonClick(Sender: TObject; EventParams: TStringList); begin TIWIPhonePageFlip1.SlideToFront end; procedure TIWForm1.TIWIPhoneOnOffButton1AsyncButtonClick(Sender: TObject; EventParams: TStringList); begin if TIWiPhoneOnOffButton1.ButtonState = bsOn then TIWIPhonePageFlip1.SlideToBack end;
The result can be seen below, where the left screenshot was taken just before I clicked on the “Off” button to switch it to “On” and slide the right screenshot in (which is still empty, but also shows the iPhone Menu instead of the Footer).
We can also respond to the menu item events on the second region, which is done in a single event if the menu itself, passing the ItemIndex of the button that was clicked (starting to count from 0).
procedure TIWFormBlog.TIWIPhoneMenu1ItemClick(Sender: TComponent; ItemIndex: Integer);I leave it as exercise for the reader to come up with a nice implementation of the menu options here.
There is one last TMS iPhone control that we haven’t covered, yet: the TIWiPhoneList which can show a list ot items, like a listbox, but with support for not only a single line of text, but also a subtext, a number, an image and some detailed notes.Using the demo so far, we can place a TIWiPhoneList control in the secont TIWiPhoneRegion and prepare to fill it with a list items, like blog posts. Of course, we can use the detail button to instruct the TIWiPhonePageFlip to move from one page to another as well.
An example of an IntraWeb iPhone application is the iPhone edition of my weblog which can be found at http://www.bobswart.nl/iblog and includes the game of Tic-Tac-Toe as eastern egg in the About region ;-)
In this article, I’ve covered the TMS IntraWeb iPhone Controls pack, a third-party add-on for IntraWeb to allow us to quickly and easily create web applications in the iPhone style (but also for the iPad and iPod Touch). The TMS IntraWeb iPhone controls pack is available as separate purchase, or as part of the full TMS IntraWeb Component Studio.
More detailed coverage of IntraWeb XI (and the TMS IntraWeb iPhone Controls Pack) can be found in my Delphi XE IntraWeb XI courseware manual, available as PDF from my webshop (with free updates and e-mail support).