PROGRAM(MenuFactory);
FUNCTION(set_menubar_modify_callback, "function(function:void)");
NAME_ARGS(callback);
// The function passed as the argument to this function will be called
// each time the accelerator key mapping is changed by the user with
// the new mapping as the argument.<p>
//  <b>NOTE</b>: This function is only used when the menubar
//  is created, once you are done with the menubar creation, the
//  callbacks for that menubar will be fixed.

FUNCTION(get_menubar_mapping, "function(void:mapping)");
//  Returns a (flat) mapping ([ path:GTK.MenuItem ]).<p>
// <b>NOTE:</b> This function can only be called <i>after</i> the menubar is created.

FUNCTION(MenyFactory, "function(array,MenuDef ...:void)");
NAME_ARGS(items);
// Returns ({ GTK.MenuBar, GTK.AcceleratorTable })
// <p>
// This is the function that actually builds the menubar.
// A short example:
//<p><pre>
// import GTK.MenuFactory;
// [GTK.MenuBar bar, GTK.AcceleratorTable map] = 
//  MenuFactory( 
//    MenuDef( "File/New", new_file, 0, "A-N" ), 
//    MenuDef( "File/Open", new_file, 1, "A-O" ), 
//    MenuDef( "File/Save", save_file, 0, "A-S" ), 
//    MenuDef( "File/<separator>", 0, 0 ),
//    MenuDef( "File/Quit", _exit, 0, "A-Q" ), 
//  );
//</pre>

// A single menu entry.
FUNCTION(MenuDef, "function(string,function|void,mixed|void,string|void,int|void)");
NAME_ARGS(path,callback,callbackargument,shortcut,flags);
RETURNS(MenuDef);
// Path is the menupath. A submenu will be created for each
// "Directory" in the path, and menuitems will be created for the
// "files". There are two special cases: The "file" '<separator>' will
// create a thin line. The "file"prefix <check> will make the menuitem
// a checkmenuitem instead of a normal menuitem.
//<p>

// The second and third arguments are the callback function and the
// first callback function argument. If the callback function argument
// is an array, the indices of the array will be pushed as
// arguments. To call the function with an array as the only argument,
// make an array with the array in.  The callback function will be
// called like callback( arg, widget ), or if arg is an array,
// callback( arg[0], arg[1], ..., widget )
//<p>
// The fourth argument, shortcut, is the shortcut to bind to this menu
// item. The shortcut can be changed later on by calling
// assign_shortcut, or by the user by pressing the desired
// keycombination over the menu item.
// <p>The shortcut syntax is:
// m[m[..]]-key, where m is one or more modifier character, and key is
// the desired key (<b>NOTE</b>: Key must be in the range 0-255
// currently, this will hopefully be fixed by the GTK people in the
// future)
// <p>
// The modifiers are:<p><pre>
// s: Shift
// c: Control
// a: Modifier 1 (called alt by the GTK people, that's not true, though)
// 1: Modifier 1
// g: Modifier 2 (called altgr by the GTK people, that's not true, though)
// 2: Modifier 2
// m: Modifier 3 (not mapped by the GTK people, meta on _my_ keyboard)
// 3: Modifier 3
// h: Modifier 4 (not mapped by the GTK people, hyper on _my_ keyboard)
// 4: Modifier 4
// u: Modifier 5 (not mapped by the GTK people, super on _my_ keyboard)
// 5: Modifier 5
// </pre>
// <p>
// The last argument (flags) is currently ignored.

FUNCTION(MenuDef->assign_shortcut, new_shortcut);
NAME_ARGS(new_shortcut);
// Set a new shortcut as the current one.
// 
// <p>
// The shortcut syntax is:
// m[m[..]]-key, where m is one or more modifier character, and key is
// the desired key (<b>NOTE</b>: Key must be in the range 0-255
// currently, this will hopefully be fixed by the GTK people in the
// future)
// <p>
// The modifiers are:<p><pre>
// s: Shift
// c: Control
// a: Modifier 1 (called alt by the GTK people, that's not true, though)
// 1: Modifier 1
// g: Modifier 2 (called altgr by the GTK people, that's not true, though)
// 2: Modifier 2
// m: Modifier 3 (not mapped by the GTK people, meta on _my_ keyboard)
// 3: Modifier 3
// h: Modifier 4 (not mapped by the GTK people, hyper on _my_ keyboard)
// 4: Modifier 4
// u: Modifier 5 (not mapped by the GTK people, super on _my_ keyboard)
// 5: Modifier 5
// </pre>
