Kah – The Developer

In Building a Menu for your Android (V1.0 R1) App, a menu was created for an application. The context menu can create menus based on the current view that has focus.

In order to create context menus, the application needs to know which views will have a menu. This is done by calling registerForContextMenu with the view. In this example, a context menu will be created for two text views.

 1 package com.android.Context;
 2
 3 import android.app.Activity;
 4 import android.os.Bundle;
 5 import android.view.ContextMenu;
 6 import android.view.MenuItem;
 7 import android.view.View;
 8 import android.widget.TextView;
 9
10 public class Context extends Activity {
11   /**
12    * This will keep track of which item is selected.
13    */
14   public String checkedItem = "";
15   
16   @Override
17   public void onCreate(Bundle savedInstanceState) {
18     super.onCreate(savedInstanceState);
19     setContentView(R.layout.main);
20
21     registerForContextMenu(findViewById(R.id.primaryText));
22     registerForContextMenu(findViewById(R.id.secondaryText));
23   }
24

To set what gets displayed in the menu, the method onCreateContextMenu is overridden. This method will be told which view the context menu is being built for. Depending on the type of view that is passed in, the menuInfo parameter provides additional information. In this example, the information is not used.

25   public void onCreateContextMenu(
26       ContextMenu menu,
27       View v,
28       ContextMenu.ContextMenuInfo menuInfo)
29   {
30     // Show different menu items, depending on what is
31     // selected.
32     if (v.getId() == R.id.primaryText) 
33     {
34       menu.setHeaderTitle("Primary context");
35       addMenuItem(menu, "Primary 1", true);
36       addMenuItem(menu, "Primary 2", true);
37       addMenuItem(menu, "Primary 3", false);
38     }
39     else
40     {
41       menu.setHeaderTitle("Secondary context");
42       addMenuItem(menu, "Secondary 1", true);  
43       addMenuItem(menu, "Secondary 2", true);
44       addMenuItem(menu, "Secondary 3", false);
45     }    
46   }
47   
48   public MenuItem addMenuItem(ContextMenu menu,
49       String itemName,
50       boolean checkable)
51   {
52     MenuItem item = menu.add(itemName);
53     item.setCheckable(checkable);
54
55     if (itemName.equals(checkedItem))
56     {
57       item.setChecked(true);
58     }
59     return item;
60   }
61

Finally, to handle item selections from the context menu, the onContextItemSelected method is overridden. In the following example, the method will simply update a text view to display what was last selected.

62   public boolean onContextItemSelected(MenuItem item)
63   {
64     TextView statusText = (TextView) findViewById(R.id.statusView);
65     
66     if (item.isCheckable() == true)
67     {
68       // Visually display what is checked.
69       checkedItem = item.getTitle().toString();
70     }
71     
72     statusText.setText("Last item " + item.getTitle());
73     return true;
74   }
75 }
76

At line 57, notice the call to set the “checked” menu item, even though the method handling the event will also be given the menu item. It may seem like it is possible simply call the setChecked method in the onContextItemSelected method, but, if you try it with this example, you’ll notice that the menu item will NEVER be checked. This is because the method onCreateContextMenu will be called every time the context menu is going to be shown (with, possibly, a different instance of the ContextMenu). In doing so, a new instance of the menu items are added to the menu via the call to the addMenuItem method.

If you compare this example with that of Building a Menu for your Android (V1.0 R1) App, you’ll notice that they follow a similar pattern for setting up menus – override the menu creation method to control what gets shown in the menu and override the receiving selection event method to control what happens when an item is selected. In fact, this same pattern is followed for an options menu (override onCreateOptionsMenu to set what gets put in there).

In Building a simple menu in Android, a menu was built using the MenuBuilder. Since the release of version 1.0 (release 1), MenuBuilder has been removed. In this tutorial, we’ll set up a custom menu that gets displayed when the menu button is pressed.

To add the menu for your application, your activity needs to override the onCreateOptionsMenu method. The method will be given the instance of the menu to popuplate. Our overridden method will add the items to the instance that is given. To control what happens when an item on the menu is selected, override the onOptionsItemSelected method. Here is the first part of the code that sets up the activity and adds a couple of items to our menu:

 1 package com.android.menu;
 2
 3 import android.app.Activity;
 4 import android.app.AlertDialog;
 5 import android.os.Bundle;
 6 import android.view.Menu;
 7 import android.view.MenuInflater;
 8 import android.view.MenuItem;
 9 import android.view.SubMenu;
