A Dullard's Guide : simulator

Virtual Keyboards

Amy — Wed, 24 Oct 2007 10:33:00 GMT

The input tag has four options for mode: password, singleline, multiline or display. When an input element with singleline, multiline, or password mode receives focus, the player may launch an onscreen keyboard to allow user input or a software player may enable use of the computer keyboard. This is not required, though (currently, only the Xbox presents the user with a keyboard). And, there's no guarantee on how a player's keyboard will look and if they will implement all the keys you want. Maybe you want an alphabetical keyboard. Maybe you want “.com” and “.net” keys to make entering email addresses easier. If you need user input, your best bet is to use the display mode on your input tag and implement your own virtual keyboard.

The project at the end of this blog has 3 sample virtual keyboards to choose from - alphabetical (for me), QWERTY, and Dvorak (for Chris). They all use the same markup, styles, timing, and script files. Only the markup files are different.

Here's a sample of what the "A" key looks like:

</div>

class
The parent div has a class attribute. A class is a way to group similar elements. It doesn't apply a style like the same attribute would in HTML. Class is used here to group which elements are hid or shown when the shift button is actioned. Class is also used to group all the keyboard keys so only one cue is needed for all buttons with the class applied.

</cue>

Custom Namespace
The buttons of the keyboard also have a "custom:key" attribute. The markup is extensible and custom attributes can be added if you add the namespace to the root element of the document.

xmlns:custom="http://custom"

This allows us to pass custom information on the button that has been actioned to the script by calling getNamedItem on the target of the action

var element = evt.target;

var attr = element.attributes.getNamedItem("custom:key");

var key = attr.value;

accessKey
Adding accessKey to a button adds a shortcut to actioning that button. This is particularly useful for the number keys because it allows users to navigate the keyboard or use the number panel on the remote. Note that for the letter keys, only keys A, B, C, and D are required to be supported. Letters E-L are optionally supported. Letters M-Z are not supported.

computeImplicitNav
As I stated earlier, shift is being handled by hiding or showing uppercase or lowercase classes. By setting style:display to none, the disabled keys are removed from display. However, changing a key's display from none to auto does not automatically add the element to the keyboard's navigation. So, when display has been updated, an event is sent to the script and computeImplicitNav re-calculates the keyboard's implicit navigation.

HD DVD Script Object Model

Amy — Wed, 24 Oct 2007 09:23:00 GMT

Have you ever been working on an HDi project and needed to look up a method name in Annex Z, but you don't have it handy (or access at all)? Well, luckily the Interactivity Jumpstart Kit ships with the HD DVD Script Object Model as a Visio file and a PNG. You'll find this very useful file in C:\Program Files\HD DVD Interactivity Jumpstart\Documentation.

And, while you're in there, check out the CHM file. It has all the command line options for the simulator and the validator, keyboard mappings, and information on how to use the CreateACA and CreateDiscID tools.

Good stuff.

Dynamic Content

Amy — Thu, 18 Oct 2007 19:01:00 GMT

Today's sample was created upon a request from my very nice and hard working office-mate Chris. Last week Chris began learning HDi. He whizzed through all the Jumpstart samples and the projects on my blog, and jumped into creating a project that would dynamically generate content on the fly. After messing around with his project for a few days, Chris said I should write a blog how to do this for other people who had questions like his. So, here it is.

There is a sample project is attached at the end of this blog. In this project, an XML file is parsed, data is extracted using XPath, text is dynamically added to the markup, and new "skins" are applied to the data by changing the loaded markup file.

XML Data
Let's say you have a project where you want to separate your data from your presentation layer. Maybe you want to download new content from the network. Maybe you want to be able to apply different skins to the same piece of content. The obvious way to separate your data is by using XML.

<?xml version="1.0" encoding="utf-8"?>

<data>

<paragraph>Lorem ipsum . . .</paragraph>

</data>

In this project, the data is in a file called data.xml and it is included with the project.

XMLParser
Before the application does anything with this XML, we need to use the XMLParser to create a DOM.

XMLParser.parse(uri, parseCallback);

function parseCallback(status, dom)

