PocketCM

Your mobile at your fingertips
Google
You are not logged in.

Customzing PocketCM Contact

You need PocketCM 0.16 or above in order to customize PocketCM this way.

Basic concept

There is 2 way of customizing PocketCM:
  • By editing a settings.ini file in the PocketCM folder
  • By creating a theme

Editing a settings.ini file

Basic idea: edit a text file, name it settings.ini, put in PocketCM folder
  • Open notepad
  • Edit using the setting below (add only the settings you need, not everything
  • Save it as settings.ini on your desktop
  • Close completely PocketCM
  • Copy it to your device in PocketCM directory (most likely something like \Program Files\PocketCM
  • Restart PocketCM Contact.

Create a theme

This is intented for more advanced user, so no detailed explaination
  • Make a ZIP file with your settings.ini, and all the required resources (image)
  • Name it accordingly
  • Copy it to your device
  • Select the theme from the GUI

New: Since version 0.29 there are some added feature especially for themer, please read here. However, if you're not familiar at all with theme, or it's your first theme, I would advise you to start slowly and do it manually for the beginning, then only try to improve your productivity!

Settings : General

Also, the basic idea of settings is:
[container].[control type].[control name].[property name]=value
for instance, for the text of the send button:
button.sendsmsbutton.text=Send
button - the control type
sendsmsbutton - the name of this specific button
text - the property you want to change
Note that there is no container specified here, container are mostly optional, they are re usefull when a given control can be shown many place, like keys on a keyboard
if you want to apply a property to all control of the same control type, you can use * as the name.

For instance to set the background for all button:
button.*.background=fill(#FF0000)
will make all button background red. If you want the sendsmsbutton to be green, while all the other button are red, you'll do:
button.*.background=fill(#FF0000)
button.sendsmsbutton.background=fill(#00FF00)
This way, the default is green, but the specific sendsmsbutton is green.

This apply also for the keyboard, and all part of the GUI, for instance:

key.*.width=20
set the width to 20 for all the key (that's generally what mean the asterisk)
key.a.width=34 
will set the width of the a key to 34. Which means if you set both, all key will be 20 pixel, except a key that will be 34 pixels. In the same idea:
key.a.width=20
set the width to 20 pixels for all the a key
layout2.key.a.width=20
set the width to 20 pixels for the a key of the layout2

It's important to understand the logic behind setting name. Most theme only override and define some settings, PocketCM will always try to take the most specific setting (container + control name, control name, * then default). Because of that most of the customization implies "creating" new setting name, based on what you want to customize.
 

 

Settings constants

The new version introduce lot of settings, so you'll end up with lot of definition, most of them will most likely use the same settings over and over (same color for instance). PocketCM gives you a way to create constants in your settings.ini, the idea is that you'll just have to modify the value of the constants, in one place in the settings.ini and not everywhere. This is very useful when tweaking theme, you can change the complete theme colors easily. .

the syntax is:
  • To create a new constant:
    $constantname$=constant value
    
  • To use a constant:
    $constantname$
A quick sample: Image I have the following settings:
global.flip.background=fill(#000000)
default.item.background=fill(#000000)
Which make, the item background black and the background of the flip animation black.

Now imagine I'd like to change this behavior, and want it to be red (#FF0000), with such settings I have to change two lines, with constant I can write:
$bg$=#FF0000

global.flip.background=fill($bg$)
default.item.background=fill($bg$)

Property type

Simple property

Some property are simple: text for instance, the value is simply the text you want.

Size propertyThe "p" basically make it resolution aware: it's 30 pixel for (W)QVGA device and 60 pixels for (W)VGA device. This allows you to create theme that are compatible with VGA and QVGA device.

Color propertyperty

Color are now hexadecimal number. #RRGGBB. (RR being the red component, GG the green, BB the blue, in order to easily convert color, you can find many website <a href="here.

Font property

smslist.*.sent.read.font=12p,regular,Segoe UI,#FFFFFF,center
size the size of the font, you can use "p" to make resolution aware fonts
family regular, bold or italic
font name full font name "as it appears in Pocket Word"
color the color of the text (in hexadecimal)
alignement lleft, center, right

For instance, here: for all sms list, message that are read and sent will use Segoe UI, 12 pt (and 24 px on VGA device) and will be rendered in white. 2>Background Property Background property are the most rich and complex.

you can use:
  • fill(#FFFFFF) - fill in white
  • vgradient(#FFFFFF,#000000) - vertical gradient from white to black
  • hgradient(#FFFFFF,#000000) - horizontal gradiant from white to black
  • fillimage(imagename.bmp) - image will be drawn (not stretched)
  • stretchimage(imagename.bmp) - image will be stretched to fill the space occupied by the control
  • alphaimage(image.png) - image will be drawn using alpha channel, use it only when needed, it's a lot slower.
  • leftimage - Image will be drawn to the left, centered vertically (used for instance in SMS conversation message)
  • rightimage - Image will be drawn to the right, centered vertically
  • margin(2) - put a 2 pixel margin around the control
  • leftmargin, rightmargin, topmargin, bottommargin also works
  • solidborder(#000000, 2) - add a 2 pixels black border around the control
  • totopborder(#000000, 1) - add a one pixel top border around the control
  • bottomborder(#000000, 1) - add a one pixel top border around the control
  • (New 0.30) stretchcomposition(image, left, top, right, bottom) - will create a series of image that will be stretched to fit the target background size, the left, top, right, bottom value specify which part of the image won't be scaled -- in short: it's a way to easily create a button that will look good in any size, by stretching only the center of it, not the border.

you can mix more than one in a single background, for instance: re style="width:300px; scroll:auto;">button.*.background=vgradient(#FFFFFF,#AAAAAA),topborder(#333333,1),bottomborder(#333333,1),margin(2) make the button filled with a vertical gradient from white to lightgray, a border of 1 pixel in dark grey, and a bottom border.

Box setting

Box define the position of the control, like the rect in 0.15 with more: you can use % and value relative to right, bottom border.

for instance:
button.sendsmsbutton.box=75%,-32p,100%,100%
the position is always: left, top, right, bottom.

left=75% so it's drawn at 75% of the container width (so 180 pixel if the orientation is portrait on a QVGA device)
top=-32p, negative value, means relative to the opposite border, "p" means resolution aware, so it means (320 - 32 = 288px for portrait when SIP is not shown on a QVGA device).
right and bottom: 100% so the edge of the screen.


In clear: the button will be drawn as the bottom right corner, with a height of 32 pixels and a width of 60 pixel.

VGA support

Since Contact 0.28 and Keyboard 0.20 it's possible to make theme for both VGA and QVGA device. In order to do so, simply put a vga.ini and/or qvga.ini file in your theme (zip), it will be used accordingly.

List of all settings

In order to get the list of all settings, the easiest way is to make a dump, using PocketCM Contact 0.19 and above, simply hit the "dump settings" button in the options. It will give you an up to date settings list for the current version.
The dump has the following section:
  • Settings for landscape
  • Settings for portrait
  • Settings for both
  • Localization dump: useful for translating the soft

Theme option (custom.settings)

Since PocketCM Contact 0.28 and Keyboard 0.20 you are able to add custom option to the application. This is useful if, for instance, your theme can have small variation and you want to avoid making 20 different theme.

The basic idea is that every option will be a specific settings file to load that will override value or define constants. (you can think of it as a dynamic include like you find in most web languages like PHP or JSP).

Practically, you define a custom settings, give the list of settings file that can be loaded, and provide the label for the UI. Depending of the number of settings (one or many), PocketCM will show the right UI (a check box, or a list).

Sample:

checkbutton.noheader.text=No header
custom.settings.noheader=noheader.ini

This will add a checkbox option with the label "No header", if the checkbox is checked by the user, the file "noheader.ini" will be loaded (at the exact position of the line where custom.settings is, so if you noheader.ini define variable, they can be used after this line not before.

Of course that means you need to add a noheader.ini file to your theme!

Sample 2 (multiple option)

custom.settings.countertype=sms_counter_all.ini,sms_counter_simple.ini,sms_counter_unread.ini
propertylabel.countertype.text=SMS count
settinglabel.sms_counter_all.ini.text=All (call/read/unread)
settinglabel.sms_counter_simple.ini.text=Simple (message count)
settinglabel.sms_counter_unread.ini.text=Only unread count
© 2010 Quentin Pouplard