[HTC Excalibur] Cyclonezephyrxz7:
CPR File Editing
​

For the HTC Excalibur/S620/T-Mobile Dash

In this tutorial, you will learn how to safely, and effectively, modify the HomeScreen CPR File on your phone.

This tutorial will be based off of the Windows Mobile 6.5 Titanium_320x240.CPR file (found in Ookba's 3VO 2.8 ROM)

First off, make a backup of your current .CPR file (located in /Windows) to a separate folder, or duplicate it. This is in case something goes wrong. (Do the same for the .home.xml file located in /Application Data/Home)

[Pre-Tutorial] - A Couple of Handy Apps

(This is updated as recommendations come by)

1)Free XML Editor - Here - hewhoisnotasothers

2)Notepad++ - Here - Me

[Tutorial Part 1] - Intro to the CPR file.

The Windows Mobile CPR file is located in the /Windows folder on your phone. This file controls the positioning, sizing, and some effects applied to text and image objects present on the Today Screen. While its extension is CPR, it can be opened by any text editor, and edited like any XML. After editing the CPR (and placing it in the /Windows folder) you must run a program (included in Ookba's ROM's and which can be found by searching) called TitaniumRefresh which reloads the Today Screen. This tutorial assumes you know the basics of the XML language, so if you do not, it is recommended you visit this link.

[Tutorial Part 2] - A First Look: Opening and Analyzing

To open the CPR file, I use Notepad++ (which can be found here). Alternatively, you can use Notepad or any other text editor. After opening the file, we see it starts with <form>, like any XML will. Scroll down a couple lines, and look at the first chunk of code.

<Image ID="Background" Opacity="1.0" Top="-54" Width="320" Height="240" Source="ConfettiPlus::WallpaperBitmap"/>

<Layer ID="StaticHomeArea" Visible="False" />

​

Let us break this down. First off, I colored Image and Layer RED. For the rest of the tutorial, I will refer to these RED colored texts as "tags" (as they are referred to in XML). The Image tag, much like HTML, will create an image on the Today Screen. The Layer tag will tell the Today Screen to move UP a layer and start putting newly inserted objects ABOVE all previously created objects. In this case, anything declared after this snippet of code will be put over the "Background" Image.

The text in DARK BLUE will be referred to as "ID's" (coming straight from their name). ID's will be covered later on, but basically they interact with either the Registry or the files used to create a panel. These are essential to any CPR file.

The text in LIGHT BLUE will be referred to as "parameters" (because they define specific details about the tags). Look at the Image tag. The use of the parameter is to tell the Today Screen exactly what to do. Without the Width or Height parameters, how would your phone know how big to make the image? Most parameters are self-explanatory because of their names, but as I see that some may become confusing, I will point them out. For instance, "Top". The function of Top, in any case, is to define how far from the top of the defined layer the object should be placed.

[Tutorial Part 3] - The .home.xml file

Before getting any deeper into the CPR file, lets see some background on it. How does the Today Screen know which panels to place where, and what the Background is? After all, the image tag for background had some gibberish about Confetti!

Now then, go to /Application Data/Home/ and pick out any .home.xml file with the name Titanium. (I will be using my own slightly modified Horizon.home.xml file from my Horizon Skin). Just like the CPR file, open this up with a text editor. Notice the first couple of lines just talk about who made the theme, and where it is located. We can ignore that for now, as it is not essential. Look now at this snippet of code:

<default target-width="240" target-height="320" font-face="Segoe Condensed" font-size="19" font-weight="bold" padding-left="5" padding-right="5" bgcolor="transparent" fgcolor="COLOR_HOMETEXT" padding-top="3" b-border-color="COLOR_HOMERULE" b-border-width="0">

<format state="selected" fgcolor="COLOR_HOMEHIGHLIGHTTEXT" />

</default>

​

The default tag is describing to the Today Screen what the default screen orientation is. It is telling it to have a width of 240 pixels and a height of 320 pixels. It is telling it to set the default font to Segoe Condensed, size to 19, weight/style to bold. It is also telling it to leave some space on the top/bottom and sides of the screen (5 pixels) so that you don't get objects cut off by the edge of the screen. It is telling it to have no background color and the Foreground color is defined later on by a variable COLOR_HOMETEXT. Same principles go for the format tag.

Move on to the next snippet of code:

<background bgimage="\Program Files\Horizon\BGIMG.jpg" bgimage-rotated="\Program Files\Horizon\BGIMG.jpg" valign="bottom" bgcolor="COLOR_TRAYGRADLEFT" />

​

Just from the tag, you can see how this is related to the background tag in the CPR file. So all that confetti jargon is really just telling it to look here (for the initial setup that is. The value in the registry is changed when the background is changed). So this tag is telling the Today Screen to set the image at "\Program Files\Horizon\BGIMG.jpg" as the default background. Since there is currently no way (as far as I know) to change the screen orientation, the bgimage-rotated is the same as the bgimage. "valign", which should sound familiar, is set to the bottom, and bgcolor is set to the variable COLOR_TRAYGRADLEFT.

So what are these variables exactly? Lets see:

<scheme>

<color name="COLOR_TRAYGRADLEFT" value="#000000" />

<color name="COLOR_HOMEHIGHLIGHT" value="#4683af" />

<color name="COLOR_HOMEHIGHLIGHTTEXT" value="#C0C0C0" />

<color name="COLOR_HOMETEXT" value="#FFFFFF" />

<color name="COLOR_HOMERULE" value="#4683af" />

<color name="COLOR_HIGHLIGHT" value="#4683af" />

</scheme>

​

Scheme, which is not an evil plot in this case, refers to the color presets for the phone's theme. Those variables I mentioned earlier are defined here. The value (which is the color value) is written in HEX-HTML code. It goes from 00 - FF, where F is the greatest, 0 the least, and is written in 2's. so COLOR_TRAYGRADLEFT has 00, which is 0 RED, 00, which is 0 GREEN, and 00, which is 0 BLUE. These aren't too important unless you are doing a whole theme makeover for your phone.

Below that you may have a plugin tag with the "name" parameter equal to iconbar. You won't deal with that much. So look at the next plugin tag, which is titled "name = Bronze". Lets look at that:

<plugin clsid="{E9267CAB-02EE-4f37-8216-6BF6A8FF5A71}" name="Bronze" height="266">

<Plugins Order="CMyPhotos;CMusic;CLinks;CLauncher;CComm;Settings;TitaniumWeather;CClock;CHome;CAppointments;CPhone;CText;CMessage;CEmail;CVoicemail;CWindowsLive" CPRFileName="Horizon" />

</plugin>

​

This is the big one. Here you can see, from the plugin tag, that the Plugins (or more commonly called Panels) are given 266 pixels of space on the homescreen. Below that is the Plugins tag, which very nicely tells us what the order, from top to bottom, is for the Panels. This is how the Today Screen knows how to put what where! Notice that the parameter "CPRFileName = "Horizon"" in the example. This changes depending on the CPR being used. This gives users the choice to run either their own theme or the default theme provided without having to delete any other CPR files.

[[CONTINUED IN NEXT POST]]
​