{

if (status == XMLParser.OK)

{

//do something with dom

}

XMLParser.parse takes two arguments - uri is the full path of the xml file (file:///dvddisc/ADV_OBJ/data.xml in this project) and the callback function which is called when the XMLParser has completed and is ready to return the DOM.

XMLParser also has a method called parseString which will create a DOM from a string. The parseString function returns the DOM directly without the callback.

var dom = XMLParser.parseString("<data><headline value=\"This Is The Header\"/></data>");

This can be very handy to use if your XML comes from getResponseString() from a network request or if you want to create a new empty DOM on the fly. (For more information on networking, read http://blogs.msdn.com/amyd/archive/2007/09/20/very-simple-network-example.aspx)

evaluateXPath
There are a couple of ways to can go through the newly created DOM. We could cycle through all the childNodes using DOM Level 2 ECMAScript Language Binding. Or, we can use XPath. (Note, Xpath axes are not supported). In this project, I've chosen to use some simple XPath calls to extract my data using evaluateXPath.

var nodes = dom.evaluateXPath("//headline", dom.documentElement);

evaluateXPath returns a nodeList. Since I know I'm only expecting one headline here, if I do get a non-empty nodelist, I only need the first item and its value attribute.

var headline = nodes.item(0).getAttribute("value");

The call to evaluteXPath for paragraph from my DOM will return more than one node. Also, the data here is in a text node, not an attribute. This text node is the first child of the paragraph tag and its contents can be retrieved by calling nodeValue.

for (var i = 0; i < nodes.length; i++)

{

// do something with nodes.item(i).firstChild.nodeValue;

}

I could go back to this DOM every time I need to get this data, but my application would take a performance hit. So once I get my data, I cache it for use later.

Adding Text to Markup

Okay, the XML has been parsed and data cached, so now we can put it in the markup. Here we will use the DOM Level 2 ECMAScript Language Binding to create new paragraph tags (elements that can hold text) and text nodes inside.

function addText(element, txt)

{

var p = document.createElement("p");

var text = document.createTextNode(txt);

p.appendChild(text);

element.appendChild(p);

}

And, of course once this is complete, we load the changes to the modified markup by calling document.load. For more information on why you need to call document.load, read Peter Torr's blog on Live vs. Load DOM.

Switching Between Markup Files
And, finally, just for kicks, I've added the ability to load new markup pages in order to reskin the data using the link() function.

Happy Programming!

Launching the Simulator from Visual Studio

Amy — Tue, 15 May 2007 20:45:00 GMT

When you're building your HDi applications, you can use the BUILD_PROJECT.BAT file you downloaded from my last post to create your aca file and launch your project in the simulator in one simple step. But, now, let's cut that double clicking down to one single button press in Visual Studio.

First, we need to add our batch file to the list of external tools used by Visual Studio. From the "Tools" menu, choose "External Tools...".

In the dialog that appears, click the "Add" button to add a new External Tool.

I've named my tool "Build HDi App". The command maps to the full path of the BUILD_PROJECT.BAT file in my solution. I'm not passing any arguments in. And, I've hard-coded the full path of the Initial directory to the ADV_OBJ folder in my solution's directory. If you wish, you can modify your batch file so you can take advantage of the Arguments field or make the Initial directory generic so you use just one batch file for all your HDi projects.

You can now run this batch from the "Tools" menu. Note that in this example, "Build HDi App" is the 6^th External Tool in this list (I'll explain this later).

But, to make it even more convenient, let's put a button to launch this in the toolbar. From the "Tools" menu, choose "Customize..." In the Customize dialog, click on the Commands tab. Under Categories on the left, click on Tools. Under Commands on the right, click on your external tool and drag it up to your toolbar of your choice (you can add it to one of the existing toolbars, or create one of your own).

Here, I know that my batch file is under External Command 6, because it was the 6^th External Tool in my list as noted above. But to figure this out, you can also click on the "Rearrange Commands" button and in the dialog that appears, select "Tools" from the Menu Bar drop down menu to get the view below. Since "Build HDi App" in the Tools menu appears just above "External Tools...", I know that "External Command 6" is the one I'm looking for. This is also a useful dialog if you'd like to rename the items or put an image on the menu item or button.

The example I've shown here works well if you are currently working on a single HDi application. But, you can modify your batch file and the arguments passed in by the tool dialog to customize your environment to work better for you. Or, you could just create a button for each application you're working on. Customize your development environment to suit your needs.

Have you noticed I like Batch Files?

Amy — Mon, 14 May 2007 17:50:00 GMT

I am a big fan of automating where I can. I am not a big fan of remembering command line arguments. I prefer to double-click whenever possible.

In my last post, I went over how I generated an aca using a batch file. Using the aca means that I can add resources to my project whenever I want without having to modify my playlist or my manifest. But, now I want to take it one step farther. I want the batch file to create my aca and I want it to launch my project in the simulator. And, it turns out that it's a simple addition of one line at the very end:

"C:\Program Files\HD DVD Interactivity Jumpstart\HDDVDSimulator\HDiSim.exe" -nosize -debug -p ../

I'm using a few command line arguments of note here. "-nosize" tells the simulator that it can ignore the size I enter for the resource in the playlist. I can't ignore this value forever - before the final version goes to disc, I have to put the correct value in the playlist, but I don't want to bother with this value during development. "-debug" tells the simulator to give me debug messages in the status bar at the bottom of the window. I find this very helpful when things are working like I expected them to. If you're doing a lot of script work, you might consider using "-jit" - more on this at a later time. "-p " is used to tell the simulator the project that I want to run. Since I'm adding this to the CREATE_ACA.bat file in ADV_OBJ, I use "../" as the project location so that the simulator loads this project from one level higher (which is considered to be the dvddisc directory).

Okay, now "CREATE_ACA.BAT" isn't really a good name for this updated batch file because it is also opening my project. "BUILD_PROJECT.BAT" is attached at the end of this post. I keep a copy of this batch file in all my ADV_OBJ folders. Whenever I modify a file in my project, I can double click this file to re-generate my acas and launch my project in the simulator.

In my next post, I'll show you how to add a button to your Visual Studio toolbar to run this batch file.

ACAs are Your Friend

Amy — Wed, 09 May 2007 22:51:00 GMT

As you have noticed, every resource that you use - script, markup, images, audio, etc - must be listed as a resource in both the playlist and the manifest. As you can imagine, this quickly becomes painful as your applications grow in size. This is where ACA files come in very handy.

ACAs are simply archive files. There's no compression, just grouping. There are several benefits in using ACAs for you project. First, you don't have to list out all the resources individually. Instead, you will have only one resource - the aca file itself - listed in your playlist and manifest. Second, the player will have a lot fewer seek operations to perform because it only needs to load your aca as a resource and not all the individual files, so your application will load faster. Third, the player will be able to make better use of its available storage because rather than assigning individual assets to blocks and wasting space, there is only one aca file to load, so less wasted space.

Referencing an ACA as a Resource
Lets' suppose we want to change the Hello World application (C:\Program Files\HD DVD Interactivity Jumpstart\Samples\HelloWorld\ADV_OBJ) to use an ACA that we've created called hello.aca (more on creation later) which contains all the files needed for the Hello World application (font.ttf, manifest.xmf, markup.xmu).

Our playlist (VPLST000.XPL) title application reference used to be:

</ApplicationSegment>

Will be changed to:

</ApplicationSegment>

Our manifest (manifest.xmf) resource list used to be:

Will be changed to:

Referencing Files in the ACA

Notice that when you reference a file within the aca - like the manifest reference in the title application from the playlist above - you treat it as if it were a folder. When you want to reference the manifest.xmf file with in hello.aca, you use file:///dvddisc/ADV_OBJ/hello.aca/manifest.xmf.

ACAs contain files, not directories. All files within your aca must be at the same level.

Correct: file:///dvddisc/ADV_OBJ/hello.aca/manifest.xmf

Wrong: file:///dvddisc/ADV_OBJ/hello.aca/subdirectory/manifest.xmf

Before you create your ACA, you will want to make sure your references within your manifests and markup files are correct. One of the easiest ways to ensure your references are correct is to use relative references instead of absolute whenever possible. In the Hello World application, notice that the reference to the markup file "markup.xmu" within the manifest is relative and so is the reference to the font "font.ttf" within the markup. The reference that must be absolute, however, is the reference to the ACA as a Resource within the manifest.

Correct:
<Resource src="file:///dvddisc/ADV_OBJ/hello.aca" />

Wrong:
<Resource src="hello.aca" />

The references to the manifest for the application and aca resource in the playlist must be absolute as well.

Creating an ACA

There are several different tools that you can use to create an ACA. For development purposes, you can use the CreateACA.exe command line tool that comes with the HD DVD Interactivity Jumpstart. This tool doesn't support AACS, so you probably won't want to use it for final aca, but it's very helpful for development. You can find this tool in C:\Program Files\HD DVD Interactivity Jumpstart\Tools.

There are two ways you can use this tool to create an ACA. As part of the command line arguments, you can list out the files that should be included inside the aca. Alternatively, you can pass a text file with the list of files to be included.

To create an aca using the list of files as command line arguments, open a command line prompt in the HelloWorld\ADV_OBJ directory and enter the following...

"C:\Program Files\HD DVD Interactivity Jumpstart\Tools\CreateACA.exe" -c hello.aca markup.xmu font.ttf manifest.xmf

To create an aca by passing in a text file, put the following in a text file called temp.txt in the ADV_OBJ directory

markup.xmu
font.ttf
manifest.xmf

And run the following from the command line:

"C:\Program Files\HD DVD Interactivity Jumpstart\Tools\CreateACA.exe" -f hello.aca temp.txt

Using a Batch File

Of course, we don't want to hand type this temporary text file for every project and then have to update it for each new resource. Instead, we're going to use a batch file to create this temp.txt file and generate our aca for us.

In the HelloWorld\ADV_OBJ directory create a folder called "hello". I like to use a folder with the same name as my aca.

Move your application files (manifest.xmf, markup.xmu, and font.ttf) into the hello directory.

Open manifest.xmf and change the resource tags as show above.

Open up your text editor and enter the following (or download the file at the end of this post):

@ECHO OFF
 
::******************************
::
::SET YOUR DIRECTORY NAME HERE
::
 
set DIR_NAME=hello
 
::
::******************************
 
:loop through that directory to create a list of files
FOR %%f in (%DIR_NAME%\*.*) DO echo %%f>> temp.txt
 
:create an aca that matches your directory name
"C:\Program Files\HD DVD Interactivity Jumpstart\Tools\CreateACA.exe" -f %DIR_NAME%.aca temp.txt
 
:delete the temp text file
DEL temp.txt
 

Save this as CREATE_ACA.bat in your HelloWorld\ADV_OBJ directory.

Now you can double click on this file to quickly generate an aca.

Just copy this file to your other projects and change the "DIR_NAME" setting at the top to generate ACAs for those projects too.

Installing HD DVD Interactivity Jumpstart on Vista

Amy — Sun, 15 Apr 2007 01:10:00 GMT

You were so excited about the Vista launch that you preordered your copy of the new operating system and are now basking in the beauty of improved interactivity and security, only to find that when you try to install the jumpstart package you get the "Microsoft Interactivity HD DVD Jumpstart requires a Windows XP operating system with Service Pack 2 or higher” message. As an HDi developer, I wasn’t so pleased at this. I want to use Vista AND write HDi! Apparently there are a handful of issues running on the simulator on Vista like rendering of fonts. But, if you don't need fonts on your project, then most everything else works. So, here's how you get around that pesky error message that stops you from doing your installs

Go download the HD DVD Interactity Jumpstart and Sample Code installs and save them to your desktop. Download the batch file included at the end of this post in the same location as the two .msi files. Double-click on the batch file and follow the instructions. Done.

You want to know what this batch file is doing exactly? Okay...

First, it extracts the contents of the install files by calling...

msiexec /a HDDVDJumpstart.msi TARGETDIR="C:\Program Files\Microsoft HD DVD Interactivity Jumpstart"

msiexec /a HDDVDSamples.msi TARGETDIR="C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\Samples"

For consistency's sake, I am replicating the install as it would occur on XP, but you can extract wherever you'd like. Now, you could certainly stop here, but again, for consistency's sake, I'm duplicating what happens on XP, so now I create the Start menu shortcuts.

mkdir "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Microsoft HD DVD Interactivity Jumpstart\HD DVD Simulator\Samples"

opening the location in Program Files...

explorer "C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\HDDVDSimulator"

Now, it tells you to manually create a shortcut to the HDiSim.exe file by right clicking and chosing "Create Shortcut"

Then it will move that shortcut to the start menu folder and create a copy for each of the samples...

move "C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\HDDVDSimulator\HDiSim - Shortcut.lnk" "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Microsoft HD DVD Interactivity Jumpstart\HD DVD Simulator\HD DVD Simulator.lnk"

copy "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Microsoft HD DVD Interactivity Jumpstart\HD DVD Simulator\HD DVD Simulator.lnk" "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Microsoft HD DVD Interactivity Jumpstart\HD DVD Simulator\Samples\HelloWorld.lnk

and finally, it open up the samples folder in the start menu…

explorer "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Microsoft HD DVD Interactivity Jumpstart\HD DVD Simulator\Samples"

and asks you to manually update the target for each of the shortcuts

Advanced Techniques
"C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\HDDVDSimulator\HDiSim.exe" -p "C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\Samples\AdvancedTechniques"

Button
"C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\HDDVDSimulator\HDiSim.exe" -p "C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\Samples\Button"

Chapters
"C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\HDDVDSimulator\HDiSim.exe" -p "C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\Samples\Chapters"

Hello World
"C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\HDDVDSimulator\HDiSim.exe" -p "C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\Samples\HelloWorld"

Rotating Menus
"C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\HDDVDSimulator\HDiSim.exe" -p "C:\Program Files\Microsoft HD DVD Interactivity Jumpstart\Samples\rotatingMenus"

And now you are ready to run HDiSim on Vista! Again, there is an issue with font rendering which will cause it to crash, so try to avoid that. As you encounter issues on Vista, please leave a comment here and I will funnel the information to the correct people. Now, go have some fun!

Getting Started with HD DVD

Amy — Thu, 12 Apr 2007 09:29:00 GMT

So, you've been tasked with creating a menu for an HD DVD and don't know where to start. Lets start out by getting the (free!) Microsoft HD DVD simulator and some sample code installed on your machine.

Hardware Requirements

First, let's make sure you have the right computer. You will need to be running Windows XP SP2. Full support for Vista is not quite ready yet (although you might possibly be able to run the binaries on your Vista install - more on that later). You will need at least 512 MB RAM (1 GB+ is better) and a video card with 256 MB of video RAM.

Software Prerequisites

Before we install the simulator, there are a few prerequisites. You will need the lastest version of Windows Media Player (but at least WMP 10), Internet Explorer 7, and .NET Framework 2.0.

Simulator Install

Now we're ready to install the HD DVD Interactivity Jumpstart Package. By default, it will install at C:\Program Files\HD DVD Interactivity Jumpstart, but you can put it anywhere. This will also install some of the older, more simple samples like Hello World, Chapters, and Buttons.

And, finally, lets install the advanced Sample Code - Rotating Menus and Advanced Techniques. The Jumpstart install above includes a folder called Samples (C:\Program Files\HD DVD Interactivity Jumpstart\Samples) - if you put your Jumpstart install somewhere other than the default location, look for that Samples folder.

Okay, now we're ready to see some of these samples in action! Go to...

Start > Programs > Microsoft HD DVD Interactivity Jumpstart > HD DVD Simulator > Samples

And, check out...

Rotating Menus Sample - use the left and right arrows to navigate

Advanced Techniques Sample - use the arrow up key to bring the menu into view, and arrow left/right/up/down to navigate

So, now you're probably itching to get started on some apps of your own. I will be blogging more soon, but in the meantime, take a look at Peter Torr's blog on HD DVD.