Understanding Watch Styler's theme.json script

Because there are so many questions from people who become interested in modifying the Watch Styler clocks, I decided to write some kind of tutorial which might help to understand the theme.json script.
I hope this satisfies your hunger for knowledge.

Remarks and additions are welcome.
I'll be glad to add new knowledge to this humble explanation.

If anyone of the native english speaking people likes to rewrite (parts of) my foreigner english... Please do not doubt!
I'll be glad to correct any grammatical or whatever english error.

BE AWARE!!
This tutorial was written for Watch Styler and Galaxy Gear with Android (Gear 1 if you like).
Watch Styler on Tizen is limited in its functionality.
There is a difference in line-out of digital items and analog hands can only be centered.


LATEST ADDITIONS AND CORRECTIONS:
Febr. 24, 2014
- Corrected color calculation
- Additional info about language selection


* Extra Info, Tips and Tricks in the second post of this thread.


Prior knowledge:

For the locations and dimensions, Watch Styler devides the screen into a matrix of 10x10 cells.
Each cell measures 29x29 pixels and the entire matrix is surrounded by a border of 15 pixels on top, bottom, left and right.
This is not realy a border because virtualy the matrix goes on outside the edges of the screen.
I call it border because in the visible area the outer cells only shows 15 of 29 pixels.

Cell position -1,-1 = Pixel position -14,-14
Cell position 0,0 = Pixel position 15,15
Cell position 1,1 = Pixel position 44,44 (15 + 29)
Cell position 2,2 = Pixel position 73,73 (15 + 29 + 29)
|
Cell position 9,9 = Pixel position 276,276 (15 + 9 x 29)
Cell position 10,10 = Pixel position 305,305 (15 + 10 x 29)

14 pixels of the cells in row/column 10 are outside the visible area, just like 14 pixels of the cells in row/column -1.

Schematic representation of the top-left related coordinates

(Click picture to enlarge)

This coordinate system is used for most items.
Only a few image-items are positioned according to a center oriented matrix where coordinate 0,0 equals coordinate 5,5 in the top-left oriented system.

Schematic representation of the center related coordinates

(Click picture to enlarge)


A theme consists of two groups of items: clockImages and clockTexts.
Each item consists of one or more parts.




GRAPHIC ITEMS

clockImages is where the graphic items of a theme are defined.
These image-items can be BG_ITEM, FRAME_ITEM, HANDS_ITEM, BATTERY_ITEM and BLUETOOTH_ITEM.
Each ITEM is a layer that can contain one or more PARTs.
Besides the image-parts, an image-item has a few parameters to define its properties.

Every image-item starts with the parameters clockItem and clockImagePartTypes to initialize the item before it comes to clockImageParts.

clockImageParts is used in each image-item to define the PARTs that show the images.

BG_ITEM is the background image for the theme.
It is projected behind all other items.
It contains BG_PART, which defines the image that must be loaded from the theme's images folder.

FRAME_ITEM contains the dail for the theme.
It is projected over BG_ITEM and under HANDS_ITEM
It contains FRAME_PART, which defines the image that must be loaded.
FRAME_PART can be omitted when BG_PART contains an image of the dial, or when no dial is needed.

HANDS_ITEM contains the hands for hours, minutes and seconds of an analog clock.
It is projected over all other items.
It contains HOUR_PART, MIN_PART and SEC_PART which define the images that must be loaded.

BATTERY_ITEM contains six images to indicate different levels of battery charge.
It is projected over FRAME_ITEM and under HANDS_ITEM.
It contains BATTERY0_PART, BATTERY1_PART, BATTERY2_PART, BATTERY3_PART, BATTERY4_PART and BATTERY5_PART which define the images that must be loaded.
BATTERY0_PART level: 0- 19%
BATTERY1_PART level: 20- 39%
BATTERY2_PART level: 40- 59%
BATTERY3_PART level: 60- 79%
BATTERY4_PART level: 80- 99%
BATTERY5_PART level: 100%

BLUETOOTH_ITEM contains two images to indicate the bluetooth connection status.
It is projected over FRAME_ITEM and under HANDS_ITEM.
It contains BLUETOOTH_CONNECT_PART and BLUETOOTH_DISCONNECT_PART which define the images that must be loaded.

When all image-parts are defined, there are some image-item parameters left.

The parameters to define an image ITEM are:
layerX and layerY define the position of an image-ITEM. layerH and layerW define the size of an image-ITEM.
BATTERY_ITEM and BLUETOOTH_ITEM are placed with their top-left corner related to cell position 0,0

