While XNA opens up great development opportunities on the XBox 360, one of the features we don't get is the ability to access the XBox's dashboard keyboard for text entry. This DrawableGameCompoent is intended to address that issue, since we needed one for the game we are currently working on.

If you have suggestions for improvements or new features, please let us know! We can be reached at contact@xnaresources.com.

The component is self contained, and comes with the graphical resources you need to provide for text input in 1280x720 (XBox), 1024x768 (PC), and 800x600 (PC). The component will detect the video mode during initialization and load the appropriate keyboard images. The component also handles all of it's own text rendering.

The keyboard images included in the component archive use the XBox 360 button images by Sinnix, available from his blog at http://www.360p.blogspot.com.

About Resolution

We've included three different resolution images in this package, mostly for PC support. On the XBox 360, handling resolution is really dependant on what you want to do with the rest of your game. The XBox 360 will take your preferred backbuffer size and scale your game to fit the screen, no matter what display mode the user is using. I've decided to stick with 1280x720 for High-Def resolutions (720p) and 800x600 for Standard-Def resolutions. The 800x600 will scale automatically on the XBox to 480p and allows for a standard since that easily works between the XBox and the PC. 1024x768 should work just as well, but there will be more of a quality loss when scaled on the XBox.

Features

The Onscreen Keyboard component (OSKB for short) includes the following:

