Context Menu Services

Availability  LightWave® 7.0
Component  Layout, Modeler
Header  lwpanel.h

Context menu services are a set of functions for creating and displaying context menus over your panels. A context menu is a modal popup window containing a list of options. You typically display one of these when the user right-clicks or shift-clicks an item in your panel.

Global Call

   ContextMenuFuncs *cmenuf;
   cmenuf = global( LWCONTEXTMENU_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to a ContextMenuFuncs.

   typedef struct st_ContextMenuFuncs {
      LWContextMenuID (*cmenuCreate) (LWPanPopupDesc, void *userdata);
      int             (*cmenuDeploy) (LWContextMenuID, LWPanelID,
                                        int item);
      void            (*cmenuDestroy)(LWContextMenuID);
   } ContextMenuFuncs;

menu = cmenuCreate( popdesc, userdata )

Create a context menu. The popdesc structure, described below, contains your menu parameters and callbacks. The userdata is a pointer that you want your callbacks to receive.

selection = cmenuDeploy( menu, panel, item )

Display the context menu, typically in response to some user action. A context menu is always displayed in association with a particular panel. The item is the 0-based index of the menu item that should be selected when the menu is first displayed, and the return value is the index of the item selected by the user. Either of these can be -1 to indicate no selection.

cmenuDestroy( menu )

Free the menu and related resources allocated by cmenuCreate.

Popup Descriptor

The cmenuCreate function uses an LWPanPopupDesc structure to define the menu. This is the same structure used by Panels custom popup controls, but for that purpose, its details are conveniently hidden from you by the CUSTPOPUP_CTL macro.

   typedef struct st_LWPanPopupDesc {
      LWType  type;
      int     width;
      int    (*countFn)(void *userdata);
      char * (*nameFn) (void *userdata, int item);
   } LWPanPopupDesc;

type

Set this to LWT_POPUP.

width

The width of the menu in pixels.

nitems = countFn( userdata )

Your count callback, which returns the number of items in the menu. The userdata is whatever you passed as the second argument to cmenuCreate.

itemstring = nameFn( userdata, item )

Your item name callback, which returns the string that should be displayed for the item.

Example

The following code fragments create and display a simple context menu. First, we'll create a data structure for our menu and define the callbacks.

   typedef struct st_MyMenuData {
      int    count;
      char **name;
   } MyMenuData;

   static char *itemname[] = {
      "New", "Load", "Save", "Copy", "Paste", NULL };

   MyMenuData menudata = { 5, itemname };

   int menuCount( MyMenuData *data )
   {
      return data->count;
   }

   int menuName( MyMenuData *data, int index )
   {
      if ( index >= 0 && index < data->count )
         return data->name[ index ];
      return NULL;
   }

Don't forget to initialize the global.

   #include <lwpanel.h>
   
   ContextMenuFuncs *cmenuf;

   cmenuf = global( LWCONTEXTMENU_GLOBAL, GFUSE_TRANSIENT );
   if ( !cmenuf ) return AFUNC_BADGLOBAL;

Create the menu. Typically you'll do this when you're creating the associated panel and its controls.

   LWContextMenuID menu;
   LWPanPopupDesc desc;

   desc.type    = LWT_POPUP;
   desc.width   = 200;
   desc.countFn = menuCount;
   desc.nameFn  = menuName;
   
   menu = cmenuf->cmenuCreate( &desc, menudata );
   if ( !menu ) goto MenuFail;

Display the context menu in response to some user action.

   int select, current;

   select = cmenuf->cmenuDeploy( menu, panel, current );
   if ( select != -1 ) {
      current = select;
      ...

When you're done with it, free the menu.

   cmenuf->cmenuDestroy( menu );