0
# UI Components and Layouts
1

2
Comprehensive set of native UI components and layout containers for building mobile application interfaces. All components render as native iOS and Android controls, providing platform-specific look, feel, and performance.
3

4
## Capabilities
5

6
### Core UI Base Classes
7

8
Foundation classes that all UI elements inherit from, providing common functionality for styling, events, and layout.
9

10
```typescript { .api }
11
/**
12
 * Base class for all UI elements providing core functionality
13
 */
14
class ViewBase {
15
  // Core properties
16
  id: string;
17
  className: string;
18
  style: Style;
19
  parent: ViewBase;
20
  isLoaded: boolean;
21
  
22
  // Event handling
23
  on(eventName: string, callback: Function): void;
24
  off(eventName: string, callback?: Function): void;
25
  notify(data: EventData): void;
26
  
27
  // Lifecycle methods
28
  addEventListener(arg: string | EventData, callback?: Function): void;
29
  removeEventListener(arg: string | EventData, callback?: Function): void;
30
}
31

32
/**
33
 * Enhanced base class with layout and visual properties
34
 */
35
class View extends ViewBase {
36
  // Layout properties
37
  width: number | string;
38
  height: number | string;
39
  minWidth: number;
40
  minHeight: number;
41
  margin: string | number;
42
  padding: string | number;
43
  
44
  // Visual properties
45
  visibility: "visible" | "hidden" | "collapse";
46
  opacity: number;
47
  backgroundColor: string;
48
  color: string;
49
  
50
  // Transform properties
51
  translateX: number;
52
  translateY: number;
53
  scaleX: number;
54
  scaleY: number;
55
  rotate: number;
56
  
57
  // Layout methods
58
  measure(widthMeasureSpec: number, heightMeasureSpec: number): void;
59
  layout(left: number, top: number, right: number, bottom: number): void;
60
  getMeasuredWidth(): number;
61
  getMeasuredHeight(): number;
62
}
63
```
64

65
### Layout Containers
66

67
Layout containers that manage the positioning and sizing of child elements using different layout algorithms.
68

69
```typescript { .api }
70
/**
71
 * Base class for all layout containers
72
 */
73
class LayoutBase extends View {
74
  addChild(view: View): void;
75
  insertChild(child: View, atIndex: number): void;
76
  removeChild(child: View): void;
77
  removeChildren(): void;
78
  getChildAt(index: number): View;
79
  getChildIndex(child: View): number;
80
  getChildrenCount(): number;
81
  
82
  // Layout properties
83
  padding: string | number;
84
  paddingTop: number;
85
  paddingRight: number;
86
  paddingBottom: number;
87
  paddingLeft: number;
88
}
89

90
/**
91
 * Stack layout - arranges children in a single row or column
92
 */
93
class StackLayout extends LayoutBase {
94
  orientation: "vertical" | "horizontal";
95
}
96

97
/**
98
 * Grid layout - arranges children in rows and columns
99
 */
100
class GridLayout extends LayoutBase {
101
  columns: string; // e.g., "*, 100, auto"
102
  rows: string;    // e.g., "*, 50, auto"
103
  
104
  static setColumn(view: View, value: number): void;
105
  static getColumn(view: View): number;
106
  static setRow(view: View, value: number): void;
107
  static getRow(view: View): number;
108
  static setColumnSpan(view: View, value: number): void;
109
  static setRowSpan(view: View, value: number): void;
110
}
111

112
/**
113
 * Absolute layout - positions children using absolute coordinates
114
 */
115
class AbsoluteLayout extends LayoutBase {
116
  static setLeft(view: View, value: number): void;
117
  static setTop(view: View, value: number): void;
118
  static getLeft(view: View): number;
119
  static getTop(view: View): number;
120
}
121

122
/**
123
 * Dock layout - docks children to sides and fills remaining space
124
 */
125
class DockLayout extends LayoutBase {
126
  stretchLastChild: boolean;
127
  
128
  static setDock(view: View, value: "left" | "top" | "right" | "bottom"): void;
129
  static getDock(view: View): string;
130
}
131

132
/**
133
 * Wrap layout - arranges children in rows, wrapping to new row when needed
134
 */
135
class WrapLayout extends LayoutBase {
136
  orientation: "horizontal" | "vertical";
137
  itemWidth: number;
138
  itemHeight: number;
139
}
140

141
/**
142
 * Flexbox layout - CSS flexbox-style layout
143
 */
144
class FlexboxLayout extends LayoutBase {
145
  flexDirection: "row" | "row-reverse" | "column" | "column-reverse";
146
  flexWrap: "nowrap" | "wrap" | "wrap-reverse";
147
  justifyContent: "flex-start" | "flex-end" | "center" | "space-between" | "space-around";
148
  alignItems: "flex-start" | "flex-end" | "center" | "baseline" | "stretch";
149
  alignContent: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "stretch";
150
}
151
```
152

153
**Layout Usage Examples:**
154

