Addin Menus in Lotus Notes using MFC/NotesAPI






3.50/5 (5 votes)
Creating Add-in Menus in Lotus Notes using Lotus C APIs and MFC.
Introduction
This is a simple dll program that is used to add menus in Lotus Notes Action Menu using Lotus Notes C API 4.6.2.
Using the code
Menu Add-in funtions in NotesAPI allow you to customize the Notes Actions menu, so that users can run your API programs by selecting one of the menu items added. This will take you through a step by step procedure on how to create a Notes AddinMenu dll.
Step 1: Create New WorkspaceRun the VC New Projects wizard. Select MFC AppWizard(dll) and specify a project name as MenuAddin (for eg.). Cick on OK to proceed to the other dialogs and check the Regular Dll with MFC statically linked
option in the wizard.
Step 2: Workspace Settings
1. Go to Project Settings (ALT+F7). In the C/C++ tab in preprocessor definitions, add 'NT' or 'W32' at the end of the preprocessor list. 2. In the Link tab. In General, in Output file name, specify [NOTESPATH]\MenuAddin.dll
. [NOTESPATH]
is the path in which Notes executable resides your system. For eg. it would be Drive:\Lotus\Notes. 3. For Object/Library modules, enter notes.lib
in the field. 4. Go to Tools->Options Menu. In the Directories Tab, select Include files and specify the path of the Notes API Include Directory. For eg. in my case it was D:\Notes C API 4.6\INCLUDE
. 5. Select Library files and specify the path for the Lib files for your OS. For eg. in my case it was D:\Notes C API 4.6\LIB\MSWIN32
.
Step 3: Coding
Ok now we got the whole environment setup. Lets begin the coding part of it. There are 2 header files that need to be included for this dll to compile.
#include <global.h> #include <addinmen.h>
global.h
contains the global information and addinmen.h
contains the structures you need for creating a add-in menu dll. The Dll Class is now void of any entry point methods. NotesAddinMenu dlls must must have this as the entry point:
extern "C" NAMRESULT LNCALLBACK ActionsMenuProc(WORD wMsg, PVOID pParam)
wMsg
indicates an addin menu operation and pParam
will contain specific information, depending on the value of wMsg
.
There are 4 possible messages that are sent from the Notes Workstation to the DLL. These messages are defined in addinmen.h
. They are NAMM_INIT,NAMM_INITMENU,NAMM_COMMAND
and NAMM_TERM
. Complete reference on these message types will be available in the Notes API Reference. The Complete code for the ActionMenuProc will be as follows:
WORD gwStartingID; extern "C" NAMRESULT LNCALLBACK ActionsMenuProc(WORD wMsg, PVOID pParam) { // This function is called three times. // 1. to init/to get the menu item name. // 2. to enable/disable menu based on the context // like view,doc,workspace // 3. to do the actual command work. switch (wMsg) { case NAMM_INIT: // Set up the new addin menu items { NAM_INIT_INFO* pInitInfo; pInitInfo = (NAM_INIT_INFO *) pParam; // Save the starting ID of the First item appended to menu if (pInitInfo->wMenuItemNumber == 0) /* first time through */ gwStartingID = pInitInfo->wStartingID; // Give Notes our menu id pInitInfo->wMenuID = IDS_MENU_NAME; // Give Notes our menu item name CString strAppName; strAppName.LoadString(IDS_MENU_NAME); _tcscpy(pInitInfo->MenuItemName, (LPCSTR)strAppName); return (NAM_INIT_STOP); } case NAMM_INITMENU: // Called each time Action Menu is dropped down { NAM_INITMENU_INFO* pInitMenuInfo; WORD wFlags; pInitMenuInfo = (NAM_INITMENU_INFO *) pParam; wFlags = MF_ENABLED | MF_BYCOMMAND; // Set Menu Item State EnableMenuItem(pInitMenuInfo->hMenu, gwStartingID + IDS_MENU_NAME, wFlags); } return (NAM_NOERROR); case NAMM_COMMAND: // Called when user clicks the Menu Item { // do the actual command work here CString strAppName; strAppName.LoadString(IDS_APP_NAME); AfxMessageBox("Menu Item Clicked",IDS_APP_NAME,MB_OK); return (NAM_NOERROR); } case NAMM_TERM: default: return (NAM_NOERROR); } }
Description
Now this is not as complicated as it looks. Notes APIs provide with a lot of structures. I suggest you refer the Notes API Reference for more information on those structures. To start away with, theNAMM_INIT
tells the DLL that the Notes Client Actions menu needs to be initialized with the menu items defined in the menu add-in program. When this messgae is encountered, your program should initialize the menu using the NAMM_INIT_INFO
structure. NAM_INIT_INFO* pInitInfo; pInitInfo = (NAM_INIT_INFO *) pParam; // Save the starting ID of the First item appended to menu if (pInitInfo->wMenuItemNumber == 0) /* first time through */ gwStartingID = pInitInfo->wStartingID; // Give Notes our menu id pInitInfo->wMenuID = IDS_MENU_NAME; ..... _tcscpy(pInitInfo->MenuItemName, (LPCSTR)strAppName);
wStartingID
is the NotesID for the first add-in menu item. The program must save the starting ID the first time the message is processed. wMenuID
is a value that is assigned to each add-in menu. MenuItemName
is the string to displayed in the menu as the menu option name.
Each time the Action Menu item is selected in Lotus Notes, the message NAMM_INITMENU
is sent to the DLL. This is where we enable, disable, check or gray the add-in menu items. This is done through the NAM_INITMENU_INFO
structure.
NAM_INITMENU_INFO* pInitMenuInfo;
WORD wFlags;
pInitMenuInfo = (NAM_INITMENU_INFO *) pParam;
wFlags = MF_ENABLED | MF_BYCOMMAND;
// Set Menu Item State
EnableMenuItem(pInitMenuInfo->hMenu, gwStartingID
+ IDS_MENU_NAME, wFlags);
When a user selects a add-in menu item from the Actions menu, the NAMM_COMMAND
is sent to the DLL for processing. The DLL populates the NAM_COMMAND_INFO
structure. From the structure, you can proceed with calling functions and other API programs that are appropriate to the menu item selected. For this example I have not populated the NAM_COMMAND_INFO
structure because we are creating only one add-in menu. In cases where we are adding more than one add-in menu, the structure values can be used to determine which one of the add-in menus was invoked.
After all the processing is done in NAMM_COMMAND
it should always return NAM_NOERROR
.
Configuring Notes
You have to be sure to declare theAddinMenuProc
and assign it the ordinal value of 1 in the EXPORTS section of the .def
file. Now compile the program into a dll. After this is done you have the follow the following steps to configure Notes to load the DLL when Notes is launched.
DriveLetter:/Lotus/Notes
.
NOTES.INI
file. The format is: AddinMenus = [<drive>]:[<directory>\<addname1.dll>, [<drive>]:[<directory>\<addname2.dll> ...If the Dll is placed inside the Notes folder, you needn't specify the path. In our case it would be,
AddinMenus = MenuAddin.dllIf there is more than one dll you could use
commas
to separate them.