When color for an image-item is set to pure white (-1), the images will be show in their original colors.
Other colors will mix with the image colors.
When you create black and white or greyscale images, the color setting can be used to define the color for dial and hands.


Schematic representation where (blue area) BATTERY_ITEM or BLUETOOTH_ITEM use parameters;
"alpha":0,"color":5160703,"layerH":4,"layerW":5,"layerX":2,"layerY":1

(Click picture to enlarge)


BG_ITEM, FRAME_ITEM and HANDS_ITEM however, are the only items that are positioned with their center related to cell position 5,5 (screen/matrix center)
Negative values can be used to move a center-related ITEM to the left or top of the screen.


Schematic representation where (blue area) BG_ITEM, FRAME_ITEM or HANDS_ITEM use parameters;
"alpha":20,"color":5160703,"layerH":4,"layerW":5,"layerX":2,"layerY":1

(Click picture to enlarge)


Notice the different location with the same x,y parameters.



An image PART is defined with the parameters:





TEXT ITEMS


clockTexts is where alpha-numeric items for the theme are defined.
These text-items can be DIGITAL_ITEM, DATE_ITEM or WORLD_CLOCK_ITEM.
Each ITEM is a layer that can contain one or more PARTs.
Besides the text-parts, an text-item has a few parameters that define the item-properties.

Each text-item can contain one or more text-parts and is projected over BG_ITEM and under HANDS_ITEM.

DIGITAL_ITEM is assigned to display the local time.
DATE_ITEM is assigned to display the local date.
WORLD_TIME_ITEM is assigned to display any time zone.



Every text-item starts with the parameter;
"bgName":"<picture file>".

This can be used to define a background image for the text-item.
The <picture file> should be stored in the theme/texts folder.
image.png and image.gif tested positive, but other extensions may work too.
Animated GIF was tested but only a static first frame was shown.

** Remark **
When a background image is used for the text-item, only the last PART in that item will be displayed!


Then there's a parameter that's fully functional for WORLD_CLOCK_ITEM only.
"timeZoneId":"Area/City" is used to define the time zone that should be used.
The local time zone will be used when "Area/City" = "".
For DIGITAL_ITEM and DATE_ITEM it will affect CITY_PART only.
For WORLD_CLOCK_ITEM it will affect time and date PARTs too.

A full list of compatible time zone values can be found at:
https://support.sumologic.com/entries/23097313-JSON-timeZone-Values-and-Associated-GMT-Offsets


Next text-item parameter is "clockItem":"<Item name>" to initialize the text-item.


Then comes "clockTextParts", which contains the actual text-parts for the item.

It can contain:

AMPM_PRAT seems to be an error (compared to AMPM_PART), but this is how it's used in the clock scripts.

All these assignments seem to be obvious, but each part can be used to display much more.

Each text PART is defined with these parameters;

textAlign defines the horizontal position of a text in te area that is defined by h and w.

"textAlign":"LEFT" Places the text against the left edge of the area
"textAlign":"RIGHT" Places the text against the right edge of the area
"textAlign":"CENTER" Places the text centered in the area


textVerticalAlign defines the vertical position of a text in te area that is defined by h and w.

"textVerticalAlign":"TOP" Places the text against the top edge of the area.
"textVerticalAlign":"BOTTOM" Places the text against the bottom edge of the area.
"textVerticalAlign":"CENTER" Places the text centered in the area


"textFormat":"<string>"
<string> represents one or more letters to define the information to be displayed.


Example: "textFormat":"dd-MM-yyyy hh:mm.ss"
This will show December 8, 2013, 12 hour 07 minutes and 18 seconds AM like; 08-12-2013 12:07.18

Example: "textFormat":"dd-MMM-yyyy HH:mm.ss"
This will show December 8, 2013, 12 hour 07 minutes and 18 seconds AM like; 08-DEC-2013 00:07.18

A full list of letters that are used to define the text-display can be found at Additional Information.

textFormat works a little different for CITY_PART. When set to textformat:"" it will show the city that matches the item's timeZoneId.
When not set to "" it will show the text as it is, without decoding letters to time/date info.


"maxWidth" Truncates text after the specified number of pixels. Only CITY_PART seems to be affected by this parameter.


"fontSize" is used to define the size of the text.


"h" and "w" are used to define the size for a text-part.


"x" and "y" are used to define the location for a text-part in relation to the text-item location.

** Remark **
The absolute position for a text-PART = (ITEM-layerX + PART-x, ITEM-layerY + PART-y)


When all text-parts are defined, there are some text-item parameters left.

The parameters that define an text ITEM are:

localLanguage is used to select a language for the written month and day display.
Default for Watch Styler themes is "en", which represents English.
For German it's "de", for Dutch "nl", for Italian "it".
Not specifying a language, like in "localeLanguage":"", will automaticly select the Gear/Phone language

It seems like the language codes follow the ISO 639-1 standard.
More about this standard (and more language codes!): http://en.wikipedia.org/wiki/ISO_639-1
A full ISO 639-1 language code list: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
Please note that a lot but not all fonts are compatible with special characters (like é, ö, ã etc.) used in some languages.


Schematic representation of a (blue) text-item and (orange) text-parts using parameters;
PART 1:
"textVerticalAlign":"CENTER","textFormat":"HH:mm","textAlign":"LEFT","maxWidth":0,"h":2,"fontSize":40,"w":4,"x":1,"y":0

PART 2:
"textVerticalAlign":"TOP","textFormat":"dd MMM","textAlign":"RIGHT","maxWidth":0,"h":2,"fontSize":30,"w":4,"x":1,"y":3

PART 3:
"textVerticalAlign":"BOTTOM","textFormat":"yyyy","textAlign":"CENTER","maxWidth":0,"h":2,"fontSize":35,"w":4,"x":1,"y":6

FINAL ITEM PROPERTIES:
"fontName":"coving_regular.ttf","localeLanguage":"en","layerW":6,"layerX":2,"layerY":1,"layerH":8,"textAlpha":0,"textColor":0,"bold":false,"themeTitle":"test","dataSampleNum":3,"baseTheme":false

(Click picture to enlarge)





Finally, at the end the script is closed with some general theme parameters;
"themeType":ANALOG or DIGITAL Sets the clock type.
"themeTitle":"Title" Internal titel for the theme
"dataSampleNum":number Function unknown
"baseTheme":false/true Function unknown

"themeType" can be either ANALOG or DIGITAL, which determines the structure that can be used.
ANALOG offers an analog clock with hands and one digital item that can be used for any type of local date or time info.
DIGITAL offers three digital items. Two can be used for any type of local date or time info, one can be used for world wide date or time info.


BASIC THEME STRUCTURE:

themeType ANALOG:


themeType DIGITAL:








ADDITIONAL INFORMATION.


Time and Date format strings:

Applies to: "textFormat":"<string>"
Items: DIGITAL_ITEM, DATE_ITEM and WORLD_CLOCK_ITEM
Parts: HOUR_PART, MIN_PART, SEC_PART, YEAR_PART, MONTH_PART, DAY_PART, AMPM_PRAT

A / a:
Halfday (AM or PM)

B / b: Not used

C: Not used

c, cc or ccc:
Day of the week, written. Abbreviated.

cccc:
Day of the week, written. Full.

D, DD or DDD:
Day number in a year. 1 to 366. DD adds a leading 0 to day numbers below 10. DDD adds leading 0's to day numbers below 10 and below 100.

d or dd:
Date. dd adds a leading 0 for dates below 10.

E, EE or EEE:
Day of the week, written. Abbreviated.

EEEE:
Day of the week, written. Full.

e: Not used

F: ? (30-12-2013: 5)

f: Not used

G: Era (Output = AD)

g: Not used

H:
Hours. 0...23. HH adds a leading 0 for hours below 10.

h:
Hours. 1...12. hh adds a leading 0 for hours below 10.

I / i: Not used

J / j: Not used

K: Hours: 0...11. KK adds a leading 0 for hours below 10.

k: Hours: 1...24. kk adds a leading 0 for hours below 10.

L: Month (?)

l: Not used

M:
Month in numbers. MM adds a leading 0 for months below 10.

MMM:
Month written. Abbreviated.

MMMM:
Month written. Full.

m:
Minutes. mm adds a leading 0 for minutes below 10.

N / n: Not used

O / o: Not used

P / p: Not used

Q / q: Not used

R / r: Not used

S:
milliseconds

s:
Seconds. ss adds a leading 0 for seconds below 10.

T / t: Not used

U / u: Not used

V / v: Not used

W: (upper case)
Week in a month, 1...5, sunday-saturday (?)

w: (lower case)
Week in a year. 1...53
Note that the week number is calculated with first week of the year which is 1.
The first week of the year is the first week which contains a Thursday.
Thus, the first week of the year 1994 is not the week containing the 1st of January but rather the week 03/01-09/01/1994.
Year 2004 is an example of a year that has 53 ISO8601 weeks since it contains both the week containing 1st of January and the week containing 31st of December.

X / x: Not used

Y: Not used

y or yyyy:
Year. 4 numbers.

yy:
Year. Last 2 numbers

Z:
Time zone offset

z:
Time zone written. Abbreviated.

zzzz:
Time zone written. Full.