10
11 public class MenuDemo extends Activity
12 {
13   /** 
14    * Called when the activity is first created. 
15    */
16   @Override
17   public void onCreate(Bundle savedInstanceState) 
18   {
19     super.onCreate(savedInstanceState);
20     setContentView(R.layout.main);      
21   }
22     
23   /**
24    * {@inheritDoc}
25    */
26   @Override
27   public boolean onCreateOptionsMenu(Menu menu) 
28   {
29     super.onCreateOptionsMenu(menu);
30     
31     MenuItem item = menu.add("Painting");
32     item.setIcon(R.drawable.paint);
33     
34     item = menu.add("Photos");
35     item.setIcon(R.drawable.photos);
36     

The call to to the setIcon method attachs an image to the menu item. In the example above, the images have been placed in the appropriate resources directory and is being referenced from there.

The items added so far are top level items. Now let’s say we want to attach a submenu. This is as easy as calling the addSubMenu method.

37     SubMenu subScience = menu.addSubMenu(
38         R.string.scienceMenuName);
39     subScience.setIcon(R.drawable.science);
40

To add items to our submenu, we can create the menu items programatically (like we did with the top level menu). However, just to show you another way of setting up the menu, we’ll use load up a menu specified by a menu XML file here instead. You can use the Android Menu Editor to edit the XML if you want (in Eclipse, create an XML file and then right click on the file Open With -> Android Menu Editor) or you can use the text editor to manually create the XML. Below is the contents of the XML file that I used:

1 <menu xmlns:android="http://schemas.android.com/apk/res/android">
2   <item android:title="Physics" />
3   <item android:title="Chemistry" />
4   <item android:title="Biology" />
5 </menu>
6

It should be noted that we could have also created our top level menu the same way! The loading of the menu from an XML file is done through the use of a MenuInflater.

41     // Now, inflate our submenu.
42     MenuInflater inflater = new MenuInflater(this);
43     inflater.inflate(R.menu.menu, subScience);
44

Of course, once the menu has been loaded from an XML file, we can still add items to the submenu.

45     // Programatically, add one item to the submenu.
46     subScience.add("Meteorology");
47

To make the menu displayable when the menu button is pressed, the method needs to return true.

48     // Return true so that the menu gets displayed.
49     return true;
50   }
51

With the menu setup, we now override the onOptionsItemSelected method to handle menu selections. The selected menu item is given back as the method parameter. In this example, the an alert dialog simply pops up, showing what item was selected.

52   /**
53    * {@inheritDoc}
54    */
55   public boolean onOptionsItemSelected(MenuItem item)
56   {
57
58     if (item.hasSubMenu() == false)
59     {
60       // For this demo, lets just give back what
61       // we found.
62       AlertDialog.Builder dialogBuilder = new 
63         AlertDialog.Builder(this);
64   
65       dialogBuilder.setMessage(" You selected " +
66           item.getTitle());
67   
68       dialogBuilder.setCancelable(true);
69       dialogBuilder.create().show();
70     }
71     
72     // Consume the selection event.
73     return true;
74   }
75 }
76

Creating a custom view is as simple as inheriting from the View class and overriding the methods that need to be overridden. In this example, a custom button is implemented in this way. The button shall feature a labelled image (i.e. an image with text underneath).

