In the mtz theme package, you can find the lockscreen/advance directory, the manifest.xml file is the description script, in xml.
1. Image element
you can use Image element to display a picture on the screen with many properties.
<Image x="" y="" w="" h="" centerX="" centerY="" angle="" src="" srcid="" alpha=""/>
x,y : the position of the image relative to the upper-left point of the screen. both are 0 by default.
w,h : width and height, the image original width and height by default.
centerX, centerY : rotation center relative to the upper-left point of the image.
angle : rotation degree, 0-360
src : picture name.
srcid : the sequence number of a serial of pictures, normally it will be an expression which will be evaluated to a number. Then the image element will display different pictures according to the number. For instance, given src="pic.png" srcid="1", it will display the picture "pic_1.png".
alpha : the opacity, 0-255, will not display if alpha<=0, and >=255 just no difference from 255.
Sample:
<Image x="0" y="#screen_height-323" src="bottom_bg.png"/>
2. Expression.
All number properties supports expression. An expression can contain any kind of combinations of plus, minus, multiply, divid, modulo, brackets, functions and variables.
+ - * / %
functions: sin, cos, tan, asin, acos, atan, sinh, cosh, sqrt, abs, min, max
len(number) get the digit count of the given number, e.g. len(1234)=4
digit(number, pos) get the nth digit of the given number, e.g. digit(1234, 2) = 3
3. Variables
Variables can be used in expressions. A variable starts with a #.
currently supported variables:
* unlocker properties, format: name.property e.g. #unlocker.move_x
move_x: the move offset on x axis when unlocking, can be minus.
move_y: the move offset on y axis when unlocking, can be minus.
move_dist: the move distance when unlocking.
state: unlocking state normal:0 pressed:1 reached:2
* globals
time: current time, long
touch_x, touch_y: current touch point
battery_level: battery level 0-100
sms_unread_count: unread sms
call_missed_count: missed calls
* date & time
ampm: // 0 am, 1 pm
hour12: hour, 12 hours
hour24: hour in the day, 24 hours
minute:
second:
year:
month: //0-11
date: day
day_of_week // 1-7 Sun - Sat
screen_width: screen width
screen_height: screen height
battery_state: the state of plug and battery normal:0 charging:1 battery low:2 battery full:3
Sample:
alpha means this picture only display in non charging state, and will became transparent gradually along the unlocker dragging.
1. <Image x="162" y="#screen_height-84" src="hs_path_bg.png" alpha="(255-#unlocker.move_x/100*255)*min(1, abs(1-#battery_state))"/>
4. Image element can have animations.
Animation types: picture source, position, size, rotation, alpha.
Animations are independent to each other, they play on their own timeline and loop. An animation contains some key frame items. A key frame including properties and time. Except the source animation, other animations will interpolate the current properties according to current time and the properties of the adjacent two key frames. If the first key frame time is not 0, then the default key frame of time 0 will be the original picture properties. Time unit is ms.
for instance:
below is a position animation, if current time is 1600, 1600 mod 1000 = 600, x=10 + (600-100)/(1000-100)*(100-10) = 60 y=120
1. <Image>
2. <PositionAnimation>
3. <Position x="10" y="20" time="100"/>
4. <Position x="100" y="200" time="1000"/>
5. </PositionAnimation>
6. </Image>
time 0 100 [600] 1000
| | | |
x,y 10, 20 60,120 100, 200
The position is relative to the image's position.
7.
8. other animations:
9. <RotationAnimation>
10. <Rotation angle="" time=""/>
11. <Rotation angle="" time=""/>
12. </RotationAnimation>
13.
14. <SizeAnimation>
15. <Size w="" h="" time=""/>
16. <Size w="" h="" time=""/>
17. </SizeAnimation>
18.
19. <!-- 0-255 -->
20. <AlphaAnimation>
21. <Alpha a="" time=""/>
22. <Alpha a="" time=""/>
23. </AlphaAnimation>
The source animation is a little different from others, current picture is the first key frame source that is bigger than current time.
x, y is optional, means the relative position to the Image.
1. <SourcesAnimation>
2. <!-- optional: x y -->
3. <Source x="" y="" src="pic1.png" time="100"/>
4. <Source x="" y="" src="pic2.png" time="1000"/>
5. </SourcesAnimation>
if current time is 1600, the picture is pic2.png
Sample:
The position animation means the picture moves smoothly from the left of screen to the right in 1 second, stops for 1 second. The alpha animation means the opacity starts from 175, keep it when moving from left to right, when arrive at the right side, becomes 255 in 0.5 second, then disappears gradually in 0.5 second. And loop.
1. <Image x="0" y="#screen_height-177" src="charging_light.png" category="Charging">
2. <PositionAnimation>
3. <Position x="480" y="0" time="1000"/>
4. <Position x="480" y="0" time="2000"/>
5. </PositionAnimation>
6. <AlphaAnimation>
7. <Alpha a="175" time="0"/>
8. <Alpha a="175" time="1000"/>
9. <Alpha a="255" time="1500"/>
10. <Alpha a="0" time="2000"/>
11. </AlphaAnimation>
12. </Image>
5. Image can have masks.
x,y: the position of mask.
src: the mask picture, normally we use black to fill non-transparent area. and alpha channel will be used to mask the image. note that area in the Image that is out of the mask will keep intact.
align: indicates the position is relative to the Image or absolute.
1. <Mask x="" y="" src="" centerX="" centerY="" angle="" align="">
2. <SourcesAnimation/>
3. <RotationAnimation/>
4. <PositionAnimation/>
5. </Mask>
Mask can also have source animation, rotation animation, position animation, properties also support expression.
below is the dotted glowing arrow animation indicates the unlock path.
1. <Image x="444" y="#screen_height-92" src="hs_path_light.png">
2. <PositionAnimation>
3. <Position x="-438" y="0" time="2000"/>
4. </PositionAnimation>
5. <Mask x="0" y="#screen_height-92" src="hs_path_mask_r.png" align="absolute"/>
6. </Image>
6. Category property
All elements except the unlocker can be designated a category property. It has three values: Charging, BatteryLow, BatteryFull. The element with a category property will only show at the designated state. Can be used to display charging text, charging animations.
e.g. <Image x="100" y="100" src="pic.png" category="Charging"/>
7. Time
src is the prefix and ext of digit pictures, the code below means using time_0.png, time_1.png, ... time_9.png, time_dot.png
1. <Time x="10" y="10" src="time.png">
2. </Time>
8. Text
Display text on the screen, supports format.
color: #FFFFFFFF
size:
format: used to show variable numbers in text
align:left, center, right
paras: the variables need to be show in format.
1. <Text x="" y="" text="" color="" size="" format="" paras="#x,#y" align="">
2. <PositionAnimation/>
3. </Text>
Sample:
1. <Text x="240" y="130+#unlocker.move_y" category="Charging" color="#AAFFFFFF" alpha="200" size="24" format="Charging (%d%%)" paras="#battery_level" align="center"/>
9. Date & time
Display data and time text in designated format.
format: standard date time format, lunar date: NNNN
1. <DateTime x="" y="" color="" size="" format="">
2. <PositionAnimation/>
3. <DateTime>
Formatting characters may be repeated in order to get more detailed representations
of that field. For instance, the format character M is used to
represent the month. Depending on how many times that character is repeated
you get a different representation.
For the month of September:
M 9
MM 09
MMM Sep
MMMM September
The effects of the duplication vary depending on the nature of the field.
See the notes on the individual field formatters for details. For purely numeric
fields such as <code>HOUR</code> adding more copies of the designator will
zero-pad the value to that number of characters.
For 7 minutes past the hour:
m 7
mm 07
mmm 007
mmmm 0007
Examples for April 6, 1970 at 3:23am:
MM/dd/yy h:mmaa 04/06/70 3:23am
MMM dd, yyyy h:mmaa Apr 6, 1970 3:23am
MMMM dd, yyyy h:mmaa April 6, 1970 3:23am
E, MMMM dd, yyyy h:mmaa Mon, April 6, 1970 3:23am
EEEE, MMMM dd, yyyy h:mmaa Monday, April 6, 1970 3:23am
Noteworthy day: M/d/yy Noteworthy day: 4/6/70
24 hours: "kk:mm" -> "13:34"
10. Unlocker
name: used to compose a variable name. e.g. name.property
Can have multiple unlockers.
<Unlocker name="">
start point, specify the valid touch area of unlocking behavior. Elements under a start point will follow the current dragging.
1. <StartPoint x="" y="" w="" h="">
Normal state, can have multiple elements.
3. <NormalState>
4. <Image/>
5. <Time/>
6. <DateTime/>
7. <Text/>
8. </NormalState>
Pressed inside the valid area, starts unlocking. will hide other states elements.
10. <PressedState>
11. <Image/>
12. <Time/>
13. <DateTime/>
14. <Text/>
15. </PressedState>
When reached the unlock target area, show the reached state elements.
17. <ReachedState>
18. <Image/>
19. <Time/>
20. <DateTime/>
21. <Text/>
22. </ReachedState>
23. </StartPoint>
These 3 states can all be absent, just use variable expressions to vary elements to indicate unlock process.
Endpoint specifies the unlock target area, when the start point's x,y enter the target area, release will perform unlock.
1. <EndPoint x="" y="" w="" h="">
The intent to send after unlocking. can be used to launch an app.
3. <Intent action="" type="" category="" package="" class=""/>
5. <NormalState>
6. <Image/>
7. </NormalState>
8.
9. <!-- show the target position if pressed trying to unlock-->
10. <PressedState>
11. <Image/>
12.
13. </PressedState>
14.
15. <!-- show specified image when reached target, if touch up then perform unlock-->
16. <ReachedState>
17. <Image/>
18. </ReachedState>
19.
20.
Unlock path, can have more than 2 points to form a curve path. x,y is optional, tolerance means if dragging beyond this value then cancle the unlocking process, back to normal state. Position's x&y are relative to path's. the start point will be aligned to the path.
Path is also optional, if has no path, the start point can be dragged anywhere.
22. <Path x="" y="" tolerance="">
23. <Position x="" y="" />
24. <Position x="" y="" />
25. </Path>
26. </EndPoint>
can have multiple end points.
<EndPoint/>
</Unlocker>
Sample:
1. <Unlocker name="unlocker">
2. <StartPoint x="31" y="#screen_height-117" w="90" h="90">
3. <NormalState>
4. <Image x="31" y="#screen_height-117" src="unlock_button.png">
5. </Image>
6. </NormalState>
7. </StartPoint>
8. <EndPoint x="359" y="#screen_height-117" w="90" h="90">
9. <PressedState>
10. <Image x="359" y="#screen_height-117" src="unlock_target.png">
11. </Image>
12. </PressedState>
13. <Path x="0" y="#screen_height-117">
14. <Position x="31" y="0" />
15. <Position x="359" y="0" />
16. </Path>
17. </EndPoint>
18. </Unlocker>
11. The manifest.xml structure.
Lockscreen is the root, frameRate: specify a frame rate, if the animation is slow you can specify a small value to conserve power. by default is 30. If frameRate is set to 0, the screen will not update till you touch. touch event will cause screen update immediately. The theoratical max value is 100.
The z-order of element is subject to the secquence in xml, display from back to front.
1. <Lockscreen version="1" frameRate="">
2. <Image />
3. <Image />
4. <Unlocker/>
5. <Unlocker/>
6. <Time/>
7. <DateTime/>
8. <Text/>
9. </Lockscreen>
12. Wallpaper element
Wallpaper refers the wallpaper bitmap selected by system setting. It can't specify source, others are the same with Image. If has no Wallpaper element, wallpaper will not show. A Lockscreen may have multiple Wallpaper element.
<Wallpaper/>
If you have any question and suggestion plz contact me through: xuruijun#corp.xiaomi.com
I may not check this thread frequently.
Thanks
-- Ruijun
from MIUI team