155
```typescript
156
import { StackLayout, GridLayout, Button, Label } from "tns-core-modules";
157

158
// Stack layout example
159
const stack = new StackLayout();
160
stack.orientation = "vertical";
161

162
const header = new Label();
163
header.text = "Welcome";
164
stack.addChild(header);
165

166
const button = new Button();
167
button.text = "Click Me";
168
stack.addChild(button);
169

170
// Grid layout example
171
const grid = new GridLayout();
172
grid.columns = "*, 100"; // flexible, fixed 100
173
grid.rows = "auto, *";   // auto-size, flexible
174

175
const title = new Label();
176
title.text = "Title";
177
GridLayout.setColumn(title, 0);
178
GridLayout.setRow(title, 0);
179
GridLayout.setColumnSpan(title, 2);
180
grid.addChild(title);
181
```
182

183
### Basic UI Controls
184

185
Fundamental UI controls for user interaction and content display.
186

187
```typescript { .api }
188
/**
189
 * Clickable button control
190
 */
191
class Button extends View {
192
  text: string;
193
  textWrap: boolean;
194
  
195
  // Events
196
  static tapEvent: "tap";
197
}
198

199
/**
200
 * Text display control
201
 */
202
class Label extends View {
203
  text: string;
204
  textWrap: boolean;
205
  textAlignment: "left" | "center" | "right";
206
  
207
  // Rich text support
208
  formattedText: FormattedString;
209
}
210

211
/**
212
 * Single-line text input control
213
 */
214
class TextField extends EditableTextBase {
215
  text: string;
216
  hint: string;
217
  secure: boolean;
218
  keyboardType: "datetime" | "phone" | "number" | "url" | "email";
219
  returnKeyType: "done" | "next" | "go" | "search" | "send";
220
  autocapitalizationType: "none" | "words" | "sentences" | "allCharacters";
221
  autocorrect: boolean;
222
  
223
  // Events
224
  static textChangeEvent: "textChange";
225
  static returnPressEvent: "returnPress";
226
  
227
  dismissSoftInput(): void;
228
}
229

230
/**
231
 * Multi-line text input control
232
 */
233
class TextView extends EditableTextBase {
234
  text: string;
235
  hint: string;
236
  editable: boolean;
237
  maxLines: number;
238
}
239

240
/**
241
 * Base class for editable text controls
242
 */
243
class EditableTextBase extends View {
244
  keyboardType: string;
245
  returnKeyType: string;
246
  autocapitalizationType: string;
247
  autocorrect: boolean;
248
  updateTextTrigger: "focusLost" | "textChanged";
249
  
250
  dismissSoftInput(): void;
251
}
252

253
/**
254
 * Image display control
255
 */
256
class Image extends View {
257
  src: string | ImageSource;
258
  imageSource: ImageSource;
259
  isLoading: boolean;
260
  stretch: "none" | "aspectFill" | "aspectFit" | "fill";
261
  loadMode: "sync" | "async";
262
  
263
  // Events
264
  static isLoadingChangeEvent: "isLoadingChange";
265
}
266

267
/**
268
 * Toggle switch control
269
 */
270
class Switch extends View {
271
  checked: boolean;
272
  
273
  // Events
274
  static checkedChangeEvent: "checkedChange";
275
}
276

277
/**
278
 * Numeric slider control
279
 */
280
class Slider extends View {
281
  value: number;
282
  minValue: number;
283
  maxValue: number;
284
  
285
  // Events
286
  static valueChangeEvent: "valueChange";
287
}
288

289
/**
290
 * Progress indicator control
291
 */
292
class Progress extends View {
293
  value: number;
294
  maxValue: number;
295
}
296

297
/**
298
 * Loading indicator control
299
 */
300
class ActivityIndicator extends View {
301
  busy: boolean;
302
}
303
```
304

305
### Advanced UI Controls
306

307
Sophisticated controls for complex user interactions and data display.
308

