BlackBerry menu ordinals and priorities, illustrated - Part 1: Basics

This is an article aimed at beginners (though it might be useful for a refresher for experienced BlackBerry coders too). If all of this seems like old hat though, check out Part 2 of this mini-series to get more in-depth with BlackBerry system menu item values, altering the system menus, removing unwanted system menu items, etc.

Most BlackBerry menus I’ve seen have been constructed something like this:

	protected void makeMenu(Menu menu, int instance) {
		menu.add(new MenuItem("Item A", 100, 100) { public void run() {}});
		menu.add(new MenuItem("Item B", 100, 100) { public void run() {}});
		menu.add(new MenuItem("Item C", 100, 100) { public void run() {}});
	}

Nothing wrong with that - it’s valid in many circumstances. But what are those two numbers for?

The javadocs say that the first is the ordinal and the second the priority of the menu item.

The basics of MenuItem ordinals and priorities

Ordinal

Ordinal is straightforward, it’s the position of the item in the menu. Menu items with equal ordinals appear in the order that they were added, top to bottom. The first example gives this:

Changing the ordinals to be in ascending order:

	protected void makeMenu(Menu menu, int instance) {
		menu.add(new MenuItem("Item A", 100, 100) { public void run() {}});
		menu.add(new MenuItem("Item B", 200, 100) { public void run() {}});
		menu.add(new MenuItem("Item C", 300, 100) { public void run() {}});
	}

Gives the same thing:

Changing them to be in descending order:

	protected void makeMenu(Menu menu, int instance) {
		menu.add(new MenuItem("Item A", 300, 100) { public void run() {}});
		menu.add(new MenuItem("Item B", 200, 100) { public void run() {}});
		menu.add(new MenuItem("Item C", 100, 100) { public void run() {}});
	}

Gives:

Priority

Priority is just what menu item is selected when you initially open the menu. The menu item with the lowest priority will be selected initially. As the above examples show, if there are several items which all share the lowest priority in the menu, the topmost of those will be selected:

Changing the priority:

	protected void makeMenu(Menu menu, int instance) {
		menu.add(new MenuItem("Item A", 100, 100) { public void run() {}});
		menu.add(new MenuItem("Item B", 100, 0) { public void run() {}});
		menu.add(new MenuItem("Item C", 100, 100) { public void run() {}});
	}

And a different menu item is selected by default:

So:
ordinal = position in menu (lowest=highest)
If two menu items have the same ordinal, the first one added will be higher than the second.
priority = initially selected menu item (lowest=initially selected)
If two menu items have the same priority, the one that appears higher in the menu will be selected.

Negative numbers

Finally, what if we make one of the ordinal or priority numbers negative?

So 0 or greater.