• Semi-transparent "below blade" area through which your game can continue to render while the keyboard is active.
• Current Player indicator on the upper right corner of the screen provides feedback on which player has control of the OSKB. The Current Player is settable by your code.
• Supports both GamePad and Keyboard input
• Both "hold down" (left trigger) and "toggle" (left thumbstick) lowercase/caps selection
• Blinking cursor insertion point! :)
• A "Symbols" page with common symbols (not all that are available on the XBox's built-in Onscreen Keyboard, however, as the OSKB only supports ASCII characters from 32-126 since other characters are commonly highly font dependant.

Using the Component

Unfortunately, XNA projects currently have no way (that I can find) of creating embedded resources that work with both the PC and the XBox, so in order to use the Onscreen Keyboard component in your game, you will need to take a few preliminary setup step to add the graphical resources it needs to your project:

• Add the "onscreenkeyboard.cs" code file to your project.
• Create the following directories in your Solution Explorer (because Solution Explorer won't let you add an existing directory, you have to Add | New Folder these directories first and then copy the files in and then add them to the project... It's clunky, I know):
  • content\onscreenkeyboard
  • content\onscreenkeyboard\800
  • content\onscreenkeyboard\1024
  • content\onscrenekeyboard\1280
• Copy all of the graphics images included with the component to the appropriate directories and add them to your Solution. There should be 16 image files (all PNG files):
  • Three keyboard images for each of the three different resolutions
  • Courier30pt.png - The 30 Point Courier Font as a white-on-transparent bitmap.
  • player1.png thru player4.png - The current player indicators for players 1-4.
  • Selector_Small.png - The standard key selector (small green square)
  • Selector_Long.png - The elongated selector image used for Space and Backspace.
• Add "using oskb;" to the "Using Statements" section of your game code.

Since the Onscreen Keyboard is a DrawableGameComponent, you will need to declare an instance of the OSKB and instanciate it during your game's initialization. For example:

    public class Game1 : Microsoft.Xna.Framework.Game

    {

        GraphicsDeviceManager graphics;

        ContentManager content;

        OnscreenKeyboard oskb;

        public Game1()

        {

            graphics = new GraphicsDeviceManager(this);

            content = new ContentManager(Services);

        }

        protected override void Initialize()

        {

            graphics.PreferredBackBufferWidth = 1280;

            graphics.PreferredBackBufferHeight = 720;

            graphics.IsFullScreen = false;

            graphics.ApplyChanges();

            oskb = new OnscreenKeyboard(this);

            oskb.Visible = false;

            oskb.Enabled = false;

            oskb.DrawOrder = 200;

            oskb.UpdateOrder = 200;

            this.Components.Add(oskb);

            base.Initialize();

        }

Things to note here:

• The Initialize routine above sets the requested display mode. When the OSKB component runs LoadGraphicsContent it will check the display mode to determine what resolution-specific images to load, so it is important that the display mode be in place before that happens (currently the component does not support changing resolutions mid-stream. That may be an option for the future).
  • Note: The OSKB will assume a 1280x720 resolution by default and detect 1024x768 or 800x600 as alternatives. If you use any other video mode, the 1280x720 image will be used. If you wish, you can create a new keyboard image and add code for the resolution you wish to use to your game.
• The DrawOrder and UpdateOrder are set very high. Assuming you have other components and such in your game, you will probably want to place the OSKB at the latest draw/update order so that it is displayed above anything else when it is active.
• The component should be set to Enabled=false and Visible=false when it is not in use, otherwise it will overlay whatever else is going on in your game.

When you want to pop up the OSKB, simply Visible and Enable it:

                oskb.Enabled = true;

                oskb.Visible = true;

The OSKB will automatically deactivate itself (both enabled and visible) when the user has finished entering text (either by pressing "Start" (PC: Enter) or "B" (PC: Escape)).

Properties

The following properties are available via the component:

• Text : This string property contains the text that was input. It is read/write, and if set before displaying the OSKB, this will be the default text in the entry window.
• MaxLength : An integer property that determines the maximum number of characters to allow. Note that a maximum of 39 characters fits nicely in the alloted input window, and currently the component does not allow for scrolling. If the value of Text is larger than MaxLength (set via code, for example) the user will be able to remove characters but won't be able to add any until the length falls below MaxLength.
• Prompt : This string property contains the text string that appears above the text entry windows. It can be left blank if you don't wish to prompt, but some type of indication about what you are expecting the user to input would be a good idea.
• PromptColor : A Color property that controls what color the "Prompt" text will be displayed in.
• Player : A PlayerIndex value representing which controller to monitor for input. Defaults to PlayerIndex.One.
• ExitState : This integer property can be use to determine how the user exited the text screen. Note that the ExitState is set to 0 during each Update loop of the component, so when you first Enable the component it will be set to 0 during the NEXT update cycle, so it is important to take this into account when testing for the OSKB to have exited. In fact, I would suggest testing both the ExitState and Visible to see of the component is still active. ExitState has the following potential values:
  • -1: The OSKB has not yet been used. This is the default starting value.
  • 0 : The OSKB is currently active. (Has not been exited)
  • 1 : The user pressed "Start" (PC: Enter) to successfully complete the entry.
  • 2 : The user pressed "B" (PC: Escape) to cancel the entry.

Bonus Function

As an aside, I marked the "WriteText" function of the component as public instead of private. This makes it possible to call the WriteText function from your game to display text in the component's simple mono-spaced font. (Note that I didn't say this was a good idea, as it kinda breaks the idea of encapsulation, but for my quick testing purposes it lets me get text onto the screen without duplicating the font image and code somewhere else.)

Adding Custom Resolutions

If you look at the Initialize method for the OnscreenKeyboard.cs file, you will see a couple of "if" statements that check for different resolutions and make appropriate adjustments. You can add your own keyboard images and do the same checking as well (if anyone really wants images for a specific resolution, just let us know at the contact e-mail above and we can produce them from the original Photoshop files).

The custom resolution settings look like this:

                if (GraphicsDevice.PresentationParameters.BackBufferWidth == 1024)

                {

                    sImageNames[0] = @"content\onscreenkeyboard\1024\1024_keyboard_1";

                    sImageNames[1] = @"content\onscreenkeyboard\1024\1024_keyboard_2";

                    sImageNames[2] = @"content\onscreenkeyboard\1024\1024_keyboard_3";

                    oskb_DestRect = new Rectangle(0, 0, 1024, 768);

                    oskb_EntryHilightX = 235;

                    oskb_EntryHilightY = 290;

                    oskb_EntryStartX = 128;

                    oskb_EntryStartY = 190;

                    oskb_PromptX = 50;

                    oskb_PromptY = 140;

                    oskb_PlayerIconX = 938;

                    oskb_PlayerIconY = 106;

                }

As you can see, all that really happens is that the image file names get replaced with the new resolution specific images, and the positions of all of the various display components get updated to reflect their new locations on the screen.

Downloads

There are three files available for download associated with the Onscreen Keyboard Component:

• Primary Component Package : Contains the .cs code file for the OSKB, along with the Content directory containing the associated images.
• Windows Test Project : A *very simple* test project demonstrating using the OSKB under Windows. (Set the PreferredBackBufferWidth and PreferredBackBufferHeight in Initialize to match your screen resolution. You can also set IsFullScreen to true here).
• XBox Test Project : The same test project built for the XBox 360.

In the Test projects, press the Right-Shoulder button (or Space Bar) to display the keyboard. Pressing Back or Alt-F4 will exit the project.