Customzing PocketCM Contact
You need PocketCM 0.16 or above in order to customize PocketCM this way.
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 - 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:
will make all button background red. If you want the sendsmsbutton to be green, while all the other button are red, you'll do:
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:
set the width to 20 for all the key (that's generally what mean the asterisk)
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:
set the width to 20 pixels for all the a key
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.
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:
A quick sample: Image I have the following settings:
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:
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
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
the size of the font, you can use "p" to make resolution aware fonts
regular, bold or italic
full font name "as it appears in Pocket Word"
the color of the text (in hexadecimal)
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.
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
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 define the position of the control, like the rect in 0.15 with more: you can use % and value relative to right, bottom border.
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.
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).
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)
settinglabel.sms_counter_simple.ini.text=Simple (message count)
settinglabel.sms_counter_unread.ini.text=Only unread count