What is it ?
XGameLineInput is a GameComponent for the XNA framework that provides the programmer
with
the ability to allow for text entry in their game without the need for a keyboard.
How does it work ?
The component presents the gamer with a set of characters which can be
selected using a left,
right and select control. Each entered character will be displayed below this character
set. The
picture below shows this text entry in operation.
The character set is stored
in the component as an embedded resource thus removing the need to
provide a texture resource for the component to work. Full instructions are provided
below for
building the component with a different font.
How do I use it ?
The source code is provided as a Zip file which contains the complete Visual
Studio
Express project including the component and a small test program that demonstrates
its
use.
Extract the Zip file to a directory of your choosing then open the XGameLineInput
solution into VSE. You should see two projects, one is the component, the other
the
test harness. Select Build Solution (F6) from the Build menu to build the component
and test harness. If the build is successful, the component should exist as XGameLineInput.dll
in the Release directory of the component project.
First you need to add a reference to the component DLL in your game project. To
do this,
right click References in the Solution Explorer for your game.
Choose Add Reference...
then select the Browse tab. Browse to the XGameLineInput.DLL file in the /Release
directory
of the component and select it. You can now use the component in your game using
the
instructions below.
Public Properties
The component publishes
a number of properties allowing all aspects of the component to be
configured. A list of these properties is given in the table below.
|
Colour |
The colour of the text. |
|
CursorPosition |
A read-only property the returns the current position of the cursor (0 = leftmost
position). |
|
EnteredString |
This is the string entered by the
user.
|
|
InputX |
This is the horizontal pixel coordinate where the entered string will be rendered. |
|
InputY |
This is the vertical pixel coordinate where the entered string will be rendered. |
|
MaximumCharacters |
This is the maximum number of characters that can be entered. |
|
RepeatRate |
This property defines the speed of response to cursor movement. The time is specified
in ms. |
|
SetX |
This is the horizontal pixel coordinate where the character set will be rendered. |
|
SetY |
This is the vertical pixel coordinate where the character set will be rendered. |
Public Methods
The component makes
three cursor control methods publically available. These are given in the table
below.
|
Left |
Moves the cursor left one character. If the cursor is on the first character it
will wrap to the last. |
|
Right |
Moves the cursor right one character. If the cursor is on the last character it
will wrap to the first. |
|
Select |
Selects the highlighted character and adds it to the entered string. |
Initialisation
At the top of the main game source file add :
In your variables section add :
|
|
private XGameLineInput m_lineInput = null; |
In the Initialize method in your game you need to create an instance
of XGameLineInput, configure
its properties then add it to the component list.
|
|
protected override void Initialize()
{
//
// Create an instance of XGameLineInput and configure it
//
m_lineInput = new XGameLineInput( this );
m_lineInput.SetX = 20;
m_lineInput.SetY = 500;
m_lineInput.InputX = 20;
m_lineInput.InputY = 520;
m_lineInput.MaximumCharacters = 20;
//
// Add this component to the list of game components
//
this.Components.Add( m_lineInput );
//
// Other game initialization here
//
base.Initialize();
} |
Update
The game Update method can be used to control the cursor on the XGameLineInput component
using the three public methods.
The
user should call these three methods in their Update loop
based on their chosen
input method.
The example provided with the component shows cursor control using the XBox 360
gamepad
controller using the XGameInput component. An extract of this is shown below.
|
|
protected override void Update()
{
if ( XGameInput1.ControlState( PlayerIndex.One,"LEFT" ) == 1 )
m_lineInput.Left();
if ( XGameInput1.ControlState( PlayerIndex.One,"RIGHT" ) == 1 )
m_lineInput.Right();
if ( XGameInput1.ControlState( PlayerIndex.One,"SELECT" ) == 1 )
{
if ( m_lineInput.Select() == true )
this.Exit();
}
//
// Your Update() code here....
//
}
|
In the above example, the LEFT and RIGHT inputs were mapped to the controller joypad
and
the SELECT input was mapped to the A button.
It should also be noted that the Select() method returns true if the user selects
the Done
character (rightmost character in set). In the above example, selecting the Done
character
results in the program terminating.
Rendering
Because the control is based on a DrawableGameComponent, rendering of the character set,
user input and
cursor are all performed automatically by XNA through the base Draw method.
Using your own character set
The component has been designed to allow the programmer to user
their own character set.
Follow the steps below to change the default character set.
|
1. |
Create an image with the chosen set of characters. Create three additional characters
for Backspace, Done and the text cursor. Ideally, keep the image size to the power
of two. The default set is 512 x 32 pixels.
If the dimensions of the set are not to the power of two, XNA will scale up to the
next valid size making it slightly more difficult to specify the character positions
and size (see below). |
|
|
|
|
2. |
Add the image as an Embedded Resource in Visual Studio Express. To do this, Right
click on XGameLineInput in the Solution Explorer, choose Add -> Existing Item
and select the font file.
Select the font in the Solution Explorer and select Embedded Resource as the Build
Action in the Properties Pane. |
|
|
|
|
3. |
In LoadFontResource() in XGameLineInput.cs, change the font filename to your font
filename as added as an embedded resource in point 2 above. Ensure the filename
is preceeded by XGameLineInput. |
|
|
|
|
4. |
Modify the three lookup tables at the top of XGameLineInput.cs.
CHARS
This array holds the ASCII character code for each character defined in the font
image and should be in the same order as the image. Note that the backspace character
should have the code 1, the Done character should have the code 2 and the input
cursor should have the code 3.
STARTS
This array defines the horizontal pixel start of each character in the set. If the
set image file was designed with the size to the power of two, then the start positions
can be obtained from the original image.
If the image size is not to the power of two, see item A below.
WIDTHS
This array defines the pixel width of each character in the set. Again, if the set
image size is to the power of two, this value can be obtained from your original
image. Otherwise, refer to item A below. |
|
|
|
|
5. |
Build the application and run the test harness to see your new character set in
operation. |
|
|
|
|
A. |
If the character set image size is not to the power
of two, XNA will scale it up. Therefore to obtain the start pixel position of each
character and its width, uncomment the line :
//m_fontTexture.Save( "actualfont.png",ImageFileFormat.Png );
in LoadFontResource.
Now compile the project and run the test harness. Exit the test harness and look
for the file called actualfont.png in the Debug or Release bin directories in the
XGameLineInput project directory.
Use this image to determine the start pixel coordinate and width of each character
in the set and use these values in STARTS and WIDTHS.
|
|
|
|
|