1   public class CustomImageButton extends View {
2       private final static int WIDTH_PADDING = 8;
3       private final static int HEIGHT_PADDING = 10;
4       private final String label;
5       private final int imageResId;
6       private final Bitmap image;
7       private final InternalListener listenerAdapter = new InternalListener();
8

The constructor can take in the parameters to set the button image and label.

9       /**
10       * Constructor.
11       *
12       * @param context
13       *        Activity context in which the button view is being placed for.
14       *
15       * @param resImage
16       *        Image to put on the button. This image should have been placed
17       *        in the drawable resources directory.
18       *
19       * @param label
20       *        The text label to display for the custom button.
21       */
22      public CustomImageButton(Context context, int resImage, String label) 
23       {
24           super(context);
25           this.label = label;
26           this.imageResId = resImage;
27           this.image = BitmapFactory.decodeResource(context.getResources(),
28                  imageResId);
29  
30           setFocusable(true);
31           setBackgroundColor(Color.WHITE);
32
33           setOnClickListener(listenerAdapter);
34           setClickable(true);
35       }
36

With the constructor defined, there are a number of methods in the View class that needs to be overridden to this view behave like a button. Firstly, the onFocusChanged gets triggered when the focus moves onto or off the view. In the case of our custom button, we want the button to be “highlighted” when ever the focus is on the button.

37       /**
38       * The method that is called when the focus is changed to or from this
39       * view.
40       */
41       protected void onFocusChanged(boolean gainFocus, int direction,
42                      Rect previouslyFocusedRect)
43       {
44           if (gainFocus == true)
45           {
46               this.setBackgroundColor(Color.rgb(255, 165, 0));
47           }
48           else
49          {
50              this.setBackgroundColor(Color.WHITE);
51          }
52      }
53      

The method responsible for rendering the contents of the view to the screen is the draw method. In this case, it handles placing the image and text label on to the custom view.

54      /**
55       * Method called on to render the view.
56       */
57      protected void onDraw(Canvas canvas)
58      {
59          Paint textPaint = new Paint();
60          textPaint.setColor(Color.BLACK);
61          canvas.drawBitmap(image, WIDTH_PADDING / 2, HEIGHT_PADDING / 2, null);
62          canvas.drawText(label, WIDTH_PADDING / 2, (HEIGHT_PADDING / 2) +
63                  image.getHeight() + 8, textPaint);
64      }
65      

For the elements to be displayed correctly on the screen, Android needs to know the how big the custom view is. This is done through overriding the onMeasure method. The measurement specification parameters represent dimension restrictions that are imposed by the parent view.

 66        @Override
 67        protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) 
 68        {
 69         setMeasuredDimension(measureWidth(widthMeasureSpec),
 70                 measureHeight(heightMeasureSpec));
 71        }
 72    

The call to setMeasuredDimension in the onMeasure method is important. The documentation states that the call is necessary to avoid a IllegalStateException.

 73     private int measureWidth(int measureSpec)
 74     {
 75         int preferred = image.getWidth() * 2;
 76         return getMeasurement(measureSpec, preferred);
 77     }
 78    
 79     private int measureHeight(int measureSpec)
 80     {
 81         int preferred = image.getHeight() * 2;
 82         return getMeasurement(measureSpec, preferred);
 83     }
 84    

To calculate the width and height measurements, I’ve chosen to keep the logic simple by using a simple formula to calculate the dimensions. This simple formula computes the dimensions based on the dimensions of the image. The measureSpec parameter specifies what restrictions are imposed by the parent layout.

 85     private int getMeasurement(int measureSpec, int preferred)
 86     {
 87         int specSize = MeasureSpec.getSize(measureSpec);
 88         int measurement = 0;
 89        
 90         switch(MeasureSpec.getMode(measureSpec))
 91         {
 92             case MeasureSpec.EXACTLY:
 93                 // This means the width of this view has been given.
 94                 measurement = specSize;
 95                 break;
 96             case MeasureSpec.AT_MOST:
 97                 // Take the minimum of the preferred size and what
 98                 // we were told to be.
 99                 measurement = Math.min(preferred, specSize);
100                 break;
101             default:
102                 measurement = preferred;
103                 break;
104         }
105    
106         return measurement;
107     }
108

To make the customised button useful, it needs to trigger some kind of action when it is clicked (i.e. a listener). The view class already defines methods for setting the listener, but a more specialised listener could be better suited to the custom button. For example, the specialised listener could pass back information on the instance of the custom button.

109     /**
110      * Sets the listener object that is triggered when the view is clicked.
111      *
112      * @param newListener
113      *        The instance of the listener to trigger.
114      */
115     public void setOnClickListener(ClickListener newListener)
116     {
117         listenerAdapter.setListener(newListener);
118     }
119    

If the custom listener passes information about this instance of the custom button, it may as well have accessors so listener implementation can get useful information about this custom button.

120     /**
121      * Returns the label of the button.
122      */
123     public String getLabel()
124     {
125         return label;
126     }
127    
128     /**
129      * Returns the resource id of the image.
130      */
131     public int getImageResId()
132     {
133         return imageResId;
134     }
135    

