Skip to content

Menu Add In Programs

Chapter 12-4

Introduction

You can add items to the Notes workstation Actions menu and configure Notes to call your API program each time the user selects one of these menu items. The API program must be a Windows DLL that provides a menu add-in function. Install your DLL on the Notes workstation and configure Notes to load your DLL when the user starts running the workstation. Notes sends messages to your menu add-in function so that your function can initialize the Actions menu, enable or disable menu items, and respond when the user selects your menu item.

You must specify the name of your menu add-in DLL in the AddInMenus variable in the notes.ini file that configures the Notes workstation. To list multiple add-in DLL names, separate the names with a comma. For example, to add the DLLs uiaddin1.dll and uiaddin2.dll to the Notes workstation, add the following line to notes.ini:

      AddInMenus = UIADDIN1.DLL, UIADDIN2.DLL


In this example, the add-in DLLs must reside in a directory in the path. Alternatively, you can specify the full pathname of the DLLs in the notes.ini file.

The name of the add-in DLL may begin with the platform specifier character used in the names of other Notes API add-in programs: n under Windows 32-bit. If the DLL name contains a platform specifier character, you may omit the character when specifying the name in the AddInMenus variable in the notes.ini file.


Technical Description

An add-in DLL must have the following entry point:

      NAMRESULT LNCALLBACK AddinMenuProc (WORD wMsg, void far *pParam);

    wMsg is one of the following User Menu messages:

        NAMM_INIT
        NAMM_INITMENU
        NAMM_COMMAND
        NAMM_TERM

        pParam is message-specific data.

        The entry point can have any legal function name. You must declare the function in the EXPORTS section of the add-in's module definition (.def) file and assign it an ordinal value of 1.

        The add-in module must include addinmen.h.


        NAMM_INIT

        This message gives the DLL the opportunity to add one or more menu items to the Notes Actions menu. For each menu item, the DLL assigns the wMenuID and MenuItemName fields of the structure below. The DLL may assign a mnemonic to each added menu item by placing an ampersand (&) next to the desired character in the MenuItemName field of this structure. This causes the character following the ampersand to be underlined in the Actions menu and allows the user to select the menu item with this key.

        When the NAMM_INIT message is passed to AddinMenuProc, pParam is a pointer to a NAM_INIT_INFO structure.


            typedef struct
            {
            WORD wStartingID;     /* Input: DLL must add this to its
                                           menu item ID when specifying the
                                           menu id to another module. */
            WORD wMenuItemNumber; /* Input: Ascending ordinal number
                                           for each call. */
            WORD wMenuID;          /* Output: DLL's Menu ID. */
            char MenuItemName[MAX_ADDIN_MENU_NAME]; /* Output: Text of
                                                              menu item in LMBCS. */
            } NAM_INIT_INFO;

        When the NAMM_INIT message is passed, AddinMenuProc returns one of the following values:

            NAM_INIT_CONTINUE Requests Notes to send NAM_INIT again so that the DLL can add another menu item.
            NAM_INIT_STOP Tells Notes that this DLL has no more menu items to add.

        NAMM_INITMENU

        This message gives the DLL a chance to modify the attributes of its menu items (for example, enable, disable, gray, or check them).

        When the NAMM_INITMENU message is passed to AddinMenuProc, pParam is a pointer to a NAM_INITMENU structure.


            typedef struct
            {
            HMENU hMenu; /* Handle of the Actions popup menu. */
            NAM_CONTEXT_DATA Data; /* Context specific data */
            } NAM_INITMENU_INFO;

        When the NAMM_INITMENU message is passed, AddinMenuProc always returns NAM_NOERROR.


        NAMM_COMMAND

        This message is sent to the DLL when the user has selected one of its menu items.

        When the NAMM_COMMAND message is passed to AddinMenuProc, pParam is a pointer to a NAM_COMMAND_INFO structure.


            typedef struct
            {
            HWND hNotesWnd;         /* Handle of Notes main window
              to use as parent. */
            /* Also for use when sending
                                             messages to Notes. */
            WORD wMenuID;           /* DLL's ID number of selected
                                             menu item. */
            NAM_CONTEXT_DATA Data;  /* Context specific data */
            } NAM_COMMAND_INFO;

        When the NAMM_COMMAND message is passed, AddinMenuProc always returns NAM_NOERROR.

          While processing the NAMM_COMMAND message, the DLL can send back to Notes messages requesting Notes to take a particular action. The available messages are:


              WM_ADDIN_REFRESH
              WM_ADDIN_IMPORT


          For example, to send WM_ADDIN_IMPORT back to Notes:

            NAM_COMMAND_INFO *pCmdInfo = (NAM_COMMAND_INFO *)pParam;


              SendMessage(pCmdInfo->hNotesWnd, WM_ADDIN_IMPORT, 0, (LONG)pInfo);
                            


          These messages are described later under "WM_ADDIN Messages."


          NAMM_TERM

          This message gives the DLL a chance to free any storage that it allocated before Notes frees it.

          When NAMM_TERM is passed to AddinMenuProc, pParam is unused, and AddinMenuProc always returns NAM_NOERROR.


          Structures


              typedef struct
              {
              EDITIMPORTDATA Import;   /* defined in ixedit.h */
              EDITEXPORTDATA Export;   /* defined in ixedit.h */
                    char CaretFieldName[34]; /* field name of
                                                current cursor position */
                    WORD CaretFieldType;     /* field type of current cursor
                                                position */
              } EDITIXDATA;

              typedef struct
              {
              FLAG Context:3;     /* Notes context:  Desk, View,
                                           Editor R/W, Editor R/O */
              FLAG fCanExport:1;  /* TRUE if the add-in can perform
                                           an export. */
              FLAG fCanImport:1;  /* TRUE if the add-in can request an
                                           import. */
              union
              {
              EDITIXDATA Edit;
              VIEWIXDATA View;   /* defined in ixview.h */
              } IXData;
              } NAM_CONTEXT_DATA;

          These structures provide import/export data to the add-in DLLs. The Context member of NAM_CONTEXT_DATA indicates the Notes context when the menu item was selected. It has one of the following values:

          NAM_IN_DESK In the desktop
          NAM_IN_VIEW In a view
          NAM_IN_VIEW_DESIGN Designing a view
          NAM_IN_EDIT_RO In a read-only document
          NAM_IN_EDIT_RW In a document - edit mode
          NAM_IN_EDIT_DESIGN Designing a document

          The CaretFieldName member of the EDITIXDATA structure gives the name of the field containing the cursor when the menu item was chosen. The CaretFieldType member of the EDITIXDATA structure gives the type of the field containing the cursor when the menu item was chosen. It has one of the following values:

          FIELD_TYPE_ERROR Field type could not be determined
          FIELD_TYPE_NUMBER Number field
          FIELD_TYPE_TIME Time field
          FIELD_TYPE_RICH_TEXT Rich text field.
          FIELD_TYPE_AUTHORS Authors field
          FIELD_TYPE_READERS Readers field.
          FIELD_TYPE_NAMES Names field
          FIELD_TYPE_KEYWORDS Keyword field
          FIELD_TYPE_TEXT Plain text field.
          FIELD_TYPE_SECTION Section field


          WM_ADDIN Messages

          Add-in menu DLLs can request the Notes workstation to perform certain actions while processing one of their menu commands. In all cases, the wParam of the message is unused and the lParam is set to point to the NAM_COMMAND_INFO structure that was passed to the DLL when the user selected the menu item. Also, in all cases, the return value from the message is a STATUS code.

              WM_ADDIN_REFRESH Tells Notes to refresh the current view.
              WM_ADDIN_IMPORT Tells Notes to import to the editor the CD scratch file specified in the context block.



          Known Limitations and Usage Restrictions

          Menu add-in programs are only supported on Windows 32-bit Notes clients.

          The add-in DLL cannot add popup menus to the Notes Actions menu. It can only add menu items.