Applies to: Zune (Code works in Windows as well)

In my last tutorial, I covered building a static TextHandler class to assist in drawing text to the screen. In this tutorial, I'm going to expand on that concept by building a simple text file viewer for the Zune. First, though, some discussion about the platform and the limitations we have under it.

The Zune is a relatively restricted device (especially true compared to your Windows PC). The only (official) way to get files on or off of the Zune is via the Zune software or an XNA installer. We don't have access to browse the Zune's file system directly or store arbitrary types of files on the device.

The reason I bring this up is that the Text Viewer we will be building is really more of an example and proof of concept, since we can't actually add text files to it outside of the Visual Studio environment. All of the text files we want to view with our Zune will need to be included in our project when it is deployed to the Zune device.

That said, this tutorial will cover some interesting concepts such as:

• Working at a basic level with the file system (Loading files and setting up to save "games" on the Zune)
• Utilizing the TextHandler class
• Fun String Handling!
• Dealing with input on the Zune
• Managing simple Game States
• and a few other things...

Getting Started

From a design standpoint, we will create a "game" with two modes. In the first mode, we will be browsing a scrollable list of text files that have been added as content to the project before it gets deployed to the Zune. We will use the System.IO namespace's features to retrieve the list of files.

In the second mode, we will display the contents of the selected file to the screen, displaying enough lines to fill the display. The user can use the Zune Pad to scroll up and down, and use left and right on the pad to page up and down.

In both modes, pressing the "Play" button on the Zune switches to the other mode.

In order to demonstrate a few more features, we will also track the position we were in when we last viewed a file so that we can return directly to that position if we open the file again. We will do this by creating files in our save game area.

Fire up Visual Studio and begin by creating a new Zune Game project calling it "ZuneTextViewer". Use Windows Explorer to copy the TextHandler.cs into your project folder and then include it in your project (Right click on the project name in Solution Explorer, Add, Existing Item). Update the namespace in the TextHandler.cs class to match the namespace of the game project (ZuneTextViewer).

I've created a "starter" project which can be downloaded here that contains the new project with TextHandler.cs set up appropriately.

As with our demo project, we are going to need some SpriteFonts, so create a Fonts folder under Content and right click on Fonts, select Add, New Item, select SpriteFont, and add a SpriteFont called "Pescadero12.spritefont" to the project.

Edit the details of the SpriteFont file to change the FontName from Kootenay to Pescadero, and change the size to 12. Scroll down a bit further in the file and look for a line that says:

<!-- <DefaultCharacter>*</DefaultCharacter> -->

Remove the comment characters (<!-- from the beginning and --> from the end) from the line to uncomment it.

The DefaultCharacter attribute in a SpriteFont allows us to specify a character that will be used whenver we try to print a character that is not in our SpriteFont. This can happen if we convert text from a file that uses angled quote marks or the like and will prevent our viewer from crashing if the text files we view contain characters that aren't part of our default character set.

Extending TextHandler.cs

We will be adding two new methods to TextHandler.cs in order to make coding the main part of our TextHandler a little easier. These will make it easier to pull a potentially long text file apart into single lines that we can then use in our code.

The first of these methods is fairly generic, and simply returns the number of times a particular character appears in a string. We will be using this to detect newline characters in the files we process:

All we are actually doing here is getting the length of the string we are searching, replacing the character we are looking for in the string with an empty string (thus removing it from the string) and subtracting the length of the result from the original. This will give us the count of the number of times the character appears in the string. We could, of course, have used a loop and counter variable to do the same job (and in fact I had it coded that way to begin with) but this is shorter and works just as well.

The second method we will be adding will be called in the same way that our WrapText method is called, except that instead of inserting newlines into the return string, it will return just enough characters to make up a single line, dropping the rest.

It is, in fact, very similar to our WrapText method. You will notice that a line can end one of two ways: we can fill up our MaxLineWidth, or we can run into a "word" that contains a newline (\n) character. In the latter case, we append a number of spaces to the string equal to the number of newline characters the word contains. This simply helps with formatting a bit.

