ROVLib Tutorial - Adding a menu

© Jason Tribbeck 2002

Adding a menu

In this tutorial, we will be adding a menu to the icon on the icon bar that will enable us to quit when it is chosen.

The source code

/**
 * Menu.c - Adding a menu
 */

/* Include 4 standard C header files */
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <ctype.h>

/* Include the RISC OS kernel header file */
#include "kernel.h"

/* Include the ROVLib header files */
#include "main.h"
#include "canvas.h"
#include "menu.h"
#include "baricon.h"
#include "extras.h"

/* Prototype the click function */
void click(int icn);

/* Prototype the menu event handler */
void choose(menu m, int item);

/* Prototype the menu click event handler */
void menu_click(canvas c);

/* A variable to hold the canvas */
static canvas c;

/* A variable to hold the menu */
static menu iconm;

int main(int argc, char **argv) {
  /* Initialise the ROVLib system */
  main_init("Menu test");

  /* Initialise the ROVLib canvas core */
  canvas_init();

  /* Initialise the ROVLib menu core */
  menu_init();

  /* Create the canvas */
  c = canvas_create(640, 480, "An example canvas");

  /* Make the canvas as a window */
  canvas_make(c);

  /* Create an icon on the icon bar */
  baricon("file_ff8", click);

  /* Register a menu handler on the icon bar */
  canvas_addhandler(CANVAS_ICONBAR, CANVAS_MENUHANDLER, menu_click);

  /* Create the menu */
  iconm = menu_create("Menu test", 1, choose, NULL);

  /* Add the 'quit' menu item */
  menu_add(iconm, "Quit");

  /* Open the canvas in the centre of the screen */
  canvas_opencentre(c);

  /* Poll forever (or at least until told to quit!) */
  main_poll();
}

/* Actually perform the click function */
void click(int icn) {
  canvas_reopen(c);
}

/* Handle the menu click event */
void menu_click(canvas c) {
  menu_displayiconbar(iconm);
}

/* Handle the menu choice */
void choose(menu m, int item) {
  switch(item) {
    case 0 :
      exit(0);
      break;
  }
}

Menu click event handling

Menu click events are treated differently to normal mouse clicks, as they perform a fundamentally different operation. So, to know about menu clicks, you need to add a menu click event handler to the canvas that you wish to handle menu clicks. This is different from other RISC OS libraries in that you would normally have to decode the click event in order to find out if the MENU button was clicked. In this code, we are interested in the icon bar, so we register the menu click event handler called "menu_click" to CANVAS_ICONBAR.

The menu is created by passing the title of the menu, the number of items in the menu, the menu choose event handler for this menu, and the sub-menu choose event handler for this menu (which we don't have, so we pass NULL).

The menu then has an item labelled "Quit" added to it. Note that this is the only menu item.

Now we have a new method of quitting the application, we have removed the canvas close event handler, and allowed ROVLib to handle closes for us.

The menu click event handler displays the menu at the correct position for an icon bar menu, by calling menu_displayiconbar. ROVLib calculates the height of the menu, and then opens it at the correct position.

If the user selects a menu option, then the menu event handler choose is called, with the menu item as its second parameter. We encase this within a switch block, as we will be extending it later. In addition, if the user does not select an item (by clicking in the menu, but just outside the menu items), then you get the menu item -1 passed in. As we've only got one item, we exit if item 0 is chosen.

Running the application.

Running the !Menu Obey file will open the canvas on the screen, as well as display the icon on the icon bar. This looks remarkably like what we had before.

Now, however, if you press MENU on the icon, you will get the following menu:

If you choose "Quit", then the application will be killed.

You can close the canvas by clicking on the canvas' close icon, and reopen it by clicking SELECT on the icon.

This is looking more like a proper application!

Epilogue

You will have seen how to create a simple menu, display it, and act on user choices. Although it is not very exciting, it will become expanded in the next tutorial.