blackberry · jasondscott · Apr 30, 2013 · Apr 30, 2013 · Apr 30, 2013 · Apr 30, 2013
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -71,7 +71,8 @@ module.exports = function(grunt) {
 					'src/plugins/gridview/jquery.mobile.gridview.js',
 					'src/plugins/inputValidator/jquery.mobile.inputValidator.js',
 					'src/plugins/progressbar/jquery.mobile.progressbar.js',
-					'src/plugins/dropdown/jquery.mobile.dropdown.js'
+					'src/plugins/dropdown/jquery.mobile.dropdown.js',
+					'src/plugins/applicationmenu/jquery.mobile.applicationmenu.js'
 				],
 				dest: 'compiled/<%= pkg.name %>.js'
 			},
@@ -85,7 +86,8 @@ module.exports = function(grunt) {
 					'src/plugins/overflowMenu/jquery.mobile.overflowMenu.css',
 					'src/plugins/progressbar/jquery.mobile.progressbar.css',
 					'src/transitions/jquery.mobile.transition.cover.css',
-					'src/plugins/dropdown/jquery.mobile.dropdown.css'
+					'src/plugins/dropdown/jquery.mobile.dropdown.css',
+					'src/plugins/applicationmenu/jquery.mobile.applicationmenu.css'
 				],
 				dest: 'compiled/<%= pkg.name %>.css'
 			},