'Text':
Text

Info, Tips and Tricks

Donations
You like to donate?
I have no problem to pay my rent or to get something decent to eat every day.

Homeless people in your town will be happy to collect my donations.
If your town is lucky and noone is homeless, please donate at the nearest animal shelter.



Watch Styler themes location at your phone



Theme folder contents
File: PRV_IMG.png
File: theme.json
Folder: images. Contains one or more PNG image files
Folder: texts. Sometimes contains one or more images. Often contains fonts folder (which may be empty).



Make theme.json easier to read

Very often you may start by editing a theme that was saved by Watch Styler editor.
First thing you will see when you open theme.json, is one big text-block without any spaces or line-breaks.

What I always do first is replacing all "{" by "Enter { Enter", and replacing all "}" by "Enter } Enter".

Example in windows Notepad:
Type Enter { Enter and copy the three lines. Remove the lines you just typed and copied!
Set your cursor at the beginning of the script and press Ctrl-F (Find), type { Enter Esc Ctrl-V
You now replaced the first "{" by "Enter { Enter".
Now press F3 (Find next) and Ctrl-V until you reach the end of the script.

Do the same with }

When you've done this, you will be able to identify various script items and parts with their parameters much easier.
To make it even more clear, you can add leading tabs in front of every line to identify each item/part much easier.
Whenever a line starts with {, add one Tab more in front of the next lines.
When a line starts with }, reduce the number of Tabs leading that line and the next lines with one.

Adding spaces, Tabs or Line-breaks to a script, has no affect on the functionality as long as it is not in the middle of a word..

Here's an example:
Follow the steps above and go from something like this:
to something like this:

Watch Styler editor compatibilaty

After changing the theme.json file, There is a very big chance that the theme will not be compatible with Watch Styler editor anymore .
It doesn't harm to open the theme in the editor for testing. Just don't save the theme when it looks bad in the editor.

Some reasons why a theme gets incompatible with the editor:
- You applied a new font that is not available to Watch Styler editor.
- You used time/date formatting that's unknown to the editor.
- You used non-standard Item-Part structures.

Being not compatible to the editor doesn't mean the theme is wrong.
It's just not editable in a user-friendly way anymore. Only by direct script editing.

To upload a modified theme to your Gear, you'll still use the Watch Styler clock preset in Gear Manager.
- Gear Manager / Clocks / Gear wheel behind Watch Styler preset / Select modified theme

Reserved 2

Reserved 3

BruceFeuillette said:

Great tutorial !
One thing about the date format. Watch Styler on the phone don't support the EEE format.
So don't load the theme in it or it will "correct" the date. Just push it via the Watch Styler GM clock manager.

Sent from my TouchPad using xda app-developers app

Click to expand...

Click to collapse

There are more things that are not compatible with Watch Styler editor.
So, I started adding some info in the second post in this thread.

recDNA said:

If you have an image of an analog clock with no white date box is it possible to insert the white date box and date at the 3 o'clock position through the theme.jeson alone or do you have to photoshop the white box on to the image then just add the day text through theme.jeson?

Click to expand...

Click to collapse

At the TEXT ITEMS part you can read about the bgName parameter of a text-item. When you create a clock with the date box in Watch Styler, it's done this way.

I prefer to photoshop the datebox into the background or dial, but then you'll have to know exactly where the date is displayed in the final theme.

Which position is 3 o'clock right edge using your grid system? (I'm sorry but the grid picture isn't clear enough to read the digits)

Click to expand...

Click to collapse

So you didn't click the pictures? That helps in decoding the positions
You'll notice that a 3 o'çlock date box would be at x=8 or 9. You'll want to center the date verticaly on the center line at y=5.,
So I would use y position 4 and a part h of 2, with textVerticalAlign=CENTER.

Basically I created a rolex submariner from a picture posted early in the show thread then tried to move the date box and date text to 3 o'clock. Styler created the theme for me. Now I just want to edit it so white box and date text move down to 3 o'clock position.

Click to expand...

Click to collapse

Well.. you might try first if you can align the date text exactly on the date box position by playing with the textAlign (left, right, center) parameter on various x positions and maybe with various w (part width) values
If that doesn't work good enough, you'll have to edit the picture and move the date box a little to the left or right.

Patosbuddy said:

Read try, fail, read, try, fail,,, ,first after trying a lot, then we can ask for help if we get stuck.

Click to expand...

Click to collapse

Looks like the way I started two months ago... except that I had nothing to read and could only try fail try fail try yahooo!... and noone I could ask for help when I got stuck. :crying:

So... just imagine what kind of themes you will come up with in a few weeks... or maybe even days !!