CoronaCards — Windows Phone 8

Copying Project Files

1. In Visual Studio, view the Solution Explorer panel.
2. Expand the project's Assets → Corona tree.
3. Open Windows Explorer, browse to the Corona project's root folder, and select all of the files.
4. Drag-and-drop the files into the Assets → Corona tree within Visual Studio.
5. Highlight all of the Corona files within the Corona tree.
6. In the Properties panel for Build Action, select Content in the drop-down menu.

Adding App Icons

Corona icon image files such as Icon.png, Icon-hdpi.png, etc. are not supported on Windows Phone and will be ignored. Thus, you should omit these files from your Visual Studio project's Assets\Corona directory.

To include an app icon for Windows Phone, create a 100×100 pixel PNG image file named ApplicationIcon.png. When you create a new Windows Phone project in Visual Studio, a default ApplicationIcon.png will be automatically generated in the project's Assets directory. You should edit or replace this with your custom image. Unlike iOS or Android, Windows Phone does not support multiple application icon files of different resolutions — the operating system will simply scale the main icon.

Windows Phone can also display a tile for your application on the start screen. When you create a new Windows Phone project in Visual Studio, default tile images are automatically created under the project's Assets\Tiles directory. For more details on tile support, see Microsoft's documentation.

Setting the App Orientation

For iOS and Android projects, you typically indicate supported orientations via the build.settings file. This file is not supported on Windows Phone and will be ignored. Thus, you should omit this file from your Visual Studio project's Assets\Corona directory.

To set the orientation of a Windows Phone app, please follow these steps:

1. In Visual Studio, view the Solution Explorer panel.
2. Double click the MainPage.xaml file.
3. In the XML editor, click on the <phone:PhoneApplicationPage> tag's SupportedOrientation attribute.
4. View the Properties panel and click on the SupportedOrientations pull-down box.
5. Select either Portrait, Landscape, or PortraitOrLandscape.

Identifying the Platform

In Lua, you can check if an app is running on Windows Phone with the following code:

if ( system.getInfo("platformName") == "WinPhone" ) then
    -- This app is running on Windows Phone
end

Back Key Support

Windows Phone has a "back" key just like Android devices. Pressing this key will exit the app, so you are expected to override this key and implement backward navigation within your own Corona scenes before allowing the app to exit.

local function onKeyEvent( event )
    -- If the 'back' key was pressed on Android or Windows Phone, prevent it from backing out of your app
    local platformName = system.getInfo( "platformName" )
    if ( platformName == "Android" ) or ( platformName == "WinPhone" ) then
        if ( event.keyName == "back" ) then
            -- Navigate back one scene or display an 'Are you sure you want to exit' alert
            return true
        end
    end

    -- Return false to indicate that this app is *not* overriding the received key.
    -- This lets the operating system execute its default handling of this key.
    return false
end

-- Add the key event listener
Runtime:addEventListener( "key", onKeyEvent )

Call/Notification Interruption

The Windows Phone operating system will not automatically suspend your app when an incoming phone call is received. Instead, when a phone call occurs, Windows Phone will overlay a notification over the app, but the app will continue running. Thus, Microsoft allows developers to decide if an app should or shouldn't suspend during a phone call. However, games are expected to suspend during a phone call and Microsoft will reject your game from the Windows Phone Store if it doesn't suspend.

You can detect phone call interruption when a .NET Obscured event is raised by the operating system. However, note that this event will also be raised when a notification is received. Currently, there's no way to differentiate between these two events, but you can handle them similarly since Windows Phone notifications obstruct a large portion of the screen and games should be suspended in both cases.

To suspend an app during this event, do the following:

1. In Visual Studio, view the Solution Explorer panel.
2. Double click on the MainPage.xaml.cs file below the MainPage.xaml file in the tree.
3. Edit the code as follows:

// [C#]

