====== menu_InsertItem2 ======

===== Description =====

Add an item to the menu in L3DT. 

===== Function prototype =====

<code>bool CExtAPI::menu_InsertItem2(const char* lpFnName, const char* lpOptionName, unsigned long MenuContext, unsigned long Flags);</code>


===== Arguments =====

^  Name  ^  Type  ^ Comment ^
|  //lpFnName//  |  const char*  | A pointer to a C-style string containing the name of the ZeoFunc to be activated by this menu option.  |
|  //lpOptionName//  |  const char*  | A pointer to a C-style string containing the display name of the menu option.  |
|  //MenuContext//  |  unsigned long  | An enumerated integer to indicate into which menu the item should be inserted. See comments for supported values. |
|  //Flags//  |  unsigned long  | Reserved. Must be 0. |

===== Return value =====

False if an error occurred, and true otherwise. 

===== Comments =====

==== Use with zeofunc_LoadFunc ====

The //lpFnName// argument must be the name of a function loaded from your plugin via the  [[zeolite:functions:zeofunc_LoadFunc]] method. See the example provided below.

==== Menu contents ====

By default, this function adds the menu item into the '//Extensions->[your plugin name]//' menu in L3DT. However, using the //MenuContext// argument, you may insert your item into other menus. The following values are recognised:

^ Defined constant ^  Value  ^ Menu ^
| ZMENU_CONTEXT_EXT_CUR |  0  | //Extensions->[extension name]// |
| ZMENU_CONTEXT_EXT_ROOT |  1  | //Extensions// |
| ZMENU_CONTEXT_FILE_IMPORT |  2  | //File->Import// |
| ZMENU_CONTEXT_FILE_EXPORT |  3  | //File->Export// |

==== Sub-menus ====

The '.' (dot) character is used to delimit nested submenus. Thus, if you provide an //lpOptionName// of "mysubmenu.myoption", your option will appear at '//Extensions->[your plugin name]->mysubmenu->myoption//' (assuming the default //MenuContext//). Unfortunately, this means you cannot use dots for abbreviations or ellipsis (e.g. 'about...')

===== Example =====

This is from the InitPlugin function of [[bundywiki>plugins:file:L3DTio_TorqueTER|L3DTio_TorqueTER]]:

<code>
// load the extension function
theAPI.zeofunc_LoadFuncEx("L3DTio_TorqueTER.T3D.MaterialManagerUI", "ExtT3DMtlManagerUI", VarID_void, NULL);

// load the menu item for the function
theAPI.menu_InsertItem2("T3D.MaterialManagerUI", "Torque T3D.Material Manager", ZMENU_CONTEXT_FILE_EXPORT, 0);
</code>