Less Yap, More Tip

Today’s advent tip is how to open the Messages app (aka the SMS app) with a specific phone number populated in the To: field. This is accomplished with great ease because the iPhone has implemented the sms: URI scheme. Therefore, we can use the UIApplication class’ openURL method, which we have seen before when we discussed how to dial a phone number, pre-compose an email, and yes, even open a URL.

So here it is: the one line of code you need to pop open the SMS app with a phone number:

[[UIApplication sharedApplication] openURL:[NSURL URLWithString:@"sms:5555555555"]];

We had a number of cases like this when developing Addicus. In particular, because we have both the game and game over screens operating in a single cocos2d scene, we were noticing some bugs that occurred because of the way we handled input. This was solved by suspending input for brief periods of time.

Input Goes Off

Here’s how to tell your iPhone app to stop responding to touch events in just one line of code:

[[UIApplication sharedApplication] beginIgnoringInteractionEvents];

Input Goes On

And as you might expect, resuming responding to touch input events is similarly easy:

[[UIApplication sharedApplication] endIgnoringInteractionEvents];

Left idle, the iPhone goes into sleep mode after about a minute. This narcoleptic behaviour saves on battery life, but there are situations where you would not want the device to go to sleep. For instance, in the middle of a multiplayer game that is turn-based, such as chess. You could wait for longer than a minute for your opponent to make make their move and you wouldn’t want to miss it when they did.

To keep the iPhone awake and alert, simply run the following line of code:

[UIApplication sharedApplication].idleTimerDisabled = YES;

Do use this tip sparingly though. The iPhone’s power is unmatched, to be sure, but unfortunately it is not unlimited.

Show It

If you would like to let your users know that your iPhone app is currently swapping data with the network, you can do so with this simple line of code:

[UIApplication sharedApplication].networkActivityIndicatorVisible = YES;

Hide It

You guessed it: once you’re done showing it, to hide it again, just set the same UIApplication property to NO like so.

[UIApplication sharedApplication].networkActivityIndicatorVisible = NO;

As such, from time to time you will have a need to retrieve your app’s application delegate instance. You can retrieve it from anywhere within your app by running the following single line of code:

MyAppDelegateClass *app = [[UIApplication sharedApplication] delegate];

Just be sure to replace “MyAppDelegateClass” with your own iPhone app’s application delegate class name.

Like other phones, the iPhone supports the tel application protocol in URLs. This means that all we need to use is the trusty openURL method of the UIApplication class. We have previously discussed this method when pre-composing emails and, believe it or not, opening a URL.

The Code

Here is how to dial a phone number from your iPhone app in one line of code:

[[UIApplication sharedApplication] openURL:[NSURL URLWithString:@"tel:555-555-5555"]];

Dialing From a Web Page

You can also put links in your web pages that dial a phone number on the iPhone by using the tel protocol like so:

<a href="tel:555-555-5555">Dial 555-555-5555</a>

UIStatusBarHidden

The first way is by adding a setting to your app’s info.plist file called UIStatusBarHidden. This is ideal for apps that should never display the status bar. Just follow these steps to change the setting:

1. Open your iPhone app’s info.plist file.

2. Command-click and select Add Row.

3. Select “Status bar is initially hidden” from the drop down that appears.

4. Check the checkbox that appears next to the new row.

You could also add this setting to your app’s info.plist file by opening it in a text editor and adding the following 2 XML tags inside the <dict> tag:

<dict>
	<key>UIStatusBarHidden</key>
	<true/>
	...

How to Do it With Code

If you need the status bar to appear and disappear at runtime, then you will need to use code to do so. You can hide the status bar with one line of code:

[[UIApplication sharedApplication] setStatusBarHidden:YES animated:NO];

And to show it again, simply call the above line and pass “NO” into setStatusBarHidden instead of “YES”. You can also fade the status bar in and out by passing “YES” into the “animated” part of the message.

A Handy Function

