Skip to content

Commit 4b59455

Browse files
author
Alexander Vakrilov
committed
Merge pull request NativeScript#443 from NativeScript/feature/action-bar-docs
ActionBar: Docs and snippets
2 parents 7adeb29 + 8c62b01 commit 4b59455

File tree

4 files changed

+190
-12
lines changed

4 files changed

+190
-12
lines changed

‎apps/tests/ui/action-bar/action-bar-tests-common.ts‎

Lines changed: 72 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,79 @@
22
import LabelModule = require("ui/label");
33
import helper = require("../helper");
44
import builder = require("ui/builder");
5-
import actionBar = require("ui/action-bar");
65
import button = require("ui/button");
76
import PageModule = require("ui/page");
87

8+
// <snippet module="ui/action-bar" title="ActionBar">
9+
// # ActionBar
10+
// Using a ActionBar requires the action-bar module.
11+
// ``` JavaScript
12+
import actionBarModule = require("ui/action-bar");
13+
// ```
14+
//
15+
// ## Setting Title and Icon
16+
//```XML
17+
// <Page>
18+
// <Page.actionBar>
19+
// {%raw%}<ActionBar title="{{ title }}" android.icon="res://ic_test"/>{%endraw%}
20+
// </Page.actionBar>
21+
// ...
22+
// </Page>
23+
//```
24+
//The icon can only be set in Android platform. Following the design guides it is automatically hidden in Lollipop versions (API level >= 20). You explicitly control its visibility with the `android.iconVisibility' property.
25+
//
26+
//
27+
// ## Setting Custom Title View
28+
//```XML
29+
// <Page loaded="pageLoaded">
30+
// <Page.actionBar>
31+
// <ActionBar title="Title">
32+
// <ActionBar.titleView>
33+
// <StackLayout orientation="horizontal">
34+
// <Button text="1st" />
35+
// <Button text="2nd" />
36+
// <Button text="3rd" />
37+
// </StackLayout>
38+
// </ActionBar.titleView>
39+
// </ActionBar>
40+
// </Page.actionBar>
41+
// ...
42+
// </Page>
43+
//```
44+
//
45+
// ## Setting Action Items
46+
//```XML
47+
// <Page>
48+
// <Page.actionBar>
49+
// <ActionBar title="Title">
50+
// <ActionBar.actionItems>
51+
// <ActionItem text="left" ios.position="left"/>
52+
// <ActionItem text="right" ios.position="right"/>
53+
// <ActionItem text="pop" ios.position="right" android.position="popup"/>
54+
// </ActionBar.actionItems>
55+
// </ActionBar>
56+
// </Page.actionBar>
57+
// ...
58+
// </Page>
59+
//```
60+
//
61+
//The position option is platform specific. The available values are as follows:
62+
// * **Android** - `actionBar`, `actionBarIfRoom` and `popup`. The default is `actionBar`.
63+
// * **iOS** - `left` and `right`. The default is `left`.
64+
//
65+
// ## Setting Navigation Button
66+
//```XML
67+
// <Page>
68+
// <Page.actionBar>
69+
// <ActionBar title="Title">
70+
// <NavigationButton text="go back"/>
71+
// </ActionBar>
72+
// ...
73+
// </Page>
74+
//```
75+
//
76+
// </snippet>
77+
978
export function test_actionItem_inherit_bindingContext() {
1079
var page: PageModule.Page;
1180
var label: LabelModule.Label;
@@ -14,7 +83,7 @@ export function test_actionItem_inherit_bindingContext() {
1483
var pageFactory = function (): PageModule.Page {
1584
page = new PageModule.Page();
1685
page.bindingContext = context;
17-
var actionItem = new actionBar.ActionItem();
86+
var actionItem = new actionBarModule.ActionItem();
1887

1988
actionItem.bind({
2089
sourceProperty: "text",
@@ -110,7 +179,7 @@ export function test_Setting_ActionItems_doesnt_thrown() {
110179

111180
var pageFactory = function (): PageModule.Page {
112181
page = new PageModule.Page();
113-
var actionItem = new actionBar.ActionItem();
182+
var actionItem = new actionBarModule.ActionItem();
114183
actionItem.text = "Item";
115184
page.actionBar.actionItems.addItem(actionItem);
116185

‎ui/action-bar/action-bar-common.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,7 @@ export class ActionBar extends view.View implements dts.ActionBar {
158158
}
159159
}
160160

161-
public shouldShow(): boolean {
161+
public _shouldShow(): boolean {
162162
if (this.title ||
163163
(this.android && this.android.icon) ||
164164
this.navigationButton ||

‎ui/action-bar/action-bar.d.ts‎

Lines changed: 116 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,94 @@
1-
declare module "ui/action-bar" {
1+
/**
2+
* Contains the action bar related classes.
3+
*/
4+
declare module "ui/action-bar" {
25
import observable = require("data/observable");
36
import view = require("ui/core/view");
47
import dependencyObservable = require("ui/core/dependency-observable");
58
import bindable = require("ui/core/bindable");
69
import pages = require("ui/page");
710

11+
/**
12+
* Provides an abstraction over the ActionBar (android) and NavigationBar (iOS).
13+
*/
814
export class ActionBar extends view.View implements view.AddArrayFromBuilder, view.AddChildFromBuilder {
15+
16+
/**
17+
* Gets or sets the action bar title.
18+
*/
919
title: string;
1020

21+
/**
22+
* Gets or sets the title view. When set - replaces the title with a custom view.
23+
*/
24+
titleView: view.View;
25+
26+
/**
27+
* Gets or sets the navigation button (a.k.a. the back button).
28+
*/
1129
navigationButton: NavigationButton;
30+
31+
/**
32+
* Gets the collection of action items.
33+
*/
1234
actionItems: ActionItems;
13-
titleView: view.View;
14-
35+
36+
/**
37+
* Gets the android specific options of the action bar.
38+
*/
1539
android: AndroidActionBarSettings;
1640

41+
/**
42+
* Gets the page that contains the action bar.
43+
*/
1744
page: pages.Page;
1845

19-
shouldShow(): boolean
20-
46+
/**
47+
* Updates the action bar.
48+
*/
2149
update();
2250

2351
//@private
52+
_shouldShow(): boolean
2453
_updateAndroid(menu: android.view.IMenu);
2554
_onAndroidItemSelected(itemId: number): boolean
2655

2756
_addArrayFromBuilder(name: string, value: Array<any>): void;
2857
_addChildFromBuilder(name: string, value: any): void;
29-
3058
//@endprivate
3159
}
3260

61+
/**
62+
* Represents a collection of ActionItems.
63+
*/
3364
export class ActionItems {
65+
/**
66+
* Adds an item to the collection.
67+
* @param item - the item to be added
68+
*/
3469
addItem(item: ActionItem): void;
70+
71+
/**
72+
* Removes an item to the collection.
73+
* @param item - The item to be removed.
74+
*/
3575
removeItem(item: ActionItem): void;
76+
77+
/**
78+
* Gets an array of the current action items in the collection.
79+
*/
3680
getItems(): Array<ActionItem>;
81+
82+
/**
83+
* Gets an item at a specified index.
84+
* @param index - The index.
85+
*/
3786
getItemAt(index: number): ActionItem;
3887
}
3988

89+
/**
90+
* Base class for action items.
91+
*/
4092
export class ActionItemBase extends bindable.Bindable {
4193
/**
4294
* String value used when hooking to tap event.
@@ -53,8 +105,19 @@
53105
*/
54106
public static iconProperty: dependencyObservable.Property;
55107

108+
/**
109+
* Gets or sets the text of the action item.
110+
*/
56111
text: string;
112+
113+
/**
114+
* Gets or sets the icon of the action item.
115+
*/
57116
icon: string;
117+
118+
/**
119+
* Gets the action bar that contains the action item.
120+
*/
58121
actionBar: ActionBar;
59122

60123
/**
@@ -75,24 +138,70 @@
75138
//@endprivate
76139
}
77140

141+
/**
142+
* Represents an action item in the action bar.
143+
*/
78144
export class ActionItem extends ActionItemBase {
145+
/**
146+
* Gets the iOS specific options of the action item.
147+
*/
79148
ios: IOSActionItemSettings;
149+
150+
/**
151+
* Gets the Android specific options of the action item.
152+
*/
80153
android: AndroidActionItemSettings;
81154
}
82155

156+
/**
157+
* Represents Android specific options of the action item.
158+
*/
83159
export interface AndroidActionItemSettings {
160+
/**
161+
* Gets or sets the position of the action item in the action bar.
162+
* 1. actionBar - item is shown in the action bar.
163+
* 2. actionBarIfRoom - item is shown in the action bar if there is room for it. Otherwise it is put in the popup menu.
164+
* 3. popup - item is shown in the popup menu.
165+
*/
84166
position: string;
85167
}
86168

169+
/**
170+
* Represents iOS specific options of the action item.
171+
*/
87172
export interface IOSActionItemSettings {
173+
/**
174+
* Gets or sets the position of the action item in the action bar.
175+
* 1. left - items is shown at the left part of the navigation bar. This is the default value.
176+
* 2. right - items is shown at the right part of the navigation bar.
177+
*/
88178
position: string;
89179
}
90180

181+
/**
182+
* Represents Android specific options of the action bar.
183+
*/
91184
export interface AndroidActionBarSettings {
185+
186+
/**
187+
* Gets or sets the action bar icon.
188+
*/
92189
icon: string;
190+
191+
/**
192+
* Gets or sets the visibility of the action bar icon.
193+
* The icon is visible by default in pre-lollipop (API level < 20) versions of android and is hidden in lollipop (API level >= 20)
194+
* The possible values are:
195+
* 1. auto - the default behavior. This is the default value.
196+
* 2. always - the icon is aways shown.
197+
* 3. never - the icon is aways hidden.
198+
*/
93199
iconVisibility: string;
94200
}
95-
201+
202+
/**
203+
* Represents the navigation (a.k.a. "back") button.
204+
*/
96205
export class NavigationButton extends ActionItemBase {
97206

98207
}

‎ui/frame/frame.ios.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ export class Frame extends frameCommon.Frame {
8484

8585
case enums.NavigationBarVisibility.auto:
8686
var pageInstance: pages.Page = page || this.currentPage;
87-
newValue = this.backStack.length > 0 || (pageInstance && pageInstance.actionBar.shouldShow());
87+
newValue = this.backStack.length > 0 || (pageInstance && pageInstance.actionBar._shouldShow());
8888
newValue = !!newValue; // Make sure it is boolean
8989
break;
9090
}

0 commit comments

Comments
 (0)