[Samsung Galaxy Gear] OpenMind_NL:
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

View attachment 2523002

(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

View attachment 2523003

(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:

"alpha": 0...100	Transparancy percentage of the ITEM. 0 = No transparancy, 100 = Invisible
"color": -16777215...0	Value = -16777216 + (Red * 65536) + (Green * 256) + Blue. Red/Green/Blue = 0...255
"layerH":1...16	Height of the ITEM in cells. (*)
"layerW":1...16	Width of the ITEM in cells. (*)
"layerX":-16...16	Horizontal position of the ITEM in cells. (*)
"layerY":-16...16	Vertical position of the ITEM in cells. (*)
"themeTitle":"Title"	Internal titel for the theme
"dataSampleNum":?	Function unknown
"baseTheme":?	Function unknown

(*) More values are accepted, but pointless

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

View attachment 2523004

(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

View attachment 2523005

(Click picture to enlarge)

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

An image PART is defined with the parameters:

"clockImagePartType": "IMAGE_PART" IMAGE_PART.png is loading for the part.
"h":1...16 Height of the part in cells
"w":1...16 Width of the part in cells
"x":-16...16 Horizontal cell position of the part in relation to ITEM-layerX
"y":-16...16 Vertical cell position of the part in relation to ITEM-layerY

** Remark **
Although all the image PARTs have parameters w h x and y, they do not seem to affect the PART's size or position.

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:

YEAR_PART	assigned to display the year.
MONTH_PART	assigned to display the month.
DAY_PART	assigned to display the day.
HOUR_PART	assigned to display the hours.
MIN_PART	assigned to display the minutes.
SEC_PART	assigned to display the seconds.
AMPM_PRAT	assigned to display the halfday (AM/PM).
CITY_PART	assigned to display a city name.

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;

"clockTextPartType":"<part type>"	Initializing PART
"textAlign":"<position>"	Horizontal text alignment in relation to the part area.
"textVerticalAlign":"<position>"	Vertical text alignment in relation to the part area.
"textFormat":"<string>"	<string> contains a number of letters to define display information.
"maxWidth":0...320
"fontSize":1 and up	defines the size of the text.
"h":1...16	Height of the part in cells
"w":1...16	Width of the part in cells
"x":-16...16	Horizontal cell position of the part in relation to ITEM-layerX
"y":-16...16	Vertical cell position of the part in relation to ITEM-layerY

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.

H or h:	Hours in 24-hour and 12-hour mode. HH or hh will add a leading zero when the number of hours is below 10.
m:	Minutes.	mm will add a leading zero when the number of minutes is below 10.
s:	Seconds.	ss will add a leading zero when the number of seconds is below 10.
y:	Year.	yy will show two numbers.
yyyy will show four numbers.
M:	Month.	MM will add a leading zero when the month is below 10.
MMM will show the abreviated name.
MMMM will show the full name.
d:	Date.	dd will add a leading zero when the date is below 10.

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:

"fontName":"<font.ttf>"	The file font.ttf must be stored in the theme/texts/fonts folder
"localeLanguage":"<lang>"	Language code.
"layerH":1...16	Height of the ITEM in cells. (*)
"layerW":1...16	Width of the ITEM in cells. (*)
"layerX":-16...16	Horizontal position of the ITEM in cells. (*)
"layerY":-16...16	Vertical position of the ITEM in cells. (*)
"textAlpha":0...100	Transparancy percentage of the ITEM. 0 = No transparancy, 100 = Invisible
"textColor":0	Value = (Red * 65536) + (Green * 256) + Blue. Red/Green/Blue = 0...255
"bold":false/true	Normal font = false. Bold font = true.
"themeTitle":"Title"	Internal titel for the theme
"dataSampleNum":number	Function unknown
"baseTheme":false/true	Function unknown

(*) More values are accepted, but pointless.

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

View attachment 2523006

(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:

clockImages{
{Background Item
{Background Part}
}
{Dial Item (called FRAME_ITEM)
{Dial Part}
}
{Hands Item
{Hour Part}
{Minute Part}
{Seconds Part}
}
{Battery Indicator Item
{Battery Part 0}
{Battery Part 1}
{Battery Part 2}
{Battery Part 3}
{Battery Part 4}
{Battery Part 5}
}
{Bluetooth Item
{Connected Part}
{Disconnected Part}
}
}

clockTexts{
{Date Item
{Year part}
{Month part}
{Day part}
{Hours part}
{Minutes part}
{Seconds part}
{AMPM part}
}
}

themeType DIGITAL:

clockImages{
{Background Item
{Background Part}
}
{Battery Indicator Item
{Battery Part 0}
{Battery Part 1}
{Battery Part 2}
{Battery Part 3}
{Battery Part 4}
{Battery Part 5}
}
{Bluetooth Item
{Connected Part}
{Disconnected Part}
}
}

clockTexts{
{Digital Item
{Year part}
{Month part}
{Day part}
{Hours part}
{Minutes part}
{Seconds part}
{AMPM part}
{City part}
}
{Date Item
{Year part}
{Month part}
{Day part}
{Hours part}
{Minutes part}
{Seconds part}
{AMPM part}
{City part}
}
{World Clock Item
{Year part}
{Month part}
{Day part}
{Hours part}
{Minutes part}
{Seconds part}
{AMPM part}
{City part}
}
}

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