EPLAN.EPLAN21.ADDIN.REGISTER

Contents

Description

This command allows an add-in to generate menu items in EPLAN 21 and to register functions relating to these menu items. Each add-in can register any number of menu items.

The registration of menu items is normally carried out within the EplanIntialize() function of the add-in.

As callback for the generated menu items, commands are used. For this reason, the add-in must first register a new command (API function eplRegisterCommandHandler) and announce this command as callback to the EPLAN.EPLAN21.ADDIN.REGISTER command. The registered command is executed whenever the associated menu item is activated. The handle of the parent window is handed to the command via the EPL_PARAM_COMMAND_PARENTWINDOW parameter setting.

Parameters

All parameter settings have the prefix "EPL_PARAM_ADDIN_REGISTER_".

ParameterID Type Description
MENUNAME [IN, INDEX]
String
Designation of menu item.
MENUHANDLER [IN, INDEX]
String
Name of command to be called up as menu handler. During each call-up, this command is handed two additional parameters:
  • EPL_PARAM_COMMAND_PARENTWINDOW receives the HWND of the calling-up window.
  • EPL_PARAM_COMMAND_INDEX receives the index of the menu item. During registration, this index is used by several menu items for the eplSetParam call-ups.
An add-in can register the MENUHANDLER command via the eplRegisterMenuHandler function.
MENUDESCR [IN, INDEX, OPTIONAL]
STRING
Designation of menu item. The description is displayed in the status bar of the respective window. If no description is indicated, the ...MENUNAME parameter is used.
PARENTMENU [IN, INDEX, OPTIONAL]
Integer
Menu into which the menu item is to be integrated. At the moment, the following values are possible:
  • EPL_MENUTYPE_MAIN (Not available in EPLAN 21 EED)
  • EPL_MENUTYPE_BROWSER
  • EPL_MENUTYPE_GED
  • EPL_MENUTYPE_MACROGED
  • EPL_MENUTYPE_SYMBOLGED
  • EPL_MENUTYPE_FRAMEGED
  • EPL_MENUTYPE_FORMGED
PARENTITEM [IN, INDEX, OPTIONAL]
Integer
ID of the menu item to which the current entry is appended. Using this parameter, a certain menu position can be determined instead of the default positions of the respective dialog if its MenuID is known.
ITEM_TYPE [IN, INDEX, OPTIONAL]
Integer
For creating a separator or a pop-up menu, the ITEM_TYPE can be set. EPL_MENUITEMTYPE_SEPARATOR or EPL_MENUITEMTYPE_POPUP are possible values.
ITEM_PREPEND [IN, INDEX, OPTIONAL]
Integer
If this flag is set to "1," the menu item is not appended but put in front of the menu item as set in PARENTITEM.
MENUID [IN, INDEX, OPTIONAL]
Integer
ID of menu item. This ID must be unique. Normally it is not necessary to indicate the MenuID and it should be avoided unless it is known which IDs are available.

Error Messages

The eplExecuteCommand function returns EPL_OK if the function sets were correctly registered.

Example

The following example shows an add-in which registers its own command and uses it as callback for a menu item that is integrated into the graphical editor.

Via "EPLAN.EPLAN21.SELECTION," the menu callback queries the current selection and determines the number and the type of the selected objects.

/* Callback for the registered command "TEST.COMMAND1" which is used as the callback
 * for the menu item "TESTMENU1" in the GED
 */
extern "C" DLL_EXPORT
void __stdcall
testCommandHandler(EplSession s, const EplChar* commandName, EplHandle param)
{
        wchar_t buf[256];

        // Get the HWND of the parent window:
        eplGetParam(s, param, EPL_PARAM_COMMAND_PARENTWINDOW, 0, buf, 255);
        HWND parentWindow = (HWND) wcstol(buf, NULL, 10);

	EplHandle hSel(EPL_ERROR);

        // Ask for the current selection:
        EplHandle c = eplCreateCommand(s, L"EPLAN.EPLAN21.SELECTION");
        if(c == EPL_ERROR)
                return;

        eplExecuteCommand(s, c);

        // Selection iterator:
        hSel = eplGetHandleParam(s, c, EPL_PARAM_SELECTION_RESULT, 0);
	
        if(eplCount(s, hSel) > 0)
        {
                // Get the first selected object:
                EplHandle role = eplFirst(s, roleIter);

                // Get the object type:
                int type = eplGetType(s, o);

                // Print a message:
                std::wstring s;
                switch(type)
                {
                case EPL_OBJECTTYPE_PAGE:
                        s = L"Pages: ";
                        s.append(buf);
                        MessageBoxW(parentWindow, s.c_str(), L"TESTMENU1", MB_OK | MB_ICONEXCLAMATION);
                        break;
                case EPL_OBJECTTYPE_INSTANCE:
                        s = L"Instances: ";
                        s.append(buf);
                        MessageBoxW(parentWindow, s.c_str(), L"TESTMENU1", MB_OK | MB_ICONEXCLAMATION);
                        break;
                default:
                        MessageBox(parentWindow, "no page, no instance...", "TESTMENU1", MB_OK | MB_ICONEXCLAMATION);
                        break;
                }
        }
}

extern "C" DLL_EXPORT
int EplanInitialize(void)
{
        EplSession s = eplCreateSession();

        /* Register a new Command under the name "TEST.COMMAND1". The command
           is implemented by the function "testCommandHandler". This function
           is called in the following example:
                   EplHandle testCommand = eplCreateCommand(s, L"TEST.COMMAND1");
                   eplExecuteCommand(s, testCommand);
         */
        eplRegisterCommandHandler(s, L"TEST.COMMAND1", testCommandHandler);

        // Append one menu item to the GED:
        EplHandle c = eplCreateCommand(s, L"EPLAN.EPLAN21.ADDIN.REGISTER");
        if(c != EPL_ERROR)
        {
                // Menu name:
                eplSetParam(s, c, EPL_PARAM_ADDIN_REGISTER_MENUNAME, L"TESTMENU1", 1);

                /* Use the "TEST.COMMAND1" As the callback for the menu item. Every time
                   when the user selects this new menu item, the command is executed.
                 */
                eplSetParam(s, c, EPL_PARAM_ADDIN_REGISTER_MENUHANDLER, L"TEST.COMMAND1", 1);
                wchar_t buf[20];
                _ltow(EPL_MENUTYPE_GED, buf, 10);
                eplSetParam(s, c, EPL_PARAM_ADDIN_REGISTER_PARENTMENU, buf, 1);

                eplExecuteCommand(s, c);
                eplCloseObject(s, c);
        }

        eplDestroySession(s);
        return 0;
}

Reference