The sendEmailTo function, seen below, can be included in any class in your app. This function gives you a simple interface to send emails. It allows you to define “to” addresses, “cc” addresses, “bcc” addresses, a subject and a body. The body supports HTML tags.

- (void)sendEmailTo:(NSString*)to withCC:(NSString*)cc withBCC:(NSString*)bcc withSubject:(NSString*)subject withBody:(NSString*)body {
	NSString * url = [NSString stringWithFormat:@"mailto:?to=%@&cc=%@&bcc=%@&subject=%@&body=%@",
					  [to stringByAddingPercentEscapesUsingEncoding:NSASCIIStringEncoding],
					  [cc stringByAddingPercentEscapesUsingEncoding:NSASCIIStringEncoding],
					  [bcc stringByAddingPercentEscapesUsingEncoding:NSASCIIStringEncoding],
					  [subject stringByAddingPercentEscapesUsingEncoding:NSASCIIStringEncoding],
					  [body stringByAddingPercentEscapesUsingEncoding:NSASCIIStringEncoding]];
 
	[[UIApplication sharedApplication] openURL:[NSURL URLWithString:url]];
}

NOTE: Running this function in the iPhone Simulator will have no effect because the simulator does not include the iPhone’s Mail app. To see the effects of this function, it must be run on a device.

Example Usage

Once you have that message defined in one of your classes, you can open the Mail app with a pre-composed email with just one message call. The following example opens an email and specifies a to, cc and bcc address. It populates the subject with “Addicus” and populates the body with a short message about Addicus that includes a link and an image (which is also a link). As you can see, this is done with good old HTML tags. This results in the email in the above screenshot.

[self sendEmailTo:@"mom@example.com"
           withCC:@"dad@example.com"
          withBCC:@"asecretfriend@example.com"
      withSubject:@"Addicus"
         withBody:@"<p>Check out this game, <a href='http://addicusgame.com'>Addicus</a>, for the iPhone and iPod Touch. It's super-addictive!</p><p><a href='http://addicusgame.com'><img src='http://getsetgames.com/wp-content/uploads/2009/11/icon_addicus.png'/></a></p>"];

If you would like to have the user specify the to, cc and bcc addresses themselves, as you would in the case of a tell-a-friend button, then you would call the following message:

[self sendEmailTo:@""
           withCC:@""
          withBCC:@""
      withSubject:@"Addicus"
         withBody:@"<p>Check out this game, <a href='http://addicusgame.com'>Addicus</a>, for the iPhone and iPod Touch. It's super-addictive!</p><p><a href='http://addicusgame.com'><img src='http://getsetgames.com/wp-content/uploads/2009/11/icon_addicus.png'/></a></p>"];

myAppDelegate *app = [[UIApplication sharedApplication] delegate];
UIScrollView *appOverlayScrollView  = (UIScrollView *)app.view;
[[app window] sendSubviewToBack:appOverlayScrollView];

This creates a messy dependency between an arbitrary class and the app delegate class.  Wouldn’t it be great if we could send a message to the app delegate and tell it to move the scroll view to the front or back maintaining encapsulation?  Turns out you can indeed do this.  The UIApplication class contains a method called sendAction which is normally used to send an action message identified by a selector to a specified target.  This method can easily be used to call selectors in any object so the above code can be converted to…

[[UIApplication sharedApplication]
sendAction:@selector(bringScrollViewToFront)
to:[[UIApplication sharedApplication] delegate]
from:self
forEvent:nil];

The only downside to this approach is that I haven’t found a way to supply arguments along with the selector so you need to be calling a method with no arguments.  If you know of a way around this issue please do let me know.

On With The First Tip!

Say you would like to open a URL in Safari. We used this on the “Get Set” button on the main menu of Addicus. Here is how to do it with just one line of code using the UIApplication class:

[[UIApplication sharedApplication] openURL:[NSURL URLWithString:@"http://getsetgames.com/"]];