Building a Custom Border

All the information you need to create skins, borders, HTMLView, embedded Player controls, and programs using the Player API is contained in the Windows Media Player SDK. To try the samples in this topic, all you need are the Player and a text editor program, such as Microsoft Notepad.

To create the border, we will follow this process:

1. Create the artwork, design the border, and build the components.

2. Write the script. Using the script reference and samples in the SDK, write the skin definition file that associates the artwork to the Player API.

3. Package the border. Create the final file that the end user will download.

4. Deliver the border to the end user by adding a link to the Web page that downloads the border.

Creating the Border Artwork

The first step in creating the border is laying out, designing, and implementing the artwork that will become the border. To do that, you need to determine an optimum size for the border in the Now Playing pane, the size of the video frame, and the sizes and positions of the other elements in the border.

The border sample provided in the Windows Media Player 9 Series SDK describes a method for creating a border that is resizable, so the digital media and art elements will display correctly if the end user resizes the Player. Contoso, however, will use fixed-size elements because they want the video, text, buttons, and branding to display in a particular way.

The artwork consists of three files:

• Background file

• Mapping file

• Hover image file

The background file, shown in figure 10.9, is a simple bitmap image file that contains the basic design and layout of the border. The colors used in the background are intentionally subdued, so the background does not compete visually with the video.

Figure 10.9: The background file used for the Contoso border.

The skin definition file containing script, which will be created later, will add the video, text, functionality, and hover and mapping images to the background. To locate those components on the background, Contoso’s artists will use a graphic design program to carefully measure the areas of the background where they will be positioned. For example, they know the area where the video will be displayed is 61 pixels in from the left edge, 35 pixels from top, 176 pixels high, and 320 pixels wide.

The hover image file, shown in figure 10.10, is a simple bitmap image that shows the two buttons as they will appear when an end user moves the mouse pointer over them.

Figure 10.10: The hover image file.

The only areas of the image that will be seen are the tiny areas around each button. The content of the rest of the image does not matter. However, the size of the image and the position of the buttons must be exactly the same as those of the background. To accomplish that, the Contoso artists use a graphics program that enables them to create images in layers, such as Adobe Photoshop or Jasc Paint Shop Pro. Then they can build all the elements of the border or skin in one image file, and be assured that the elements are correctly aligned.

The mapping file, shown in figure 10.11, is a bitmap image that identifies areas of the image to which they want to add functionality.

Figure 10.11: The mapping file used to identify interactive areas of the border.

None of this image will be visible to an end user. The two colored rectangles positioned over the buttons are used by the Player to map the areas on the interface to functions in the script. Mapping is implemented in script using the color value of a colored region in the image. The area on the left is green and has a color value of #00FF00. The red area on the right has a value of #FF0000. Those color values are used to create the script.

Writing the Border Script

The script in the skin definition file is interpreted by Windows Media Player when it opens the border file. The script is written using the skin programming elements described in the Windows Media Player SDK to integrate the image files and add functionality to the border. We will not go into detail about how to script skins in this book. If you want to explore those topics and many more dealing with programming the Player, see the Windows Media Player 9 Series SDK.

The skin definition file created by Contoso contains the following script:

<THEME     id = "ContosoMoviesOnline"     author = "Contoso Movies Online"     copyright = "(c) 2002 Contoso, Inc.">     <VIEW         id = "View1"         backgroundColor = "#000000"         backgroundImage = "MObg.bmp">     <PLAYER         openstatechange=             "Info.value =              player.currentMedia.getItemInfo(‘Description’);" />     <VIDEO                  left="61"         top="35"         height="176"         width="320"         stretchToFit="true">     </VIDEO>     <BUTTONGROUP         mappingImage = "MObg-MAP.bmp"         hoverImage = "MObg-HOVER.bmp"         horizontalAlignment = "left">          <BUTTONELEMENT             id = "RentNow"             mappingColor = "#00FF00"             upToolTip = "Rent Now!"             onClick =              "JScript: player.launchURL(                 ‘http://Contoso.com/RentPage.asp’); " />         <BUTTONELEMENT             id = "Details"             mappingColor = "#FF0000"             upToolTip = "Movie Details"             onClick =                  "JScript: player.launchURL(                 ‘http://Contoso.com/MovieDetails.asp’);" />     </BUTTONGROUP>     <TEXT                    left = "60"         top = "15"         foregroundcolor = "#C7BD03"         fontSize = "8"         fontStyle = "bold"         value = "wmpprop:player.currentMedia.name" />     <TEXT                    left = "60"         top = "217"         width = "160"         height = "26"         foregroundcolor = "#E5AFD8"         fontSize = "8"         value =              "JScript:player.currentMedia.getItemInfo(             ‘Description’);"         wordWrap = "true" />     </VIEW> </THEME> 

The skin definition file, Border.wms, is included on the companion CD along with the sample image files.