Building the Text Viewer

That's it for our modifications to the TextHandler class. Everything else we do will now be done inside our Game class, so switch back to the Game1.cs file.

As I stated above, we will be using the System.IO namespace, so make sure you add:

to the using declarations at the top of the file.

We are going to have a number of declarations that we will add right after "SpriteBatch spriteBatch;" in our game's declarations area. I'm going to paste the full list of them in here. They are all commented, but I will discuss a few of them in detail below.

When our application is launched, we will cache the names of all of the text files available for us to browse into a List object for display when the reader is in "Menu Mode". In the particular case of this application, we don't need to update this list dynamically, becase the only way to get files onto the Zune and available to our Text Reader is to add them to your XNA project before deployment.

The "TextFiles" List object will hold this list of file names and be used both for displaying the names on the menu and passed to our file loader function to actually read the file from the device.

Our next object is a Texture2D called t2dScrollBar. We will create this shortly, but essentially we will be using a 1x1 pixel white texture and taking advantage of the ability of the SpriteBatch object to colorize a texture when drawing. We'll create and load the 1x1 texture when we get to the LoadContent method.

The ViewFont object simply specifies the name of the font that we will use throughout the program to display text. You could add other fonts to the project and change this variable to customize the viewer.

I mentioned "Menu Mode" above. In fact, we will have two modes in our application: Menu Mode and Reader Mode. Our Update and Draw methods will check to see which mode the application is in and act accordingly. While we could do something like define constants where 1=Menu Mode and 2=Reader Mode, we will take a more "C#" approach, and use an enumeration.

An enumeration (or enum) is a series of potential values that basically result in our own custom type. When we define an enum containing our list of modes, we can then create variables of that type, assigning them to the modes we established. This sounds more complex than it is. As you can see above, we declared the "Modes" enum to have possible values of "Menu" and "Reader". We then created a variable called "CurrentMode" and set it to Modes.Menu, indicating that the program will start out in Menu Mode.

The remainder of the variables are mostly involved in keeping track of our place either within the menu or within the file we are viewing. I'll skip over these integer values here and address them when we use them later.

Besides those values, there is also another List object called "TextLines". We will use this when we load a text file to split the file up into single lines that we will display to the screen. It is simply a List of strings containing the line data.

Finally, if you have followed my other game tutorials, you will be familiar with the two float values calld KeyPressDelay and KeyPressTimer. We will use these to pace the input that the program receives so we aren't taking actions as fast as the game's Update loop runs.

The last of these declarations I'll talk about here is the "SaveLocation" variable, which is of type StorageContainer. This variable will be set to the location we will retrieve from the Framework where we can store "save games". In our case we will be storing information files, but the concept is the same.

Preparing for Testing on Windows

If you have done any type of "Device" development in the past, you might remember that Microsoft had a Device Emulator for Windows Mobile devices. When I first started thinking about XNA Zune development, I tried to track down the Zune Device Emulator to test my code on, since it is fairly inconvenient to deploy every single build to the device to try it out.

As it turns out, there isn't a Zune Device Emulator, but that's Ok! Since we aren't working with a completely foreign Framework like we would be in Windows Moble (after all, XNA runs on Windows and the XBox too) all we really need to do is set the screen size appropriately and we have a defacto Zune emulator for our purposes.

We are going to add a few lines to the Game1's Initialize() method to accomplish this. They aren't really necessary when running the project on the Zune, but they don't hurt anything either, so rather than use compiler directives to eliminate them when running on the Zune, I just leave them in place.

First, though, we need to make a Windows version of our project. This is actually very easy. On the Visual Studio menu bar, select the Project menu and click "Create Copy of [Project Name] for Windows". The project will be created and added to your solution.

You can make this the default execution project by right clicking on the project name (which will be called "Windows copy of [Project Name]") and select "Set as Startup Project".

So, back to our Initialize() method. Add the following before the call to base.Initialize() :

