/
View.yml
2131 lines (1782 loc) Β· 89.4 KB
/
View.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
name: Titanium.UI.View
summary: An empty drawing surface or container
description: |
The `View` is the base type for all UI widgets in Titanium.
You use the <Titanium.UI.createView> method or **`<View>`** Alloy element to create a View.
#### Units and Coordinates
Sizes and coordinates can be specified using a variety of units. If a value is
specified as a number, it is interpreted as a value in the default unit for the
current system and/or the current project.
When a value is specified as string, the value can consist of:
* A number.
* A percentage, such as "10%", interpreted as a percentage of the parent's total size
in that dimension.
* A number plus a unit specifier, such as "10px" or "1in".
The following units are supported:
<table class="doc-table" width="60%">
<thead>
<tr>
<th>Unit</th>
<th>Specifier</th>
<th>Note</th>
</tr>
</thead>
<tbody>
<tr>
<td>pixels</td>
<td>px</td>
<td></td>
</tr>
<tr>
<td>density-independent pixels</td>
<td>dip</td>
<td>Equivalent to Apple "points."</td>
</tr>
<tr>
<td>inches</td>
<td>in</td>
<td></td>
</tr>
<tr>
<td>millimeters</td>
<td>mm</td>
<td>Android, iOS only</td>
</tr>
<tr>
<td>centimeters</td>
<td>cm</td>
<td>Android, iOS only</td>
</tr>
<tr>
<td>points</td>
<td>pt</td>
<td>Typographical points of 1/72 of an inch. On Android, you can specify sizes and coordinates in typographical points. On other platforms, this unit is only used to specify font sizes. Not to be confused with Apple "points."</td>
</tr>
</tbody>
</table>
The interpretation of the density-independent pixel (DIP) varies by platform:
* On Android, one DIP corresponds to one pixel on a 160DPI
display.
* On iOS, one DIP corresponds to one pixel on a non-Retina display, which
is 163DPI for iPhone/iPod touch and 132DPI for the iPad. A DIP
corresponds to 2 pixels of width or height on a Retina display.
The absolute measures, such as inches, are dependent on the device correctly reporting
its density.
If no units are specified, a system-default unit is assumed. The system default unit is:
* Pixels on Android.
* DIPs on iOS.
On Android and iOS, the default unit can be overriden on a per-application level by setting the
`ti.ui.defaultunit` property in `tiapp.xml`. For example, to use DIPs as the
default on all platforms, set `defaultunit` to `dip`:
``` xml
<property name="ti.ui.defaultunit" type="string">dip</property>
```
The value for `ti.ui.defaultunit` can be any of the unit specifiers defined above, or
`system` to specify that the platform's default unit should be used.
On IOS if you set the `ti.ui.defaultunit` property to anything other than `system` or `dip`, your
application should detect and handle Retina displays manually.
Font sizes on iOS are treated differently than other sizes: font sizes are always
specified in typographical points.
For more details see:
* [UI Composite Layout Spec](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Contributing_to_Titanium/Platform_Development/Specs/UI_Composite_Layout_Behavior_Spec.html)
#### Size and Position
Titanium views are positioned using the `left`, `right`, `top,` `bottom` and `center`
properties, and sized using the `width` and `height` properties. These are
input properties, set by the user to specify layout, and not modified by the
system to indicate actual calculated positions and sizes.
The [height](Titanium.UI.View.height) and [width](Titanium.UI.View.width) properties
accept several special values:
* <Titanium.UI.FILL> specifies that the view should fill the parent in this
dimension.
* <Titanium.UI.SIZE> specifies that the view should adjust this size to fit its
contents, such as a label's text or a view's children.
* 'auto' specifies that the view should choose either `FILL` or `SIZE` behavior.
The use of `auto` is deprecated, and should be replaced with the SIZE or FILL constants if it is necessary to set the view's behavior explicitly.
Sizes and positions can also be specified as a percentage of the parent's size, for
example, `50%`.
How these properties are interpreted depends on the value of the view's `layout`
property. See the description of the [layout](Titanium.UI.View.layout) property
for details.
The [rect](Titanium.UI.View.rect) property is a read-only dictionary
with the properties `x`, `y`, `width` and `height`. It provides the *rendered*
size and position of the view, and is only available once both it and its ancestors have been
fully drawn.
The [size](Titanium.UI.View.size) property is a read-only dictionary
with the properties `x`, `y`, `width` and `height`. It provides the *rendered* size
of the view, and is only available once both it and its ancestors have been
fully drawn.
To determine whether the `size` and `rect` values are available, add an event listener
for the [postlayout](Titanium.UI.View.postlayout) event, which is fired at the end of
a layout cycle.
#### Accessibility
Four accessibility-related view properties are available in Titanium Mobile for iOS
and Android:
* <Titanium.UI.View.accessibilityLabel>
* <Titanium.UI.View.accessibilityValue>
* <Titanium.UI.View.accessibilityHint>
* <Titanium.UI.View.accessibilityHidden>
The first three, `accessibilityLabel`, `accessibilityValue` and `accessibilityHint`, are for setting text
that will be relayed to the user by the assistive service (such as TalkBack on Android or VoiceOver
on iOS). On iOS, Titanium will then take these values and set the native properties
of the same name which are defined in the [UIAccessibilityProtocol](https://developer.apple.com/documentation/uikit/accessibility/uiaccessibility).
On Android, Titanium takes the three values and concatenates them in the order `accessibilityLabel`,
`accessibilityValue`, and `accessibilityHint`, and then uses the result to set the native view's
[`contentDescription`](https://developer.android.com/reference/android/view/View.html#setContentDescription%28java.lang.CharSequence%29)
property.
You are not required to set all three properties: feel free to set just one or two as needed and
experiment with the results by turning on VoiceOver (iOS) or TalkBack (Android) on your test device.
The fourth property, `accessibilityHidden`, when set to `true`, indicates that the view can be ignored
by the assistive service. In iOS this sets the similarly-named
[accessibilityElementsHidden](https://developer.apple.com/documentation/objectivec/nsobject/1615080-accessibilityelementshidden)
native property.
In Android `accessibilityHidden` calls the native [View.setImportantForAccessibility(boolean)](https://developer.android.com/reference/android/view/View.html#setImportantForAccessibility%28int%29) method, passing `false` when
this property is set to `true` (i.e., "hidden" means it's not important). However, the
native `setImportantForAccessibility` method is available only on devices running
Android 4.1 (API level 16/Jelly Bean) or later. On earlier versions of Android, this
property is ignored.
No error will occur on older devices if you set `accessibilityHidden`; the value will simply be ignored.
#### iOS: backgroundLeftCap and backgroundTopCap properties
The [backgroundLeftCap](Titanium.UI.View.backgroundLeftCap) and [backgroundTopCap](Titanium.UI.View.backgroundTopCap) properties are
used to specify the portions of the [backgroundImage](Titanium.UI.View.backgroundImage) that must not be resized when the image is streched or shrunk.
Given an image of width `w` and height `h`, the stretchable portion on the image is defined as a rectangle with the `top-left` point set to
`(backgroundLeftCap , backgroundTopCap)` and the `bottom-right` point set to `(w - backgroundLeftCap , h - backgroundTopCap)`. The portions not covered by
the stretchable portion keep their original size and appearance.
For best results on ImageView set up the `backgroundLeftCap` and `backgroundTopCap` properties such that the stretchable portion is always a 1x1 box.
#### iOS Clipping Behavior
Four view related properties are available in Titanium Mobile for iOS.
* <Titanium.UI.View.viewShadowRadius>
* <Titanium.UI.View.viewShadowColor>
* <Titanium.UI.View.viewShadowOffset>
* <Titanium.UI.View.clipMode>
The first three, `viewShadowColor`, `viewShadowRadius` and `viewShadowOffset` control the shadow associated with the view.
The shadow of the view is drawn using a rounded rectangle with the arc radius set to the `borderRadius` property.
The `clipMode` property lets the user control the clipping behavior of the View.
Setting this to <Titanium.UI.iOS.CLIP_MODE_ENABLED> enforces all child views to be clipped to this views bounds.
Setting this to <Titanium.UI.iOS.CLIP_MODE_DISABLED> allows child views to be drawn outside the bounds of this view.
When set to <Titanium.UI.iOS.CLIP_MODE_DEFAULT> or when this property is not set, clipping behavior is defined by the following rules applied in order.
* If the `viewShadowColor` is defined to be a color with alpha > 0, clipping is disabled.
* If the `borderWidth` or `borderRadius` of the view is set to a value > 0, clipping is enabled.
* If the view has one or more `children` clipping is enabled.
* If none of the conditions are met, clipping is disabled.
In earlier versions of Titanium Mobile, views had clipping enabled by default.
#### iOS Animation on shadow associated with view
If `borderRadius` property has multiple values, animation on shadow associated with the view will not work.
extends: Titanium.Proxy
since: "0.9"
events:
- name: click
summary: Fired when the device detects a click against the view.
description: |
There is a subtle difference between singletap and click events.
A singletap event is generated when the user taps the screen briefly
without moving their finger. This gesture will also generate a click event.
However, a click event can also be generated when the user touches,
moves their finger, and then removes it from the screen.
On Android, a click event can also be generated by a trackball click.
properties:
- name: x
type: Number
summary: X coordinate of the event from the `source` view's coordinate system.
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: obscured
type: Boolean
summary: |
Returns `true` if the click passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: dblclick
summary: Fired when the device detects a double click against the view.
properties:
- name: x
type: Number
summary: X coordinate of the event from the `source` view's coordinate system.
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: obscured
type: Boolean
summary: |
Returns `true` if the double click passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: doubletap
summary: Fired when the device detects a double tap against the view.
platforms: [android, iphone, ipad, macos]
properties:
- name: x
summary: X coordinate of the event from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: obscured
type: Boolean
summary: |
Returns `true` if the double tap passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: focus
summary: Fired when the view element gains focus.
description: This event only fires when using the trackball to navigate.
platforms: [android]
- name: keypressed
summary: Fired when a hardware key is pressed in the view.
description: |
A keypressed event is generated by pressing a hardware key. On Android, this event can only be
fired when the property [focusable](Titanium.UI.View.focusable) is set to true. On iOS the
event is generated only when using [Ti.UI.TextArea](Titanium.UI.TextArea), [Ti.UI.TextField](Titanium.UI.TextField)
and [Ti.UI.SearchBar](Titanium.UI.SearchBar).
platforms: [android, iphone, ipad, macos]
since: {android: "3.1.0", iphone: "5.4.0", ipad: "5.4.0", macos: "9.2.0"}
properties:
- name: keyCode
type: Number
summary: The code for the physical key that was pressed. For more details, see [KeyEvent](https://developer.android.com/reference/android/view/KeyEvent.html). This API is experimental and subject to change.
- name: longclick
summary: Fired when the device detects a long click.
description: |
A long click is generated by touching and holding on the touchscreen or holding down the
trackball button.
The event occurs before the finger/button is lifted.
A `longpress` and a `longclick` can occur together.
As the trackball can fire this event, it is not intended to return the `x` and `y`
coordinates of the touch, even when it is generated by the touchscreen.
A `longclick` blocks a `click`, meaning that a `click` event will not fire when a
`longclick` listener exists.
platforms: [android]
- name: longpress
summary: Fired when the device detects a long press.
description: |
A long press is generated by touching and holding on the touchscreen. Unlike a `longclick`,
it does not respond to the trackball button.
The event occurs before the finger is lifted.
A `longpress` and a `longclick` can occur together.
In contrast to a `longclick`, this event returns the `x` and `y` coordinates of the touch.
platforms: [android, iphone, ipad, macos]
properties:
- name: x
summary: X coordinate of the event from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: obscured
type: Boolean
summary: |
Returns `true` if the long press passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: pinch
summary: Fired when the device detects a pinch gesture.
description: |
A pinch is a touch and expand or contract
with two fingers. The event occurs continuously until a finger is lifted again.
platforms: [iphone, ipad, android, macos]
since: "1.8.0"
properties:
- name: scale
summary: The scale factor relative to the points of the two touches in screen coordinates.
type: Number
- name: velocity
summary: The velocity of the pinch in scale factor per second.
type: Number
- name: time
summary: The event time of the current event being processed.
type: Number
since: "7.5.0"
platforms: [android]
- name: timeDelta
summary: |
The time difference in milliseconds between the previous accepted scaling event and the
current scaling event.
type: Number
since: "7.5.0"
platforms: [android]
- name: currentSpan
summary: |
The average distance between each of the pointers forming the gesture in progress through
the focal point.
type: Number
since: "7.5.0"
platforms: [android]
- name: currentSpanX
summary: |
The average X distance between each of the pointers forming the gesture in progress through
the focal point.
type: Number
since: "7.5.0"
platforms: [android]
- name: currentSpanY
summary: |
The average Y distance between each of the pointers forming the gesture in progress through
the focal point.
type: Number
since: "7.5.0"
platforms: [android]
- name: previousSpan
summary: |
The previous average distance between each of the pointers forming the gesture in progress through
the focal point.
type: Number
since: "7.5.0"
platforms: [android]
- name: previousSpanX
summary: |
The previous average X distance between each of the pointers forming the gesture in progress through
the focal point.
type: Number
since: "7.5.0"
platforms: [android]
- name: previousSpanY
summary: |
The previous average Y distance between each of the pointers forming the gesture in progress through
the focal point.
type: Number
since: "7.5.0"
platforms: [android]
- name: focusX
summary: |
The X coordinate of the current gesture's focal point.
type: Number
since: "7.5.0"
platforms: [android]
- name: focusY
summary: |
The Y coordinate of the current gesture's focal point.
type: Number
since: "7.5.0"
platforms: [android]
- name: inProgress
summary: Returns `true` if a scale gesture is in progress, `false` otherwise.
type: Boolean
since: "7.5.0"
platforms: [android]
- name: postlayout
summary: Fired when a layout cycle is finished.
description: |
This event is fired when the view and its ancestors have been laid out.
The [rect](Titanium.UI.View.rect) and [size](Titanium.UI.View.size) values
should be usable when this event is fired.
This event is typically triggered by either changing layout
properties or by changing the orientation of the device. Note that changing the
layout of child views or ancestors can also trigger a relayout of this view.
Note that altering any properties that affect layout from the `postlayout` callback
may result in an endless loop.
since: "2.0.0"
- name: singletap
summary: Fired when the device detects a single tap against the view.
properties:
- name: x
summary: X coordinate of the event from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: obscured
type: Boolean
summary: |
Returns `true` if the single tap passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: swipe
summary: Fired when the device detects a swipe gesture against the view.
platforms: [android, iphone, ipad, macos]
properties:
- name: direction
summary: Direction of the swipe--either 'left', 'right', 'up', or 'down'.
type: String
- name: x
summary: X coordinate of the event's endpoint from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event's endpoint from the `source` view's coordinate system.
type: Number
- name: obscured
type: Boolean
summary: |
Returns `true` if the swipe passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: touchcancel
summary: Fired when a touch event is interrupted by the device.
description: |
A touchcancel can happen in circumstances such as an incoming call to allow the
UI to clean up state.
properties:
- name: x
summary: X coordinate of the event from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: force
summary: |
The current force value of the touch event.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later and on some Android devices.
type: Number
- name: size
summary: |
The current size of the touch area. Note: This property is only available on some Android devices.
type: Number
- name: maximumPossibleForce
summary: |
Maximum possible value of the force property.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: altitudeAngle
summary: |
A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is
being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0.
Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: timestamp
summary: |
The time (in seconds) when the touch was used in correlation with the system start up.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: azimuthUnitVectorInViewX
summary: |
The x value of the unit vector that points in the direction of the azimuth of the stylus.
Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: azimuthUnitVectorInViewY
summary: |
The y value of the unit vector that points in the direction of the azimuth of the stylus.
Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: obscured
type: Boolean
summary: |
Returns `true` if the touch passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: touchend
summary: Fired when a touch event is completed.
description: |
On the Android platform, other gesture events, such as `longpress` or `swipe`, cancel touch
events, so this event may not be triggered after a `touchstart` event.
properties:
- name: x
summary: X coordinate of the event from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: force
summary: |
The current force value of the touch event.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later and on some Android devices.
type: Number
- name: size
summary: |
The current size of the touch area. Note: This property is only available on some Android devices.
type: Number
- name: maximumPossibleForce
summary: |
Maximum possible value of the force property.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: altitudeAngle
summary: |
A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is
being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0.
Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: timestamp
summary: |
The time (in seconds) when the touch was used in correlation with the system start up.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: azimuthUnitVectorInViewX
summary: |
The x value of the unit vector that points in the direction of the azimuth of the stylus.
Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: azimuthUnitVectorInViewY
summary: |
The y value of the unit vector that points in the direction of the azimuth of the stylus.
Note: This property is only available for iOS devices that support the Apple Penciland are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: obscured
type: Boolean
summary: |
Returns `true` if the touch passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: touchmove
summary: Fired as soon as the device detects movement of a touch.
description: |
Event coordinates are always relative to the view in which the initial touch occurred
properties:
- name: x
summary: X coordinate of the event from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: force
summary: |
The current force value of the touch event.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later and on some Android devices.
type: Number
- name: size
summary: |
The current size of the touch area. Note: This property is only available on some Android devices.
type: Number
- name: maximumPossibleForce
summary: |
Maximum possible value of the force property.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: altitudeAngle
summary: |
A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is
being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0.
Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: timestamp
summary: |
The time (in seconds) when the touch was used in correlation with the system start up.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: azimuthUnitVectorInViewX
summary: |
The x value of the unit vector that points in the direction of the azimuth of the stylus.
Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: azimuthUnitVectorInViewY
summary: |
The y value of the unit vector that points in the direction of the azimuth of the stylus.
Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: obscured
type: Boolean
summary: |
Returns `true` if the touch passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: touchstart
summary: Fired as soon as the device detects a touch gesture.
properties:
- name: x
summary: X coordinate of the event from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: force
summary: |
The current force value of the touch event.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later and on some Android devices.
type: Number
- name: size
summary: |
The current size of the touch area. Note: This property is only available on some Android devices.
type: Number
- name: maximumPossibleForce
summary: |
Maximum possible value of the force property.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: altitudeAngle
summary: |
A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is
being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0.
Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: timestamp
summary: |
The time (in seconds) when the touch was used in correlation with the system start up.
Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: azimuthUnitVectorInViewX
summary: |
The x value of the unit vector that points in the direction of the azimuth of the stylus.
Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: azimuthUnitVectorInViewY
summary: |
The y value of the unit vector that points in the direction of the azimuth of the stylus.
Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.
type: Number
platforms: [iphone, ipad, macos]
- name: obscured
type: Boolean
summary: |
Returns `true` if the touch passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
- name: twofingertap
summary: Fired when the device detects a two-finger tap against the view.
since: { android: "3.0.0" }
properties:
- name: x
summary: X coordinate of the event from the `source` view's coordinate system.
type: Number
- name: y
summary: Y coordinate of the event from the `source` view's coordinate system.
type: Number
- name: obscured
type: Boolean
summary: |
Returns `true` if the tap passed through an overlapping window belonging to another app.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.
platforms: [android]
since: "9.3.0"
methods:
- name: add
summary: Adds a child to this view's hierarchy.
description: |
The child view is added as the last child in this view's hierarchy.
Although all views inherit from <Titanium.UI.View>, not all views are capable of
containing other views. In particular:
* Some views are not designed to be containers at all.
* Some views are special-purpose containers that can only contain certain other
views.
* Some views are top-level containers that cannot (or should not) be added to other views.
#### Non-Container Views
The following views are not intended to act as containers that can hold other
views:
* [ActivityIndicator](Titanium.UI.ActivityIndicator)
* [Button](Titanium.UI.Button)
* [ImageView](Titanium.UI.ImageView)
* [Label](Titanium.UI.Label)
* [ProgressBar](Titanium.UI.ProgressBar)
* [SearchBar](Titanium.UI.SearchBar)
* [Slider](Titanium.UI.Slider)
* [Switch](Titanium.UI.Switch)
* [TableView](Titanium.UI.TableView)
* [TextArea](Titanium.UI.TextArea)
* [TextField](Titanium.UI.TextField)
* [WebView](Titanium.UI.WebView)
Adding children to the these views _may_ be supported on some platforms,
but is not guaranteed to work across platforms. Where it is supported, it may not
work as expected.
For maximum portability, these views should be treated as if they do not support children.
Instead of adding children to these views, applications can positon other views as
siblings. For example, instead of adding a button as a child of a `WebView`, you can add
the button to the web view's parent such that it appears on top of the web view.
#### Special-Purpose Containers
A few view objects act as special-purpose containers--that is, they only manage
certain types of children, and many of them support a special means of adding
these children, instead of the general `add` method. These containers include:
* [ButtonBar](Titanium.UI.ButtonBar) and [TabbedBar](Titanium.UI.iOS.TabbedBar) are designed
to hold their own internally-created buttons, assigned by adding strings to the "labels" array.
Views added using the `add` method are displayed on top of these buttons.
* [Picker](Titanium.UI.Picker). Can only hold `PickerRows` and `PickerColumns`, which
are added using the `add` method. Adding other types of views to a `Picker` is not
supported.
* [TableView](Titanium.UI.TableView) is a specialized container for
`TableViewSection` and `TableViewRow` objects. These objects must be
added using the properties and methods that `TableView` provides
for adding and removing sectons and rows.
On some platforms, it is possible to add arbitrary child views to a table view
using the `add` method. However, this is not guaranteed to work on all platforms,
and in general, should be avoided.
* [TableViewSection](Titanium.UI.TableViewSection) is a specialized container
for `TableViewRow` objects, which _are_ added using the `add` method. The `add` method
on `TableViewSection` can only be used to add `TableViewRow` objects.
* [Toolbar](Titanium.UI.iOS.Toolbar) is designed to hold buttons and certain
other controls, added to its `items` array. Views added using the `add` method are
displayed on top of the controls in the `items` array.
* The `Tab`, `TabGroup`, `NavigationWindow` and `SplitWindow` objects are
special containers that manage windows. These are discussed in the
"Top-Level Containers" section.
#### Top-Level Containers
There are certain top-level containers that are not intended to be added
as the children of other views. These top-level containers include
<Titanium.UI.Window>, <Titanium.UI.iOS.SplitWindow>, <Titanium.UI.NavigationWindow>,
and <Titanium.UI.TabGroup>. Other types of views must be added
to a top-level container in order to be displayed on screen.
The special containers <Titanium.UI.NavigationWindow>,
<Titanium.UI.iOS.SplitWindow>, <Titanium.UI.Tab>, and
<Titanium.UI.TabGroup> manage windows.
These managed windows may be referred to as *children* of the
container, but they are not added using the `add` method.
`Tab` is another kind of special container: it is not itself a top-level container,
but can only be used within a `TabGroup`. You cannot `add` a `Tab` to an arbitrary
container.
parameters:
- name: view
summary: |
View to add to this view's hierarchy.
You may pass an array of views, e.g. `view.add([subview1, subview2]`.
type: [Titanium.UI.View, Array<Titanium.UI.View>]
- name: animate
summary: Animates this view.
description: |
The [Animation](Titanium.UI.Animation) object or dictionary passed to this method defines
the end state for the animation, the duration of the animation, and other properties.
Note that on SDKs older than 9.1.0 - if you use `animate` to move a view, the view's actual *position* is changed, but
its layout properties, such as `top`, `left`, `center` and so on are not changed--these
reflect the original values set by the user, not the actual position of the view.
As of SDK 9.1.0, the final values of the animation will be set on the view just before the `complete` event and/or the callback is fired.
The [rect](Titanium.UI.View.rect) property can be used to determine the actual size and
position of the view.
parameters:
- name: animation
summary: |
Either a dictionary of animation properties or an
[Animation](Titanium.UI.Animation) object.
type: [Titanium.UI.Animation, Dictionary<Titanium.UI.Animation>]
- name: callback
summary: Function to be invoked upon completion of the animation.
type: Callback<Object> # FIXME: iOS appears to fire with the Ti.UI.Animation object, while Android fires with an empty object
optional: true
- name: clearMotionEffects
summary: Removes all previously added motion effects.
description: Use this method together with <Titanium.UI.horizontalMotionEffect> and <Titanium.UI.verticalMotionEffect>.
since: "8.2.0"
platforms: [iphone, ipad, macos]
- name: hide
summary: Hides this view.
parameters:
- name: options
summary: |
Animation options for Android only. **Since SDK 5.1.0 and used only on Android 5.0+**
Determines whether to enable a circular reveal animation.
Note that the default here is equivalent to passing in `{ animated: false }`
type: AnimatedOptions
optional: true
default: "{ animated: false }"
# FIXME: Allow setting platforms/osver on parameters. Sucks we have to stick this in summary!
- name: insertAt
summary: Inserts a view at the specified position in the [children](Titanium.UI.View.children) array.
description: |
Useful if the `layout` property is set to `horizontal` or `vertical`.
parameters:
- name: params
summary: |
Pass an object that specifies the view to insert and optionally at which position (defaults to end)
type: ViewPositionOptions
since: "3.3.0"
platforms: [android, iphone, ipad, macos]
- name: remove
summary: Removes a child view from this view's hierarchy.
parameters:
- name: view
summary: View to remove from this view's hierarchy.
type: Titanium.UI.View
- name: removeAllChildren
summary: Removes all child views from this view's hierarchy.
since: {android: "3.1.0", iphone: "3.1.0", ipad: "3.1.0"}