The instructions in the skin definition file are written in Extensible Markup Language (XML), which is similar to HTML. If you have used HTML to create Web pages, you will find that XML looks familiar. In general, XML scripting is used to set or retrieve the properties of elements. For example, the Contoso script describes the location and size of the video frame by setting left, top, width, and height properties. In scripting for skins, the API enables you to describe actions you want the Player to perform (methods), and to use actions generated by the Player (events).

To script a method or event, the examples shown here use Microsoft JScript. For example, in JScript you can assign the launchURL method to the onClick method of a skin button in the script:

onClick = "JScript: player.launchURL(‘http://WebSite’);" 

When a user clicks the button, the Player opens a browser to the Web site indicated in the URL. If you want to add more complex functionality to the script, you can assign a JScript file to the skin definition file that contains additional lines of code. For example, you could create a multi-line JScript function that is called from an onClick event handler.

The following descriptions provide an overview of the elements that are used in the sample script:

• VIEW elements contain the user interface details of a skin or border. Using VIEW, you can set the background image file or define a background color (black) for those areas not covered by the image file.

• PLAYER elements contain script that communicates directly with the Player. Most PLAYER elements are events, which are messages sent by the Player that can be used to trigger a method in a script. For example, in the Contoso script, the Player sends an openStateChange event, which triggers the method getItemInfo that gets the description text embedded in the current file or stream.

• VIDEO elements provide ways to manipulate a video window in a skin. For example, the Contoso script defines the location and size of the video window, and specifies that the Player should stretch the video (if necessary) to fit the defined size.

• BUTTONGROUP elements define a group of buttons. In the Contoso script, the hover image and mapping files are set with this element.

• BUTTONELEMENT elements define one or more buttons in a BUTTONGROUP. Rather than define the button area using location and size values, skin definition files use color values in the mappingImage file. After setting the mappingColor value for a button, the button is then defined as the area or areas with that color value on the mapping image. When an end user moves the mouse pointer over a defined area, the same area on the hover image file shows through and a ToolTip appears. When an end user clicks the area, the onClick method of the button is called.

• TEXT elements define how and where text appears on a skin or border. On the Contoso skin, one TEXT element places the name of each clip above the video window; another TEXT element places the description text embedded in a clip in an area below the video window. The other attributes in the TEXT elements define the size and location of the TEXT areas, and how you want the text to appear.

To create the skin file, create a folder on your computer that contains the following elements:

• The skin definition file, Border.wms.

• The background image file, MObg.bmp.

• The hover image file, MObg-HOVER.bmp.

• The mapping file, MObg-MAP.bmp.

These elements comprise the skin. If you double-click Border.wms, the Player will open and interpret the file, and the Player skin will change according to the definition in the script. In the Contoso case, however, the skin does not contain the usual skin functions, like play and stop, because Contoso will be using it as a border. In the next topic, we will follow the steps for creating a finished border, which is a Windows Media Download Package file.

Packaging the Border

To create border files, you follow a process of combining sets of files into single compressed files with a .zip file name extension. Then the end user only has to download one file that contains all the pieces. The end user does not need to do anything with the file, such as extract the individual files and install them. The Player downloads and reads the compressed file, and then handles the installation automatically.

The only additional file needed for the Contoso border is a Windows Media metafile that contains the playlist. To create the Windows Media Download Package that will implement the Contoso border, the designers do the following:

1. Create a compressed file that includes the four files that comprise the skin. The compressed file will have a .zip extension.

2. Change the .zip extension to .wmz (For example, Border.wmz). If you were to double-click the file, the Player would open and install Border.wmz as a skin.

3. Create a Windows Media metafile that embeds the skin as a border. The metafile contains links to the digital media that will play in the border, as well as a SKIN element that references Border.wmz. You can use a text editor to type the metafile script, and then save it with an .asx extension (for example Border.asx). The following script shows an example of a metafile with three playlist entries.

   <ASX VERSION = "3.0">     <SKIN HREF = "Border.wmz" />     <TITLE>Contoso Movies Online</TITLE>     <ENTRY>         <REF HREF = "mms://WMServer/Trailer01.wmv"/>         <PARAM NAME="Prebuffer" VALUE="true" />     </ENTRY>         <ENTRY>         <REF HREF = "mms://WMServer/Trailer02.wmv"/>         <PARAM NAME="Prebuffer" VALUE="true" />     </ENTRY>     <ENTRY>         <REF HREF = "mms://WMServer/Trailer03.wmv"/>     </ENTRY> </ASX>

   The PreBuffer parameter is used for seamless stream switching. If an ENTRY element contains this parameter and it is set to “true”, the Player will begin to buffer the beginning of the following ENTRY before the current ENTRY ends, so the transition to the following file or stream will be as quick and will use as little buffering as possible.

4. Create another compressed file that includes the .wmz and .asx files. Change the .zip extension to .wmd, which makes this a Windows Media Download Package file. When an end user double-clicks this file, the Player starts, displays Border.wmz as a border, and plays the files in the .asx playlist. To make a complete download package, you can include the Windows Media files in Border.wmd, and then change the REF HREF values to reference the files locally, such as:

   <REF HREF = "Trailer01.wmv"/>