diff --git a/docs/README.md b/docs/README.md
@@ -162,6 +162,60 @@ A complete example of the action bar can be found [here](/kitchenSink/actionbar_
 
 To see all the diffent ways to have your actionbar look [here](/kitchenSink/actionbar.html).
 
+Application Menu
+--------------
+![Application Menu](/figures/applicationMenu.png)
+
+To create an __application menu__, first create a top-panel ```data-role="panel"``` with the following options
+* ```data-position="top"``` - To place it on the top of the screen
+* ```data-display="push"``` - So that when we open it, it uses the push animation
+* ```data-theme="a"``` - So that it is using the dark theme
+* ```data-dark-modal="true"``` - So that the content becomes opaque when the menu is open
+
+To make the panel work as an __application menu__, add a ```div``` with ```data-role="applicationmenu"```, 
+and inside this ```div``` add the desired __menu action items__.
+
+```
+<div data-role="panel" id="top" data-dark-modal="true" data-position="top" data-display="push" data-theme="a" class="">
+	<div data-role="applicationmenu">
+		<a data-role="action" href="#">
+			<img src="img/Core_applicationmenu_icon_help.png" alt="" />
+			<p>Help</p>
+		</a>
+		<a data-role="action" href="#">
+			<img src="img/generic_81_81_placeholder.png" alt="" />
+			<p>Option1</p>
+		</a>			
+		<a data-role="SettingsActionItem" href="#">
+			<img src="img/Core_applicationmenu_icon_settings.png" alt="" />
+			<p>Settings</p>
+		</a>	
+	</div>
+</div>
+```
+
+Notice that each__menu action item__ is specified in the following format:
+```
+<a data-role="action" href="desired_url">
+	<img src="action_icon_url" />
+	<p>action_name</p>
+</a>
+```
+
+__Menu action items__  can have one of two data-roles (case sensitive):
+* ```data-role="SettingsActionItem"``` for a "Settings" item 
+*  ```data-role="action"``` for any other action items.  
+
+```data-role="SettingsActionItem"``` is only needed if the action is the only one in the menu. 
+It ensures that the action is placed on the right side when it is the only item.
+
+ There are several key points to consider when building an application menu:
+* There is a maximum of 5 action items that can be displayed in the menu. Any extra items will not show. 
+* The order of the menu actions from left to right is determined by the order of the items in the markup from top to bottom. 
+* The default icon size used in each action item is 81x81 px. 
+
+To see a more complete example of the application menu look [here](/kitchenSink/application_menu.html).
+
 Overflow Menus (Panels)
 --------------
 To create an overflow menu use the [jQuery Mobile panel](http://jquerymobile.com/demos/1.3.0-beta.1/docs/panels/index.html).

diff --git a/docs/figures/applicationMenu.png b/docs/figures/applicationMenu.png
diff --git a/kitchenSink/application_menu.html b/kitchenSink/application_menu.html
@@ -0,0 +1,79 @@
+<!DOCTYPE HTML>
+<!--
+* Copyright 2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+-->
+
+<html>
+	<head>
+		<meta charset="utf-8">
+		<title>Application Menu</title>
+		<!--<meta name="viewport" content="width=device-width, initial-scale=1">-->
+		<link rel="stylesheet" href="lib/BlackBerry-JQM-all.css" />
+		<script src="lib/BlackBerry-JQM-all.js"></script>
+		<script type="text/javascript" src="lib/app.js"></script>
+	</head>
+	<body>
+		<div id="applicationMenu" data-role="page">
+			<!-- This is how you set up your application menu (top panel) -->
+			<div data-role="panel" id="top" data-dark-modal="true" data-position="top" data-display="push" data-theme="a" class="">
+				<div data-role="applicationmenu">
+
+					<a data-role="action" href="#">
+						<img src="img/Core_applicationmenu_icon_help.png" alt="" />
+						<p>Help</p>
+					</a>
+					<a data-role="action" href="#">
+						<img src="img/generic_81_81_placeholder.png" alt="" />
+						<p>Option1</p>
+					</a>
+					<a data-role="action" href="#">
+						<img src="img/generic_81_81_placeholder.png" alt="" />
+						<p>Option2</p>
+					</a>
+					<a data-role="action" href="#">
+						<img src="img/generic_81_81_placeholder.png" alt="" />
+						<p>Option3</p>
+					</a>					
+					<!-- data-role=SettingsActionItem places the settings action on the right side when it is the only item in the menu -->
+					<a data-role="SettingsActionItem" href="#">
+						<img src="img/Core_applicationmenu_icon_settings.png" alt="" />
+						<p>Settings</p>
+					</a>
+
+					<!-- Maximum of 5 actions. Any extra actions will not appear on the menu -->
+					<a data-role="action" href="#">
+						<img src="img/generic_81_81_placeholder.png" alt="" />
+						<p>This option should not show up</p>
+					</a>			
+				</div>
+			</div>
+
+			<div data-role="header" data-theme="c">
+				<h1>Application Menu</h1>
+			</div><!-- /header -->
+			<div data-role="content">
+				<!-- Put your page content here -->
+				<a id="menuBtn" data-role="button" href="#top">Open application menu </a>
+				<h2 id="simulInst" style="text-align: center">Open application menu by firing "blackberry.event.swipedown"<h2>
+			</div><!-- /content -->
+
+			<div data-role="footer" data-position="fixed">
+				<div id="action-bar-area" data-role="actionbar">
+					<div data-role="back"></div>
+				</div>
+			</div>
+		</div><!-- /page -->
+	</body>
+</html>
diff --git a/kitchenSink/img/Core_applicationmenu_icon_help.png b/kitchenSink/img/Core_applicationmenu_icon_help.png
diff --git a/kitchenSink/img/Core_applicationmenu_icon_settings.png b/kitchenSink/img/Core_applicationmenu_icon_settings.png
diff --git a/kitchenSink/index.html b/kitchenSink/index.html
@@ -33,6 +33,7 @@ <h1>BB10 JQM KitchenSink</h1>
 					<li data-role="list-divider">Light Theme</li>
 					<li><a href="activityIndicator.html">Activity Indicator</a></li>
 					<li><a href="actionbar_sample.html">Action Bar Sample</a></li>
+					<li><a href="application_menu.html">Application Menu</a></li>
 					<li><a href="bb_activity_indicator.html">BB10 Activity Indicator</a></li>
 					<li><a href="building_blocks.html" data-transition="cover" >Building Blocks - Light</a></li>
 					<li><a href="buttons.html">Buttons</a></li>

diff --git a/kitchenSink/lib/app.js b/kitchenSink/lib/app.js
@@ -21,6 +21,9 @@ App.init = function () {
 	$("#actionBarSample").live("pageinit", function() {
 		App.page.actionBarSample.init();
 	});
+	$('#applicationMenu').live("pageinit", function() {
+		App.page.applicationMenu.init();
+	});
 }
 
 App.utils = {
@@ -38,7 +41,8 @@ App.page = {
 	progress: {},
 	slider: {},
 	toggle: {},
-	actionBarSample: {}
+	actionBarSample: {},
+	applicationMenu: {}
 }
 
 App.page.activity.init = function() {
@@ -193,7 +197,17 @@ App.page.actionBarSample.init = function() {
 	});
 }
 
-
+App.page.applicationMenu.init = function() {
+	if(typeof blackberry != 'undefined'){
+		blackberry.event.addEventListener('swipedown', function(){
+			$('#top').panel("open");
+		});
+		$('#menuBtn').css('display','none');
+	}
+	else{
+		$('#simulInst').css('display','none');
+	}
+}
 
 App.init();
 
diff --git a/src/lib/panel.js b/src/lib/panel.js
@@ -177,6 +177,11 @@ $.widget( "mobile.panel", $.mobile.widget, {
 			panelInnerHeight = self._panelInner.outerHeight(),
 			expand = panelInnerHeight > $.mobile.getScreenHeight();
 
+		if( self.options.position === "top" ){
+			var panelHeight = self.element.height();
+			self._setVerticalCssTransform( self._wrapper, panelHeight );
+		}
+
 		if ( expand || !self.options.positionFixed ) {
 			if ( expand ) {
 				self._unfixPanel();

diff --git a/src/plugins/applicationmenu/assets/core_applicationmenu_pressed.png b/src/plugins/applicationmenu/assets/core_applicationmenu_pressed.png
diff --git a/src/plugins/applicationmenu/jquery.mobile.applicationmenu.css b/src/plugins/applicationmenu/jquery.mobile.applicationmenu.css
@@ -0,0 +1,107 @@
+/*
+* Copyright 2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/* application menu styling */
+
+.application-menu{
+	display:-webkit-box;
+	-webkit-box-orient: horizontal;
+}
+
+/* hide any extra action item */
+.application-menu .ui-link:not(.visible){
+	display:none;
+}
+
+/* menu action item styling */
+.application-menu-item.visible {
+	display:block;
+	width:20%;
+	height: 100%;
+	text-align:center;
+}
+/* item separation for 2 items in the bar */
+.application-menu-item:first-child:nth-last-child(2){
+	margin-right: 60%;
+}
+/* item separation for 3 items in the bar */
+.application-menu-item:first-child:nth-last-child(3),
+.application-menu-item:first-child:nth-last-child(3) ~ a {
+	margin-right: 20%;
+}
+/* item separation for 4 items in the bar */
+.application-menu-item:first-child:nth-last-child(4),
+.application-menu-item:first-child:nth-last-child(4) ~ a {
+	margin-right: 6.6666%;
+}
+
+.application-menu-item-settings{
+	margin-left: 80%;	
+}
+
+/* override panel padding */		
+.ui-panel-inner.ui-panel-inner-application-menu{
+	padding:0;
+}
+
+/* styling for the action-pressed indicator */
+.application-menu-item-pressed-indicator{
+	width:95px;
+	height:6px;
+	margin: 0 auto;
+}
+
+.application-menu-item-pressed-indicator.pressed{
+	background-image: url('images_bb/core_applicationmenu_pressed.png');
+}
+
+.application-menu-item-image{
+	margin-top:8px;
+	width:81px;
+	height:81px;
+}
+.application-menu-item-text{
+	width:100%;
+	font-size:0.625em;
+	font-weight:normal;
+	color: #FAFAFA;
+
+}
+
+.application-menu-item-text p{
+	text-overflow: ellipsis;
+	width: 100%;
+	white-space: nowrap;
+	overflow: hidden;
+	margin: 0;
+}
+
+.application-menu-item-text{
+	margin-bottom:6px;
+}
+
+@media screen and (orientation: landscape), screen and (device-aspect-ratio: 1/1){
+	.application-menu-item-pressed-indicator{
+		height:2px;
+	}
+	.application-menu-item-image{
+		margin-top:0;
+	}
+	.application-menu-item-text{
+		margin-top:-8px;
+	}
+
+}