309
```typescript { .api }
310
/**
311
 * List view for displaying collections of data
312
 */
313
class ListView extends View {
314
  items: any[] | ObservableArray<any>;
315
  itemTemplate: string | Template;
316
  itemTemplateSelector: Function;
317
  separatorColor: string;
318
  rowHeight: number;
319
  
320
  // Events
321
  static itemLoadingEvent: "itemLoading";
322
  static itemTapEvent: "itemTap";
323
  static loadMoreItemsEvent: "loadMoreItems";
324
  
325
  refresh(): void;
326
  scrollToIndex(index: number): void;
327
  isItemAtIndexVisible(index: number): boolean;
328
}
329

330
/**
331
 * Segmented control for selecting from options
332
 */
333
class SegmentedBar extends View {
334
  items: SegmentedBarItem[];
335
  selectedIndex: number;
336
  selectedBackgroundColor: string;
337
  
338
  // Events
339
  static selectedIndexChangeEvent: "selectedIndexChange";
340
}
341

342
class SegmentedBarItem {
343
  title: string;
344
}
345

346
/**
347
 * Date picker control
348
 */
349
class DatePicker extends View {
350
  year: number;
351
  month: number;
352
  day: number;
353
  date: Date;
354
  minDate: Date;
355
  maxDate: Date;
356
  
357
  // Events
358
  static dateChangeEvent: "dateChange";
359
}
360

361
/**
362
 * Time picker control
363
 */
364
class TimePicker extends View {
365
  hour: number;
366
  minute: number;
367
  time: Date;
368
  minHour: number;
369
  maxHour: number;
370
  minuteInterval: number;
371
  
372
  // Events
373
  static timeChangeEvent: "timeChange";
374
}
375

376
/**
377
 * List picker for selecting from options
378
 */
379
class ListPicker extends View {
380
  items: any[];
381
  selectedIndex: number;
382
  selectedValue: any;
383
  
384
  // Events
385
  static selectedIndexChangeEvent: "selectedIndexChange";
386
}
387

388
/**
389
 * Web view for displaying web content
390
 */
391
class WebView extends View {
392
  url: string;
393
  src: string;
394
  canGoBack: boolean;
395
  canGoForward: boolean;
396
  
397
  loadUrl(url: string): void;
398
  goBack(): void;
399
  goForward(): void;
400
  reload(): void;
401
  
402
  // Events
403
  static loadStartedEvent: "loadStarted";
404
  static loadFinishedEvent: "loadFinished";
405
}
406
```
407

408
### Navigation and Container Controls
409

410
Controls for organizing content and managing navigation within applications.
411

412
```typescript { .api }
413
/**
414
 * Application page container
415
 */
416
class Page extends View {
417
  content: View;
418
  actionBar: ActionBar;
419
  navigationContext: any;
420
  frame: Frame;
421
  
422
  // Events
423
  static loadedEvent: "loaded";
424
  static navigatedToEvent: "navigatedTo";
425
  static navigatedFromEvent: "navigatedFrom";
426
  
427
  // Modal methods
428
  showModal(moduleName: string, context?: any, closeCallback?: Function, fullscreen?: boolean): void;
429
  closeModal(...args: any[]): void;
430
}
431

432
/**
433
 * Navigation frame container
434
 */
435
class Frame extends View {
436
  currentPage: Page;
437
  currentEntry: NavigationEntry;
438
  backStack: BackstackEntry[];
439
  animated: boolean;
440
  
441
  navigate(entry: string | NavigationEntry): void;
442
  goBack(to?: BackstackEntry): void;
443
  canGoBack(): boolean;
444
  
445
  // Events
446
  static navigatingToEvent: "navigatingTo";
447
  static navigatedToEvent: "navigatedTo";
448
}
449

450
interface NavigationEntry {
451
  moduleName?: string;
452
  context?: any;
453
  animated?: boolean;
454
  transition?: NavigationTransition;
455
  backstackVisible?: boolean;
456
  clearHistory?: boolean;
457
}
458

459
/**
460
 * Action bar for page headers
461
 */
462
class ActionBar extends View {
463
  title: string;
464
  navigationButton: NavigationButton;
465
  actionItems: ActionItems;
466
  flat: boolean;
467
}
468

469
class ActionItem extends ViewBase {
470
  text: string;
471
  icon: string;
472
  position: "left" | "right" | "popup";
473
  
474
  // Events
475
  static tapEvent: "tap";
476
}
477

478
/**
479
 * Scrollable content container
480
 */
481
class ScrollView extends ContentView {
482
  orientation: "horizontal" | "vertical";
483
  scrollBarIndicatorVisible: boolean;
484
  isScrollEnabled: boolean;
485
  
486
  scrollToVerticalOffset(value: number, animated: boolean): void;
487
  scrollToHorizontalOffset(value: number, animated: boolean): void;
488
  
489
  // Events
490
  static scrollEvent: "scroll";
491
}
492

493
/**
494
 * Content container view
495
 */
496
class ContentView extends View {
497
  content: View;
498
  layoutView: View;
499
}
500
```
501

502
**Advanced Controls Usage Examples:**
503

504
```typescript
505
import { ListView, Page, ObservableArray } from "tns-core-modules";
506

507
// ListView with data binding
508
const listView = new ListView();
509
const items = new ObservableArray([
510
  { name: "Item 1", description: "First item" },
511
  { name: "Item 2", description: "Second item" }
512
]);
513

514
listView.items = items;
515
listView.on(ListView.itemTapEvent, (args) => {
516
  console.log("Tapped item:", args.index);
517
});
518

519
// Page with navigation
520
const page = new Page();
521
page.on(Page.navigatedToEvent, (args) => {
522
  console.log("Navigated to page");
523
});
524

525
// Modal dialog
526
page.showModal("modal-page", { data: "context" }, (result) => {
527
  console.log("Modal closed with result:", result);
528
});
529
```