public partial class MainPage : PhoneApplicationPage
{
    public MainPage()
    {
        // Initialize this page's components that were set up via the UI designer.
        InitializeComponent();

        // Set up Corona to automatically start up when the control's Loaded event has been raised.
        // Note: By default, Corona will run the "main.lua" file in the "Assets\Corona" directory.
        //       You can change the defaults via the CoronaPanel's AutoLaunchSettings property.
        fCoronaPanel.AutoLaunchEnabled = true;

        // Set up the CoronaPanel control to render fullscreen via the DrawingSurfaceBackgroundGrid control.
        // This significantly improves the frame rate and is the only means of achieving 60 FPS.
        fCoronaPanel.BackgroundRenderingEnabled = true;
        fDrawingSurfaceBackgroundGrid.SetBackgroundContentProvider(fCoronaPanel.BackgroundContentProvider);
        fDrawingSurfaceBackgroundGrid.SetBackgroundManipulationHandler(fCoronaPanel.BackgroundManipulationHandler);

        // Add application event handlers.
        App.RootFrame.Obscured += OnAppObscured;
        App.RootFrame.Unobscured += OnAppUnobscured;
    }

    private void OnAppObscured(object sender, ObscuredEventArgs e)
    {
        if (e.IsLocked == false)
        {
            fCoronaPanel.Runtime.Suspend();
        }
    }

    private void OnAppUnobscured(object sender, EventArgs e)
    {
        fCoronaPanel.Runtime.Resume();
    }
}

Optimizing Text Performance

Text generation via display.newText() or display.newEmbossedText(), and text rendering within widgets, is a slow and expensive operation on Windows Phone. This performance issue is caused by the operating system's native text rendering APIs and it cannot be further optimized by Corona Labs.

One workaround for this performance issue is to use "bitmap" fonts. This involves setting up an imageSheet which contains all of the required letters/characters and then render your text via display.newImage() or display.newImageRect() objects. This will vastly improve your app's text rendering performance, since all characters will be pre-loaded.

The following third-party bitmap font libraries may be considered:

• bmGlyph
• Font-Manager
• TextCandy

Note that a bitmap font library is best used for text that's under your app's control. This means that it shouldn't be used for text strings taken from a source like Facebook, Twitter, or another outside source, as this text may contain special characters which are not included in your imageSheet. In these cases, using display.newText() should be acceptable, since the text will not likely be updated/changed frequently.

Finally, regarding widgets, the performance penalty will only occur if the widget contains text, for example text inserted into tableView rows. When inserting text in this case, you should either pre-load text generated by display.newText() or use bitmap fonts.

Using Embedded Fonts

If your Corona project includes a .ttf or .otf font file which you want to utilize via display.newText() or similar, you must use the following font naming convention — this is a standard Windows Phone XAML font naming standard which Corona uses to load embedded fonts.

local fontName = "<MyFontNamePlusExtension>#<My Font Family Name>"

For example, if you copy a Times New Roman font file named Times.ttf into your project's Assets\Corona folder, it may be displayed as follows:

local myText = display.newText( "My Text", 0, 0, "Times.ttf#Times New Roman", 8 )

In Windows, you can determine a .ttf or .otf file's font family name by double clicking on it. This will display a window which reveals the font family name in the title bar or next to the Font name: field.

Note that Windows Phone may refuse to load some font files and default to the system font instead. If the operating system refuses to load a particular font that you've provided, you'll need to use a different font file or generate a bitmap font using a bitmap font library.

Audio Support

For audio playback on Windows Phone, CoronaCards supports the following audio file formats:

• .ogg (Ogg Vorbis)
• .wav (16-bit uncompressed)

CoronaCards for Windows Phone 8 does not support the audio recording feature.

In-App Purchases

CoronaCards for Windows Phone 8 does not support the store API and thus does not feature direct in-app purchase (IAP) support. However, you can implement IAP yourself via Lua/.NET Communication — please inspect the example code here.

Implementing Missing Features

If your app requires other features which are not supported by CoronaCards for Windows Phone 8, you may be able to implement these features yourself in .NET. Please proceed to the Lua/.NET Communication guide for more details.