Finally, for our custom button class that is using a custom listener, the custom listener class needs to be defined.

136     /**
137      * Internal click listener class. Translates a view’s click listener to
138      * one that is more appropriate for the custom image button class.
139      *
140      * @author Kah
141      */
142     private class InternalListener implements View.OnClickListener
143     {
144         private ClickListener listener = null;
145    
146         /**
147          * Changes the listener to the given listener.
148          *
149          * @param newListener
150          *        The listener to change to.
151          */
152         public void setListener(ClickListener newListener)
153         {
154             listener = newListener;
155         }
156        
157         @Override
158         public void onClick(View v) 
159         {
160             if (listener != null)
161             {
162                 listener.onClick(CustomImageButton.this);
163             }
164         }
165     }
166    }
167    

25 Nov 2008, This tutorial has been superceded by Building a Menu for your Android (V1.0 R1) App.

19 Aug 2008, Note: Due to changes to the Android SDK, the code in this example does not work in 0.9 beta.

The menu builder class provides a way to build a simple menu, similar to the one below, in Android.

Menu built with the menu builder class.

To do anything useful with the menu, you need to specify what to do when an item is selected. A class that implements the MenuItem.OnClickListener interface is required to perform these actions. Here is an example of a listener that popups a dialog with the selection:

1   public class AndroidMenuButton extends Activity
2   {
3       private View menuInstance = null;
4  
5       private class ReactToClick
            implements Menu.OnClickListener
6       {
7           public ReactToClick()
8           {
9               // Empty constructor. Do nothing.
10          }
11          
12          /**
13           * React to an item being clicked.
14           */
15          public boolean onClick(Item item) 
16          {
17              // Display a that "echoes" the item that was
                // selected.
18              AlertDialog.Builder dialogBuilder = new 
19                  AlertDialog.Builder(AndroidMenuButton.this);
20              
21              dialogBuilder.setMessage(" You selected " +
22                      item.getTitle());
23              dialogBuilder.setCancelable(true);
24              dialogBuilder.create().show();
25  
26              // Click has been processed, so consume it.
27              return true;
28          }
29      }
30  

A layout can be setup to place the view on. For this example, I’ve set up a vertical linear view using XML and I grab the layout with the findViewById method:

31      /** 
32       * Called when the activity is first created. 
33       */
34      @Override
35      public void onCreate(Bundle icicle) 
36      {
37          super.onCreate(icicle);
38          setContentView(R.layout.capbutton);
39  
40          // Grab the view’s layout.
41          LinearLayout backView = (LinearLayout) 
42              findViewById(R.id.backgroundView);
43          

Next, create an instance of a MenuBuilder object and use the add method to place the menu items. Images for the menu items should be placed as a resource in res/drawables.

44          // Create the menu builder.
45          MenuBuilder builder = new MenuBuilder(this);
46          builder.setHeader("Menu Demo");
47          Item newItem = null;
48          ReactToClick action = new ReactToClick();
49          
50          // Tell the menu builder how to build the menu.
51          newItem = builder.add(0, 1, "Photos",
                R.drawable.item1);

The class, R, should be automatically be generated for you by the Android Eclipse plugin. R should contain references to all of your resources. The add method will return an Item object, to which you add your listeners to.

52          newItem.setClickListener(action);
53          newItem = builder.add(0, 2, "Painting",
                R.drawable.item2);
54          newItem.setClickListener(action);
55          newItem = builder.add(0, 3, "Science",
                R.drawable.item3);
56          newItem.setClickListener(action);
57          

Once all of the menu items have been added, the menu view can be constructed by the viewer and added to your own view.

58          // Get the menu instance and add it the view.
59          menuInstance = builder.getMenuView
60              (MenuBuilder.TYPE_ICON, backView, true);
61          menuInstance.setBackgroundColor(Color.WHITE);
62  
63          backView.addView(menuInstance);
64      }
65  }

It is also possible to have Android create the menu in different formats, such as the icon view (pictured in the first screenshot) or the context menu (pictured in the screenshot below).

Example of a context type menu.

The type of menu displayed is controlled by the first parameter to the MenuBuilder’s getMenuView method. The other two types of menus that have not been mentioned are the expanded menu and submenus. The MenuBuilder documentation details which constants the parameter needs to be set to in order to obtain the different types of menus (see the Constants section).