There is really nothing special here... this is the standard way we would set our desired resolution in XNA. We are just setting the backbuffer to match the size of the Zune display.

Helper Methods

There are a few things we need to be able to do during our project's initalization, and while we could simply pile all of the code into the LoadContent() method, I've split the functions out to helper methods to keep things more organized. It also allows for smaller chunks of code for discussion.

Here is the first one:

You will remember that I said in the declaration section that I was going to talk about some of the Integer values later on. Well, here is the first set.

All we are doing here is determining some basic properties of the screen we will be displaying to. We will need this information when determining how much text to put on a single line, or how many lines to put onto the screen.

We can retrieve the size of the display from the Viewport object. As you can see above, we use the height of the viewport to base our CursorBottom and LinesPerPage variables on, and the Width of the viewport to determine the width of a line of text.

The "CursorBottom" variable is what we will consider the lowest point on the screen to start drawing a new line of text. Any further down and the line will be partially cut off the display.

You may also see that we reserve 10 pixels on the right side of the screen for the "scroll bar" we will add later.

Our next helper method will let us find out what files there are to view on the device:

The first thing we do here is clear out the TextFiles List object. Strictly speaking this should not be necessary, since creating an instance of the List object results in an empty list. However, it is always good practice to make absolutely sure you are in a known state before doing anything with an object, so we'll clear it out (after all, in a program under windows we might have a way to change folders, in which case we could call this method multiple times).

Next we create a DirectoryInfo object and read the contents of the diretory indicated by "StorageContainer.TitleLocation" with "\Content\Text" appended to it. The StorageContainer.TitleLocation string is provided by XNA and points to where in the filesystem the application is installed to/running from. The result of this is that we get a DirectoryInfo object containing the directory where we will be storing our Text Files.

Finally we use a simple foreach loop to add all of the files in the directory to the TextFiles list.

This next method uses the XNA "Guide" object to find out where we can save files at runtime. On Windows and the Zune, executing BeginShowStorageDeviceSelector doesn't actually do anything that the user needs to interact with, and we can use a shortcut method of handling the result (which is returned immediately with a call to EndShowStorageDeviceSelector. This wouldn't work the same way on the XBox, however, since the user would be prompted to select the storage device (ie, disk drive or memory module) they want to use to store the game's save data. You would actually have to handle the asynchronous nature of the call on the XBox.

On the Zune, however, you simply get back a directory name that we can use. We call the device's "OpenContainer()" method and pass it the name we wish to use for our application. The result is a StorageDevice object that we save into our "SaveLocation" variable. We will use this later when we want to save data about where the user left off when reading a text file.

Our next two helper funcitons deal with saving file to and reading files from the location we just received via the FindStorageDevice() call. We want to be able to save the current line we are viewing in each text file so that when we reload that text file we return to the same place. In order to do that, we will need a way to save the information, and a way to reload it, so we have the following to functions (I'm putting them together since they handle the same files):

In the GetSavedLastLine() function we check to see if a file called "LastLoc_" plus the filename for the file we are loading exists. If it does, we use a StreamReader object to read the line number from the file. We use MathHelper.Clamp to make sure that the value we get back is at least within the limits of the text file we are reading.

The SaveCurrentLine() function simply does the opposite. We create the text file and write the current line number to it.

Loading Text Files

We've done a lot of background work, so lets get on to actually loading a text file into our TextLines list object. There is actually only a few lines of code in this function, but a lot of comments to clarify what is going on.

Essentially, we will open a text file and then use the GetOneLine() method of the TextHandler class that we added earlier to break it into individual lines. We simply keep processing the remainder of the file until we run out of text to handle.

Most everthing that I would explain here is covered by the comments in this code, so take a look at them. The most important things here are the handling of the special characers \r and \n. These characters represent a Carriage Return (\r) and a New Line (\n). We are really only interested in the New Line characters, so we strip out all \r characters from the outset.

When we hit a New Line, it is important to review hour our TextHandler methods will look at it. Recall that in our GetOneLine() method we treat a "word" containing a new line as a special case. we append a number of spaces equal to the number of \n characters in the word and drop the word completely.

This means that we can't have an actual word that ends in a \n character, which is going to be pretty common in text. Lets say we take that last sentance the way it looks in a text file : "... pretty common in text.\n". Our "text." would be dropped because it is part of the "word" that contains a newline.

So instead, we replace the "\n" character with a " \n" (a space before the \n) so that \n will always start a new word. The reason we replace the \n characters with spaces in the return value is that we check the length of the return value to determine how many characters to remove from the front of our work string before we continue processing.

The last thing we do in the LoadTextFile() method is call the GetSavedLastLine() method we added above to see if we should start somewhere other than the top of the file.

Lets LoadContent()!

Now that we have all of our Helper Methods in place, lets take a look at LoadContent(). Because we split almost everything out into helper functions, LoadContent() is going to be very simple, but we need to add a texture to our project first.

Normally at this point in my tutorials, I would create a sample texture and upload it for you to download and include in your project. I'm not going to do that this time. Lets put those art skills to work!

Right-click on Content in Solution Explorer and add a new folder called "Textures". Then, right click on Textures and click Add, New Item. In the Add New Item window that appears, select "Bitmap File" and call it ScrollBar.bmp.

When you do this, you will get an edit that looks a lot like the standard Windows "Paint" program, zoomed really far into a 48x48 pixel bitmap. In the Properties window for the new bitmap object, set both the Height and the Width to 1 (if you don't see a Height and Width property, you are probably seeing the Content Manager related properties. Double-click on the "ScrollBar.bmp" file name in Solution Explorer and the properties should change to the file properties.

Save your ScrollBar.bmp file and close it. Yes, we are going to be using a 1x1 pixel white bitmap as our scroll bar image. Even *my* art skills are up to that challenge, and I can barely draw a straight line.

Back in our Game1.cs file, lets set up our LoadContent() method to initialize the TextHandler, load our bitmap, and call our helper methods to get things set up:

Again, since we broke our actual setup tasks down to their own methods, LoadContent() becomes pretty straightforward.

The Update() Method

It is finally time to handle some user input. (I know, I know... we *still* haven't displayed anything onto the screen yet!). Our control scheme is fairly simple. We have two modes (or Game States if you want to call them that). Our controls are similar in both modes : The user can scroll up or down, page up or down, change between modes, or exit the program.

We will handle all of the input at one time, determining the command the user wants to execute, and then process that "command" based on the mode we are currently in.

The Update() method is a big chunk of code, but it is also fairly simple. We start by reading the GamePad and Keyboard states and storing them. We then check for various button/key presses and, based on what is pressed, determine a command to process.

Then it is simply a matter of translating the command into what we want to happen on the screen for each mode. Here is the Update() method itself. I'll take a bit more about it after the code.

One thing to note is the handling of the "NONE" command. Whenever we process a "NONE" command, we set KeyPressTimer to KeyPressDelay + 1, ensuring that the next time we process a command KeyPressTimer will be greater than KeyPressDelay.

Why? Well, we have the delay in there to prevent the screen from scrolling as fast as the Zune can process the Update event as soon as you touch the Zune Pad. But what if the user WANTS to scroll faster than the built-in delay? By writing it this way, we can allow the user to rapidly "tap" their commands. Each time they release the button the KeyPressTimer will "reset" allowing the next press to be detected immediately.

The Draw() Method

We are finally there. We have all the background work we need so all that is left is to display the results of our efforts to the screen.

Just like our Update() method, we will be handling two different modes (or States) with our Draw() method. When CurrentMode is equal to Modes.Reader we will be displaying lines from the current text file. Otherwise we will be displaying the list of text files to select from.

I'm going to paste the whole method here, and then talk about the interesting bits below.

We start by clearing the display to a black screen, and then start a SpriteBatch.Begin() call.

Next, we need to set our defaults for the TextHandler class for this interation of the Draw() method. We want to set our font, set the default drawing color to white, and position our virtual "cursor" at the upper left of the display.

At this point, we split depending on which mode we are in. In Reader mode, we start a simple While loop that will continue running for each "line" on the display (there are actually several ways we could have done this... a for loop from 1 to LinesPerPage would also work, but I wanted to use the CursorLocation check just to make some more use of the TextHandler.)

For each line we are going to print, we check to see of the line exists in our TextLines list. If it does, we use TextHandler's Print() method (which will take care of advancing the cursor to the next line for us) to display the line.

If we have gone off of the end of the text file, we simply print a blank space. Again, we could also just do nothing here and accomplish the same result if we were using a for loop, but since we are looping until we run out of display room, we need to print the blank line so the cursor moves down.

Our next step in Reader mode is to draw the scroll bar. Our 1x1 pixel white bitmap is going to do some extra duty for us here thanks to a few features of the SpriteBatch.Draw() method.

In our first spriteBatch.Draw() call we draw a yellow line from the top of the display to the bottom of the display along the right side of the screen. we can do this because when we specify the destination rectangle for the sprite to be drawn, it doesn't have to be the same size as the source (1x1 pixel) rectangle. SpriteBatch will stretch the image out over the destination area.

We can also use the last parameter of SpriteBatch.Draw() to tint our sprite. Since our bitmap is white, any color we specify in the last parameter will be the color for the whole "texture" when it is displayed.

The math comes next. We have to figure out how far down on the scroll bar to draw the position indicator, and how big to make it. The code looks more complicated than it is because of all of the type casting involved (we can't divide two integers and get a float, so we have to (float) both ReaderMode_CurrentLine and TextLines.Count and divide one by the other to get a percentage (ie, if we are at line 0 of 100, 0/100=0. If we are at line 50 of 100, 50/100 = 0.5).

We multiply this percentage by the height of the screen, resulting in the number of pixels from the top we will start drawing our marker block (after finally converting all of those (float)s back to an (int)).

The process to determine the height of the marker is similar. We divide LinesPerPage by TextLines.Count, giving the percentage of the file that a single page consist of (ie, if 10 lines fit on the screen and we have a 100 line file, 10/100=0.1). We multiply this by the height of the display to get the height of a single page relative to the height of the whole file (in this case, 320 * 0.1 = 32).

Lastly, we make sure that the marker is going to be at least 3 pixels high just so we can actually see it on long files.

All that is left to do now is to draw it. Again, we will be stretching our sprite over the required area and colorizing it, this time with Color.Red.

That handles Reader Mode, so the next thing to deal with is Menu Mode.

This time around (just for variety) we are going to use a for loop. We will loop starting at MenuMode_TopFileLine, and continue until we either run out of space on the screen, or reach the last item in the TextFiles list.

The only decision we have to make here is what color to draw the item in. If it is our "current" menu item (meaning that MenuMode_CurFileLine is equal to this item) we want to draw the item in Color.LightGreen to show it as hilighted. Otherwise, we will draw it with Color.White.

After we decide on a color, we simply use TextHandler.Print to print the entry and advance the cursor.

Add Some Files

The last thing to do is add some text files to view. Right click on Content once again, and add a new folder called Text. Now browse around and find some interesting things to put on your Zune as text files. Add each one of them to the Text folder and include them in your project.

In the Properties window, set the Build Action to "None" and set Copy to Output Directory to "Copy Always". We need to make these changes since we don't want Content Manager to try to process these items.

Fire It Up!

You should now have a working (though admittedly of limited use since you can't add files to the Zune outside of Visual Studio and redeploying your application) text file browser.

Going in and out of text files should store your current position so that when you return to that file later you start out at the same point.

Ideas for Expansion

As I have already said, due to the limitations of what we can actually place on the Zune, this application has a fairly limited usefulness potential. That said, there are a couple of ways you could make it fancier:

• Include a way to change fonts. As written, this would require rereading the current file since the file is split into lines when it is loaded based on the current font.
• Add the ability to rotate the display and read in "landscape" mode.

Here is my final project folder with a few text files that you may find familiar included: