DLL Interface

Introduction

The Proton IDE has been designed with flexibility in mind. Plugins enable the functionality of the IDE to be extended by through additional third party software, which can be integrated into the development environment. The plugin architecture has been designed to make writing third party plugins very easy using the development environment of your choice. Examples include Visual BASIC, C++ or Borland Delphi. All you need to do is write some code to interface with the plugin manager DLL.

Please note that you cannot implement or execute plugins unless version 1.0.3.0 or higher of the Proton IDE is installed on the target system. To install the latest version of the IDE, select VIEW...ONLINE UPDATES from the IDE main menu. If you are currently using a version of the IDE that is prior to 1.0.3.0, you will need to run the online update utility twice to ensure that mcPluginMgr.dll is installed correctly on your machine.

Creating a Plugin

This first thing you need to do is read the interface reference guide in this help file. A code template also provides a good starting point for implementing your plugin. To install the plugin into the IDE, use the Plugin Editor software.

Know Issues

A number of operating system API calls are used to support the plugin architecture. Microsoft have identified a number of problems with these calls that impact on the operation of the plugin system for some operating systems. These are:

  • Error Lock Violation. Microsoft has confirmed that this is a problem in Windows 2000. This problem was first corrected in Windows 2000 Service Pack 2. This article was published under Q266749. More information can be found here.
  • A program may experience memory leaks when running on Windows 98 or Windows 98 Second Edition. This article was published under Q242161. More information can be found here.


Contact Information

Mecanique
85 Marine Parade
Saltburn by the Sea
TS12 1BZ
United Kingdom

Tel | from the UK | 01287 622382
 | outside the UK | +44 1287 622382
FAX | from the UK | 08700 520279
 | outside the UK | +44 8700 520279
email |  | enquiries@mecanique.co.uk


Connect

BOOL Connect(HWND pHostWin)

Overview

Connect to the IDE plugin interface.

Parameters

  • pHostWin - The window handle of the client application. If the value is NULL, the client application will be unable to receive notification messages from the IDE plugin manager.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also

IsConnected


Disconnect

BOOL Disconnect

Overview

Disconnect from the IDE plugin manager. There is no need to explicitly call this function during a session, as a connection is automatically terminated when the client application shuts down. However, you can call this function if you wish to terminate the connection before the client application is closed.

Parameters

None

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also


IsConnected

BOOL IsConnected

Overview

Determines if a connection to the IDE plugin manager has been made.

Parameters

None

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also

Connect


GetPathCompiler

void GetPathCompiler(LPSTR pPath, UINT pLen)

Overview

Gets the fully qualified compiler path currently being used by the IDE.

Parameters

  • pPath - Pointer to a buffer into which the function is to copy the compiler path.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pPath parameter.

Return Value

None

See Also


GetPathIDE

void GetPathIDE(LPSTR pPath, UINT pLen)

Overview

Gets the fully qualified IDE path.

Parameters

  • pPath - Pointer to a buffer into which the function is to copy the IDE path.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pPath parameter.

Return Value

None

See Also


GetPathPlugin

void GetPathPlugin(LPSTR pPath, UINT pLen)

Overview

Gets the fully qualified plugin path currently being used by the IDE.

Parameters

  • pPath - Pointer to a buffer into which the function is to copy the plugin path.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pPath parameter.

Return Value

None

See Also


GetPage

void GetPage(LPSTR pFilename, UINT pLen)

Overview

Gets the filename, including path, of the page currently selected in the IDE.

Parameters

  • pFilename - Pointer to a buffer into which the function is to copy the page filename.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pFilename parameter.

Return Value

None

See Also

GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageInfo

BOOL GetPageInfo(LPSTR pFilename, LPPAGEINFO pInfo)

Overview

Gets page information.

Parameters

  • pFilename - Pointer to a null terminated page filename string. The filename string must point to a page currently open in the IDE.
  • pInfo - Points to a PAGEINFO structure that receives information about the page selected by the pFilename parameter.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also

GetPage
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageByIndex

BOOL GetPageByIndex(UINT pIndex, LPSTR pFilename, UINT pLen)

Overview

Gets the filename of a page, including path, by its index value. The number of pages available can be obtained with a call to GetPageCount.

Parameters

  • pIndex - The page index, which ranges from 0 to GetPageCount - 1.
  • pFilename - Pointer to a buffer into which the function is to copy the page filename.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pFilename parameter.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also

GetPage
GetPageInfo
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageCount

UINT GetPageCount

Overview

Gets the number of pages currently open in the IDE. Used in conjunction will GetPageByIndex.

Parameters

None

Return Value

Number of pages currently open in the IDE.

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageIncludeByIndex

BOOL GetPageByIncludeIndex(LPSTR pFilename, UINT pIndex, LPSTR pInclude, UINT pLen)

Overview

Gets the include filename of a page, including path, by its index value. The number of include files can be obtained with a call to GetPageIncludeCount. You can use this function to obtain all project include files.

Parameters

  • pFilename - Pointer to a null terminated page filename string. The filename string must point to a page currently open in the IDE or an include file which has been found in a previous call to GetPageIncludeByIndex.
  • pIndex - The include file index, which ranges from 0 to GetPageIncludeCount - 1.
  • pInclude - Pointer to a buffer into which the function is to copy the page include filename.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pInclude parameter.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageIncludeCount

UINT GetPageIncludeCount(LPSTR pFilename)

Overview

Gets the number of include files contained in page.

Parameters

  • pFilename - Pointer to a null terminated filename string. The filename string must point to a page currently open in the IDE or an include file which has been found in a previous call to GetPageIncludeByIndex.

Return Value

Number of include files.

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageText

void GetPageText(LPSTR pText, UINT pLen)

Overview

Gets all text contained in the currently selected page. You can allocate your text string statically, or you can use a dynamic string to buffer the text data. For dynamic allocation, use a call to GetPageInfo to obtain the size of the page.

Parameters

  • pText - Pointer to a buffer into which the function is to copy the text.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pText parameter.

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageTextRTF

void GetPageTextRTF(LPSTR pText, UINT pLen)

Overview

Gets all text contained in the currently selected page in RTF format. You can allocate your text string statically, or you can use a dynamic string to buffer the text data. For dynamic allocation, use a call to GetPageInfo to obtain the size of the RTF page.

Parameters

  • pText - Pointer to a buffer into which the function is to copy the text.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pText parameter.

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageSelectedText

void GetPageSelectedText(LPSTR pText, UINT pLen)

Overview

Gets all text selected contained in the currently selected page. You can allocate your text string statically, or you can use a dynamic string to buffer the text data. For dynamic allocation, use a call to GetPageInfo to obtain the size of the page.

Parameters

  • pText - Pointer to a buffer into which the function is to copy the selected text.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pText parameter.

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


GetPageCursorPos

void GetPageCursorPos(UINT &pX, UINT &pY)

Overview

Gets the current page cursor position.

Parameters

  • pX - X coordinate. Returned value is not zero based. If the cursor is positioned at the first character of a line, the value returned will be equal to one.
  • pY - Y coordinate. Returned value is not zero based. If the cursor is positioned at the first line, the value returned will be equal to one.

Return Value

None

See Also

SetPageCursorPos
SetPageTopLine
GetPageDisplayLines
SetPageLineColor
SetPageLineColorDelete
SetPageLineColorClear
SetPageSelectTextAt


GetPageDisplayLines

void GetPageDisplayLines(UINT &pTopLine, UINT &pLinesInWindow)

Overview

Obtains the visible display extents of the current page.

Parameters

  • pTopLine - The line number at the top of the visible page.
  • pLinesInWindow - The number of visible page lines.

Return Value

None

See Also


Set Page

BOOL SetPage(LPSTR pFilename)

Overview

Sets the current IDE page.

Parameters

  • pFilename - Pointer to a null terminated page filename string. The filename string must point to a page currently open in the IDE.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


SetPageText

void SetPageText(LPSTR pText)

Overview

Places text into a page at the current cursor position.

Parameters

  • pText - Pointer to a null terminated text string.

Return Value

None

See Also

 GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


SetPageTextAt

void SetPageTextAt(LPSTR pText, UINT pX, UINT pY)

Overview

Places text into a page at the position specified by pX and pY.

Parameters

  • pText - Pointer to a null terminated text string.
  • pX - X coordinate. Value is not zero based. If the value is equal to one, the text is placed at the first character of a line.
  • pY - Y coordinate. Value is not zero based. If the value is equal to one, the text is placed at the first line.

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


SetPageSelectTextAt

void SetPageSelectTextAt(UINT pSelStart, UINT pSelLength)

Overview

Selects text in the current page.

Parameters

  • pSelStart - The start character position of the text to select.
  • pSelLength - The number of characters to select.

Return Value

None

See Also


SetPageUpdateText

void SetPageUpdateText(LPSTR pText, BOOL pSaveUpdate)

Overview

Clear all of the text on the current page and replace with the contents of pText.

Parameters

  • pText - Pointer to a null terminated text string.
  • pSaveUpdate - If true, the updated page is automatically saved to disk. A page will only be saved to disk if the page filename already exists and is not located on a floppy drive.

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


SetPageClear

void SetPageClear

Overview

Clears the current page.

Parameters

None

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


SetPageNew

void SetPageNew(LPSTR pPageName)

Overview

Create a new page called pPageName.

Parameters

  • pPageName - Pointer to a null terminated page name string. For example, "MyProgram.BAS".

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


SetPageInsertHeader

void SetPageInsertHeader

Overview

Inserts a page header at the top of the current page

Parameters

None

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageSave
SetPageLoad
SetPageClose
SetPageCloseAll


SetPageSave

BOOL SetPageSave(LPSTR pPageName)

Overview

Saves a page to disk. A page is only saved to disk if its modified flag is set to true.

Parameters

  • pPageName - Pointer to a null terminated page filename string. The page name string must point to a page currently open in the IDE.

Return Value

If the function succeeds the return value is non zero. If the function fails, or the user cancels a save operation, the return value is zero.

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageLoad
SetPageClose
SetPageCloseAll


SetPageLoad

void SetPageLoad(LPSTR pFilename)

Overview

Loads a file into the IDE.

Parameters

  • pFilename - Pointer to a null terminated filename string.

Return Value

None

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageClose
SetPageCloseAll


SetPageClose

BOOL SetPageClose(LPSTR pPageName)

Overview

Closes a currently open IDE page.

Parameters

  • pPageName - Pointer to a null terminated page filename string. The page name string must point to a page currently open in the IDE.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero. If the modified flag of the page is true and a user cancels a save operation, the page will not be closed and the return value will be zero.

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageCloseAll


SetPageClose

BOOL SetPageCloseAll(LPSTR pNewPageName)

Overview

Closes all currently open IDE pages.

Parameters

  • pNewPageName - Pointer to a null terminated page string. If a null string is specified, a new page called 'Untitled' is created after closing all open pages. To automatically rename the untitled page, pass a non null string. For example, "MyProgram.bas".

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero. If the modified flag of any page is true and a user cancels a save operation, no further pages are closed and the return value will be zero.

See Also

GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageClose


SetPageCursorPos

void SetPageCursorPos(UINT pX, UINT pY)

Overview

Sets the current page cursor position.

Parameters

  • pX - X coordinate. Value is not zero based. If the value is equal to one, the cursor is positioned at the first character of a line.
  • pY - Y coordinate. Value is not zero based. If the value is equal to one, the cursor is positioned at the first line.

Return Value

None

See Also

SetPageCursorPos
SetPageTopLine
GetPageDisplayLines
SetPageLineColor
SetPageLineColorDelete
SetPageLineColorClear
SetPageSelectTextAt


SetPageTopLine

void SetPageTopLine(UINT pTopLine)

Overview

Moves the current page display window to the top line. Use a call to GetPageDisplayLines to obtain the visible display extents of the current page.

Parameters

  • pTopLine - Moves the current page display window to the value specified by pTopLine.

Return Value

None

See Also

GetPageCursorPos
SetPageCursorPos
GetPageDisplayLines
SetPageLineColor
SetPageLineColorDelete
SetPageLineColorClear
SetPageSelectTextAt


SetPageVersion

void SetPageVersion(LPSTR pFilename, BYTE pMajor, BYTE pMinor, BYTE pRelease, BYTE pBuild)

Overview

Sets the version number for a page. Version numbers are always set, even if automatic incrementing of version information within the IDE has been disabled. You can set or obtain the state of the version information flag will calls to SetPageVersionEnabled and GetPageInfo respectively.

Parameters

  • pFilename - Pointer to a null terminated filename string of an open page.
  • pMajor - Major version.
  • pMinor - Minor version.
  • pRelease - Release version.
  • pBuild - Build version.

Return Value

None

See Also

SetPageVersionEnabled
GetPageInfo


SetPageVersionEnabled

void SetPageVersionEnabled(BOOL pValue)

Overview

Enables or disables automatic incrementing of version information after a successful compile. You can obtain the state of the version information flag will a call to GetPageInfo.

Parameters

  • pValue - Automatic incrementing version flag.

Return Value

None

See Also


SetPageLineColor

void SetPageLineColor(UINT pLineNumber, UINT pBGColor, UINT pFGColor)

Overview

Highlights a line of text.

Parameters

  • pLineNumber - The line to select. Value is not zero based. The first line of a page will correspond to a value of one.
  • pBGColor - The background colour of the line.
  • pFGColor - The foreground colour of the line.

Background and foreground colours are represented by a 32 bit value. When specifying a colour, the lower three bytes contain the RGB components. For example,

0x00BBGGRR

The value 0x00FF0000 represents pure blue, 0x0000FF00 is pure green and 0x000000FF is pure red. 0x00000000 is black and 0x00FFFFFF is white. Delphi uses can just use the TColor type to specify a colour. For example, pBGColor := clRed. C users may prefer to use the RGB macro. For example, pBGColor = RGB(RedValue, GreenValue, BlueValue).

Multiple line highlights can be added to a single page. To remove highlights, make a call to SetPageLineColorDelete or SetPageLineColorClear.

Return Value

None

See Also


SetPageLineColorDelete

void SetPageLineColorDelete(UINT pLineNumber)

Overview

Deletes a highlighted line of text.

Parameters

  • pLineNumber - The line to delete. Value is not zero based. The first line of a page will correspond to a value of one.

Multiple line highlights can be added to a single page with a call to SetPageLineColor.

Return Value

None

See Also


SetPageLineColorClear

void SetPageLineColorClear

Overview

Deletes all highlighted lines of text.

Parameters

None

Multiple line highlights can be added to a single page with a call to SetPageLineColor. Call SetPageLineColorDelete to remove a single highlighted line.

Return Value

None

See Also


IsProgrammerAvailable

BOOL IsProgrammerAvailable

Overview

Identifies the type of target programmer.

Parameters

None

Return Value

The function return value is non zero if the default programming device is not a plugin. The function return value is zero if the default programming device is a plugin. For example, the Labcenter ISIS simulator.

See Also

GetProgrammer
GetProgrammerInfo
GetProgrammerByIndex
GetProgrammerCount
SetProgrammer


GetProgrammer

void GetProgrammer(LPSTR pName, UINT pLen)

Overview

Gets the default programmer name. Use IsProgrammerAvailable to determine if the default programmer name is a plugin.

Parameters

  • pName - Pointer to a buffer into which the function is to copy the programmer name.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pName parameter.

Return Value

None

See Also


GetProgrammerInfo

BOOL GetProgrammerInfo(LPSTR pName, LPPROGINFO pInfo)

Overview

Gets programmer information.

Parameters

  • pName - Pointer to a null terminated programmer name string.
  • pInfo - Points to a PROGINFO structure that receives information about the programmer selected by the pName parameter.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also


GetProgrammerByIndex

BOOL GetProgrammerByIndex(UINT pIndex, LPSTR pName, UINT pLen)

Overview

Gets the name of an installed programming device. The number of programmers available can be obtained with a call to GetProgrammerCount.

Parameters

  • pIndex - The programmer index, which ranges from 0 to GetProgrammerCount - 1.
  • pName - Pointer to a buffer into which the function is to copy the programmer name.
  • pLen - Specifies the length, in characters, of the buffer pointed to by the pName parameter.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also

 IsProgrammerAvailable
GetProgrammer
GetProgrammerInfo
GetProgrammerCount
SetProgrammer


GetProgrammerCount

UINT GetProgrammerCount

Overview

Gets the number of installed programming devices. Used in conjunction will GetProgrammerByIndex.

Parameters

None

Return Value

Number of installed programming devices.

See Also


SetProgrammer

BOOL SetProgrammer(LPSTR pName)

Overview

Sets the current programming device.

Parameters

  • pName - Pointer to a null terminated programming device name.

Return Value

If the function succeeds the return value is non zero. If the function fails, the return value is zero.

See Also


ExecuteCompile

BOOL ExecuteCompile

Overview

Executes the compiler process. The function is a synchronous call. That is, it does not return until the compilation process has terminated. To execute the compiler asynchronously, call ExecuteCompileAsync.

Parameters

None

Return Value

If the compilation process succeeds the return value is non zero. If the compilation process fails, the return value is zero.

See Also
ExecuteCompileAsync
ExecuteProgram
IsProgrammerAvailable
GetProgrammer
GetProgrammerInfo
GetProgrammerByIndex
GetProgrammerCount
SetProgrammer

Associated Events

NotifyPreCompile
NotifyCompileSuccess
NotifyCompileFail
NotifyPreProgram


ExecuteCompileAsync

void ExecuteCompileAsync

Overview

Executes the compiler process. The function is an asynchronous call and returns immediately. To execute the compiler synchronously, call ExecuteCompile.

Parameters

None

Return Value

None

See Also
ExecuteCompile
ExecuteProgram
IsProgrammerAvailable
GetProgrammer
GetProgrammerInfo
GetProgrammerByIndex
GetProgrammerCount
SetProgrammer

Associated Events

NotifyPreCompile
NotifyCompileSuccess
NotifyCompileFail
NotifyPreProgram


ExecuteProgram

void ExecuteProgram

Overview

Executes the default programmer process. The function is an asynchronous call and returns immediately.

Parameters

None

Return Value

None

See Also
ExecuteCompile
ExecuteCompileAsync
IsProgrammerAvailable
GetProgrammer
GetProgrammerInfo
GetProgrammerByIndex
GetProgrammerCount
SetProgrammer

Associated Events

NotifyPreCompile
NotifyCompileSuccess
NotifyCompileFail
NotifyPreProgram


IDELock

void IDELock

Overview

A call to this function will lock the IDE interface. This feature can mimic a 'modal' dialog window, where the user is unable to interact with the application beneath the plugin window. In this mode of operation, it is strongly recommended that the plugin is created as a top most window. IDELock is also useful for plugin operations that may fail if the user were to modify pages or interact with the IDE.

A plugin that locks the IDE is responsible for unlocking the interface using a call to IDEUnlock. If two or more plugins lock the IDE, then the IDE will not be unlocked until each plugin has made a call to IDEUnlock.

Parameters

None

Return Value

None

See Also
IDEUnlock


IDEUnlock

void IDEUnlock

Overview

Unlocks a locked IDE. A call to this function will have no effect unless the plugin has made a previous call to IDELock. For more information on locking the IDE, see IDELock.

Parameters

None

Return Value

None

See Also

IDELock


Notification Messages

WM_NOTIFY_PLUGIN

The WM_NOTIFY_PLUGIN message informs the client process that an event has occurred in the IDE. The client application will only receive notification messages if a valid window handle has been passed to Connect. The wParam parameter indicates the type of message sent by the plugin and can be one of the following:

NotifyReloadPlugin

Indicates that the user has tried to start another instance of the client application, which has been blocked by the plugin manager. This is typically in response to the 'single instance with reload' flag being set the *.plg file.

NotifyTabChanged

Indicates that a page tab has changed. It should be noted that this message is sent immediately after a tab has changed and the new page loaded. In most cases it it advisable to wait for an explorer update message, rather than a tab changed message, to ensure any page information retrieved from the IDE is accurate (for example, the type of device used).

NotifyExplorerUpdate

Indicates that the code explorer window has finished processing a new or reloaded page.

NotifyPreCompile

Indicates that a project is about to be compiled. It is important to note that this message is synchronous and will not return until the client application has finished processing the message. Unduly long latencies when processing this message will result in poor performance in the IDE. Use with care.

NotifyPreProgram

Indicates that the target device it about to be programmed. It is important to note that this message is synchronous and will not return until the client application has finished processing the message. Unduly long latencies when processing this message will result in poor performance in the IDE. Use with care.

NotifyCompileSuccess

Indicates that a project has been compiled successfully.

NotfiyCompileFail

Indicates that a project has failed to compile.

NotifyDeviceChanged

The project device type has been changed.

NotifyOSCChanged

The project oscillator frequency has been changed.

NotifySelectionChanged

Indicates a new selection has been made on the currently active page.

NotifyProgrammerChanged

Indicates that the target programmer has been changed.

NotifyProgrammerInstalled

Indicates that a new programming device has been installed.

NotifyProgrammerDeleted

Indicates that an installed programming device has been deleted.

NotifyVersion

Indicates that the version information dialog has updated automatic version incrementing.

See Also

Notification Constants


PageInfo

The page information structure is filled with a call to GetPageInfo.

typedef struct _PAGEINFO
{
   char DisplayName [64];
   char Filename [256];
   char FilenameMCI [256];
   char FilenameASM [256];
   char FilenameHEX [256];
   BOOL Modified;
   char Device [16];
   UINT DeviceCore;
   UINT OSC;
   BOOL VersionEnabled;
   BYTE VersionMajor;
   BYTE VersionMinor;
   BYTE VersionRelease;
   BYTE VersionBuild;
   UINT PageSize;
   UINT PageSizeRTF;
} PAGEINFO;

Members

  • DisplayName - the name displayed in the IDE tab.
  • Filename - the page filename, including path.
  • FilenameMCI - IDE project file.
  • FilenameASM - The ASM filename, including path. This field with be filled with the ASM filename, even if it has not been created.
  • FilenameHEX - The HEX filename, including path. This field with be filled with the HEX filename, even if it has not been created.
  • Modified - The page modification flag.
  • Device - The project device name. For example, 16F877.
  • DeviceCore - The project device core type. Can be 12, 14 or 16.
  • OSC - The project clock frequency.
  • VersionEnabled - Version enabling flag.
  • VersionMajor - Major version of the project.
  • MinorVersion - Minor version of the project.
  • ReleaseVersion - Release version of the project.
  • BuildVersion - Build version of the project.
  • PageSize - The size in bytes of the page. The page size includes a two byte line termination sequence for every line and a NULL terminator.
  • PageSizeRTF - The size in bytes of the page in RTF format. The RTF page size includes a two byte line termination sequence for every line and a NULL terminator.

See Also

GetPageInfo


ProgInfo

The programmer information structure is filled with a call to GetProgrammerInfo.

typedef struct _PROGINFO
{
   char Path [256];
   char Filename [256];
   char Params [256];
   char ParamsBound [256];
   char HookFilename [256];
} PROGINFO;

Members

  • Path - The path to the programmer executable.
  • Filename - The programmer executable filename.
  • Params - Unbound command line parameters. For example, -pPIC$target-device$ $hex-filename$.
  • ParamsBound - Bound command line parameters. For example, -pPIC16F628 blink.hex
  • HookFilename - Filename of an optional pre-processing executable that is called before the main programmer process is executed.

See Also

GetProgrammerInfo


Notification Constants
WM_NOTIFY_PLUGIN | WM_USER + 100
Asynchronous |
NOTIFY_RELOAD_PLUGIN | 0x0001
NOTIFY_TAB_CHANGED | 0x0002
NOTIFY_EXPLORER_UPDATE | 0x0003
NOTIFY_COMPILE_SUCCESS | 0x0004
NOTIFY_COMPILE_FAIL | 0x0005
NOTIFY_DEVICE_CHANGED | 0x0006
NOTIFY_OSC_CHANGED | 0x0007
NOTIFY_SELECTION_CHANGED | 0x0008
NOTIFY_PROGRAMMER_CHANGED | 0x0009
NOTIFY_PROGRAMMER_INSTALLED | 0x000A
NOTIFY_PROGRAMMER_DELETED | 0x000B
NOTIFY_VERSION | 0x000C
Synchronous |
NOTIFY_PRE_COMPILE | 0x0100
NOTIFY_PRE_PROGRAM | 0x0101


Code Templates

The program manager DLL is called mcPluginMgr.dll. The following code templates provide a basic starting block for your plugin development by interfacing to this DLL.

Code Template for Borland Delphi

The Borland Delphi code template gives you all the constant, type and interface declarations you need to get your plugin up and running. The functions and procedures are statically linked. An improvement would be to introduce dynamic linking. This would provide your application with some protection should the target system have an earlier version of the plugin manager DLL installed.


Delphi Interface

unit cPluginInterface;

interface

uses
   Windows, Messages, cPluginTypes;

const
   // the plugin manager DLL name...
   DLL_NAME = 'mcPluginMgr.dll';

// DLL interface functions...
function plgConnect(pHostWin:HWND):BOOL;stdcall;external DLL_NAME name 'Connect';
function plgDisconnect:BOOL;stdcall;external DLL_NAME name 'Disconnect';
function plgIsConnected:BOOL;stdcall;external DLL_NAME name 'IsConnected';
procedure plgGetPathIDE(pPath:LPSTR;pLen:UINT);stdcall; external DLL_NAME name 'GetPathIDE';
procedure plgGetPathCompiler(pPath:LPSTR;pLen:UINT);stdcall; external DLL_NAME name 'GetPathCompiler';
procedure plgGetPathPlugin(pPath:LPSTR;pLen:UINT);stdcall; external DLL_NAME name 'GetPathPlugin';
procedure plgGetPage(pFilename:LPSTR;pLen:UINT);stdcall; external DLL_NAME name 'GetPage';
function plgGetPageInfo(pFilename:LPSTR;pInfo:LPPAGEINFO):BOOL;stdcall; external DLL_NAME name 'GetPageInfo';
function plgSetPage(pFilename:LPSTR):BOOL;stdcall; external DLL_NAME name 'SetPage';
function plgGetPageByIndex(pIndex:UINT;pFilename:LPSTR;pLen:UINT):BOOL;stdcall; external DLL_NAME name 'GetPageByIndex';
function plgGetPageCount:UINT;stdcall;external DLL_NAME name 'GetPageCount';
function plgGetPageIncludeByIndex(pFilename:LPSTR;pIndex:UINT;pInclude:LPSTR;pLen:UINT):BOOL;stdcall; external DLL_NAME name 'GetPageIncludeByIndex';
function plgGetPageIncludeCount(pFilename:LPSTR):UINT;stdcall;external DLL_NAME name 'GetPageIncludeCount';
procedure plgSetPageNew(pFilename:LPSTR);stdcall; external DLL_NAME name 'SetPageNew';
procedure plgSetPageClear;stdcall; external DLL_NAME name 'SetPageClear';
procedure plgSetPageInsertHeader;stdcall; external DLL_NAME name 'SetPageInsertHeader';
procedure plgGetPageText(pText:LPSTR;pLen:UINT);stdcall; external DLL_NAME name 'GetPageText';
procedure plgGetPageTextRTF(pText:LPSTR;pLen:UINT);stdcall; external DLL_NAME name 'GetPageTextRTF';
procedure plgGetPageSelectedText(pText:LPSTR;pLen:UINT);stdcall; external DLL_NAME name 'GetPageSelectedText';
procedure plgSetPageUpdateText(pText:LPSTR;pSaveUpdate:BOOL);stdcall; external DLL_NAME name 'SetPageUpdateText';
procedure plgSetPageText(pText:LPSTR);stdcall; external DLL_NAME name 'SetPageText';
procedure plgSetPageTextAt(pX,pY:UINT;pText:LPSTR);stdcall; external DLL_NAME name 'SetPageTextAt';
procedure plgSetPageSelectTextAt(pSelStart,pSelLength:UINT);stdcall; external DLL_NAME name 'SetPageSelectTextAt';
procedure plgSetPageCursorPos(pX,pY:UINT);stdcall; external DLL_NAME name 'SetPageCursorPos';
procedure plgGetPageCursorPos(var pX:UINT;var pY:UINT);stdcall; external DLL_NAME name 'GetPageCursorPos';
procedure plgSetPageTopLine(pLineNumber:UINT);stdcall; external DLL_NAME name 'SetPageTopLine';
procedure plgGetPageDisplayLines(var pTopLine:UINT;var pLinesInWindow:UINT);stdcall; external DLL_NAME name 'GetPageDisplayLines';
procedure plgSetPageSave; stdcall;external DLL_NAME name 'SetPageSave';
procedure plgSetPageLoad(pFilename:LPSTR); stdcall;external DLL_NAME name 'SetPageLoad';
procedure plgSetPageVersion(pFilename:LPSTR;pMajor,pMinor,pRelease,pBuild:BYTE); stdcall;external DLL_NAME name 'SetPageVersion';
procedure plgSetPageVersionEnabled(pFilename:LPSTR;pValue:BOOL);stdcall;external DLL_NAME name 'SetPageVersionEnabled';
procedure plgSetPageLineColor(pLineNumber,pBG,pFG:UINT);stdcall;external DLL_NAME name 'SetPageLineColor';
procedure plgSetPageLineColorDelete(pLineNumber:UINT);stdcall;external DLL_NAME name 'SetPageLineColorDelete';
procedure plgSetPageLineColorClear;stdcall;external DLL_NAME name 'SetPageLineColorClear';
function plgIsProgrammerAvailable:BOOL;stdcall;external DLL_NAME name 'IsProgrammerAvailable';
procedure plgGetProgrammer(pName:LPSTR;pLen:UINT);stdcall; external DLL_NAME name 'GetProgrammer';
function plgGetProgrammerInfo(pName:LPSTR;pInfo:LPPROGINFO):BOOL;stdcall; external DLL_NAME name 'GetProgrammerInfo';
function plgSetProgrammer(pName:LPSTR):BOOL;stdcall; external DLL_NAME name 'SetProgrammer';
function plgGetProgrammerByIndex(pIndex:UINT;pName:LPSTR;pLen:UINT):BOOL;stdcall; external DLL_NAME name 'GetProgrammerByIndex';
function plgGetProgrammerCount:UINT;stdcall;external DLL_NAME name 'GetProgrammerCount';
function plgExecuteCompile:BOOL;stdcall; external DLL_NAME name 'ExecuteCompile';
procedure plgExecuteCompileAsync;stdcall; external DLL_NAME name 'ExecuteCompileAsync';
procedure plgExecuteProgram;stdcall; external DLL_NAME name 'ExecuteProgram';
procedure plgSetLoadFromFile(pFilename:LPSTR); stdcall;external DLL_NAME name 'SetLoadFromFile';
procedure plgSetForegroundWindow;stdcall; external DLL_NAME name 'SetForegroundWindow';

implementation

end.


Delphi Messages

unit cPluginMessages;

interface

uses
   Messages;

const
   WM_NOTIFY_PLUGIN = WM_USER + 100;

   // asynchronous
   NOTIFY_RELOAD_PLUGIN = $0001;
   NOTIFY_TAB_CHANGED = $0002;
   NOTIFY_EXPLORER_UPDATE = $0003;
   NOTIFY_COMPILE_SUCCESS = $0004;
   NOTIFY_COMPILE_FAIL = $0005;
   NOTIFY_DEVICE_CHANGED = $0006;
   NOTIFY_OSC_CHANGED = $0007;
   NOTIFY_SELECTION_CHANGED = $0008;
   NOTIFY_PROGRAMMER_CHANGED = $0009;
   NOTIFY_PROGRAMMER_INSTALLED = $000A;
   NOTIFY_PROGRAMMER_DELETED = $000B;
   NOTIFY_VERSION = $000C;

   // synchronous
   NOTIFY_PRE_COMPILE = $0100;
   NOTIFY_PRE_PROGRAM = $0101;

implementation

end.


Delphi Code Template

unit UnitMain;

interface

uses
   Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs,
   cPluginInterface, cPluginTypes, cPluginMessages;

type
   // main form object...
   TMainForm = class(TForm)
      procedure FormCreate(Sender: TObject);
      procedure FormDestroy(Sender: TObject);
   private
      function OnMessageHook(var Message : TMessage) : Boolean;
   public
   end;
var
   MainForm: TMainForm;

implementation

{$R *.DFM}

// create main
form...
procedure TMainForm.FormCreate(Sender: TObject);
begin
Application.HookMainWindow(OnMessageHook);
plgConnect(Application.Handle);
end;

// destroy main form...
procedure TMainForm.FormDestroy(Sender: TObject);
begin
   Application.UnhookMainWindow(OnMessageHook);
end;

// message hook - process messages in here...
function TMainForm.OnMessageHook(var Message : TMessage) : Boolean;
begin
   Result := False;
   if Message.Msg = WM_NOTIFY_PLUGIN then
   begin
      Result := true;
      case Message.WParam of
         NOTIFY_RELOAD_PLUGIN : begin end;
         NOTIFY_TAB_CHANGED : begin end;
         NOTIFY_EXPLORER_UPDATE : begin end;
         NOTIFY_PRE_COMPILE : begin end;
         NOTIFY_PRE_PROGRAM : begin end;
         NOTIFY_COMPILE_SUCCESS : begin end;
         NOTIFY_COMPILE_FAIL : begin end;
         NOTIFY_DEVICE_CHANGED : begin end;
         NOTIFY_OSC_CHANGED : begin end;
         NOTIFY_SELECTION_CHANGED : begin end;
         NOTIFY_PROGRAMMER_CHANGED : begin end;
         NOTIFY_PROGRAMMER_INSTALLED : begin end;
         NOTIFY_PROGRAMMER_DELETED : begin end;
         NOTIFY_VERSION : begin end;
      end;
   end;
end;

end.


Delphi Types

unit cPluginTypes;

interface

uses
Windows;
type
LPPAGEINFO = pointer;
LPPROGINFO = pointer;
TString_256 = array[0..255] of char;
TString_64 = array[0..63] of char;
TString_16 = array[0..15] of char;

// page information structure...
TPageInfo = record
DisplayName    : TString_64;
Filename       :
TString_256;
FilenameMCI    : TString_256;
FilenameASM    : TString_256;
FilenameHEX    : TString_256;
Modified       :
BOOL;
Device
: TString_16;
DeviceCore     : UINT;
OSC
: UINT;
VersionEnabled : BOOL;
VersionMajor   : BYTE;
VersionMinor   : BYTE;
VersionRelease : BYTE;
VersionBuild   : BYTE;
PageSize       :
UINT;
PageSizeRTF    : UINT;
end;

   //
programmer information structure...
TProgrammerInfo = record
Path
: TString_256;
Filename     : TString_256;
Params       :
TString_256;
ParamsBound  : TString_256;
HookFilename : TString_256;
end;

implementation

end.


Plugin Interface Reference

Connect
Disconnect
IsConnected
GetPathCompiler
GetPathIDE
GetPathPlugin
GetPage
GetPageInfo
GetPageByIndex
GetPageCount
GetPageIncludeByIndex
GetPageIncludeCount
GetPageText
GetPageSelectedText
GetPageCursorPos
GetPageDisplayLines
SetPage
SetPageText
SetPageTextAt
SetPageUpdateText
SetPageSelectTextAt
SetPageClear
SetPageNew
SetPageInsertHeader
SetPageSave
SetPageLoad
SetPageCursorPos
SetPageTopLine
SetPageVersion
SetPageVersionEnabled
SetPageLineColor
SetPageLineColorDelete
SetPageLineColorClear
IsProgrammerAvailable
GetProgrammer
GetProgrammerInfo
GetProgrammerByIndex
GetProgrammerCount
SetProgrammer
ExecuteCompile
ExecuteCompileAsync
ExecuteProgram

Notification Events

WM_NOTIFY_PLUGIN
 NotifyReloadPlugin
NotifyTabChanged
NotifyExplorerUpdate
NotifyPreCompile
NotifyPreProgram
NotifyCompileSuccess
NotfiyCompileFail
NotifyDeviceChanged
NotifyOSCChanged
NotifySelectionChanged
NotifyProgrammerChanged
NotifyProgrammerInstalled
NotifyProgrammerDeleted
NotifyVersion


DLL Interface Reference

Connect(pHostWin:HWND):BOOL
Disconnect:BOOL
IsConnected:BOOL

GetPathCompiler(pPath:LPSTR;pLen:UINT)
GetPathIDE(pPath:LPSTR;pLen:UINT)
GetPathPlugin(pPath:LPSTR;pLen:UINT)

GetPage(pFilename:LPSTR;pLen:UINT)
GetPageInfo(pFilename:LPSTR;pInfo:LPPAGEINFO):BOOL
GetPageByIndex(pIndex:UINT;pFilename:LPSTR;pLen:UINT):BOOL
GetPageCount:UINT
GetPageIncludeByIndex(pFilename:LPSTR;pIndex:UINT;pInclude:LPSTR;pLen:UINT)
GetPageIncludeCount(pFilename:LPSTR):UINT
GetPageText(pText:LPSTR;pLen:UINT)
GetPageSelectedText(pText:LPSTR;pLen:UINT)
GetPageCursorPos(var pX:UINT;var pY:UINT);
GetPageDisplayLines(var pTopLine:UINT;var pLinesInWindow:UINT)

SetPage(pFilename:LPSTR):BOOL
SetPageText(pText:LPSTR)
SetPageTextAt(pX,pY:UINT;pText:LPSTR)
SetPageUpdateText(pText:LPSTR)
SetPageSelectTextAt(pSelStart,pSelLength:UINT)
SetPageClear
SetPageNew(pFilename:LPSTR)
SetPageInsertHeader
SetPageSave
SetPageCursorPos(pX,pY:UINT)
SetPageTopLine(pLineNumber:UINT);
SetPageVersion(pFilename:LPSTR;pMajor,pMinor,pRelease,pBuild:BYTE)
SetPageVersionEnabled(pFilename:LPSTR;pValue:BOOL)
SetPageLineColor(pLineNumber,pBG,pFG:UINT)
SetPageLineColorDelete(pLineNumber:UINT)
SetPageLineColorClear

IsProgrammerAvailable:BOOL
GetProgrammer(pName:LPSTR;pLen:UINT)
GetProgrammerInfo(pName:LPSTR;pInfo:LPPROGINFO):BOOL
GetProgrammerByIndex(pIndex:UINT;pName:LPSTR;pLen:UINT):BOOL
GetProgrammerCount:UINT
SetProgrammer(pName:LPSTR):BOOL

ExecuteCompile
ExecuteCompileAsync
ExecuteProgram

SetSaveToFile(pFilename:LPSTR)
SetLoadFromFile(pFilename:LPSTR)
SetForegroundWindow

Notification Events

WM_NOTIFY_INTERNAL

Asynchronous Events

NOTIFY_RELOAD_PLUGIN
NOTIFY_TAB_CHANGED
NOTIFY_EXPLORER_UPDATE
NOTIFY_COMPILE_SUCCESS
NOTIFY_COMPILE_FAIL
NOTIFY_DEVICE_CHANGED
NOTIFY_OSC_CHANGED
NOTIFY_SELECTION_CHANGED
NOTIFY_PROGRAMMER_CHANGED
NOTIFY_PROGRAMMER_INSTALLED
NOTIFY_PROGRAMMER_DELETED
NOTIFY_VERSION

 Synchronous Events

 NOTIFY_PRE_COMPILE
NOTIFY_PRE_PROGRAM


Plugin Editor

When testing or distributing your plugin, you need a way of placing your plugin on the main IDE plugin menu. To do this, you will need to use the Plugin Editor to generate a *.mcp file. The *.mcp file is used by the IDE to register the plugin.

Plugin *.mcp files should always be located in the IDE Plugin subfolder. If you plan to distribute your plugin, you should ideally place your *.mcp file and associated executable in the same plugin subfolder. For example,

c:\program files\ProtonIDE\Plugin\YourCompany\ImageConverter.mcp
c:\program files\ProtonIDE\Plugin\YourCompany\Converter.exe

The Plugin Editor can be accessed from the IDE plugin menu.

Menu Options

The menu options tab enables you to specify how the plugin is presented to the user on the IDE plugin menu. It is also used to specify how and when plugins are executed by the IDE.

The first field allows you to enter the name of your plugin that will appear on the IDE plugin menu. The second field allows you to specify a group name. Using a group name is optional, but strongly recommended. It enables you to group programs into a single category and prevents the main plugin menu from becoming cluttered. Use something meaningful for the group name, such as 'Image Processing'. Alternatively, use your company name if you plan to provide multiple plugin programs.

The Plugin Name field has a drop down menu option to the right of the edit box, as shown below:

Separator Before Name

Allows you to place a menu separator before the name entry. This option is also available in the Group Name drop down menu.

Separator After Name

Allows you to place a menu separator after the name entry. This option is also available in the Group Name drop down menu.

Instance

Selecting the instance option reveals a number of sub-options, as shown below:

  • Single with Terminate - If the user selects a plugin from the menu that is already running, the current plugin process is terminated and a new instance started.
  • Single with Reload Message - If the user selects a plugin from the menu that is already running, the new instance is blocked (that is, it will not be started) and a NotifyPluginReload message is sent to the currently running plugin process.
  • Multiple - If the user selects a plugin from the menu that is already running, a new instance of the plugin is started.

Programmer Link

This option enables a plugin to appear on the main IDE 'select programmer' drop down menu. A good example of this type of plugin is the Labcenter Electronics ISIS simulator.

Enabled

Selecting the enabled option reveals a number of sub-options, as shown below:

  • Always - The plugin item is always available from the plugin menu.
  • ASM File Required - The plugin item is disabled (greyed out) if an ASM file is not available for the current project.
  • HEX File Required - The plugin items is disabled (greyed out) if a HEX file is not available for the current project.
  • Selected Text Required - The plugin is disabled (greyed out) if the current page has no text selected.

Auto Execute

Selecting this option will automatically execute the plugin when the IDE is started.

Menu Item Visible

Selecting this option will make the plugin available from the IDE plugin menu. The default is enabled.

Speed Button Visible

Selecting this option will make the plugin available on the IDE plugin toolbar. The default is disabled.

The IDE uses alpha blended icon images at 24x24 and 16x16 pixels for large and small toolbar images respectively. Plugin toolbar images are normally extracted from the 32x32 pixel icon embedded in the plugin executable, which is then scaled appropriately. For best display results, your plugin icon should be 24 bit colour with an 8 bit alpha channel. This allows icons to be displayed with smooth edges that appear to blend into any background. Icons which have 24 bit colour with an 8 bit alpha channel are the new Windows XP standard. However, the IDE will happily display this type of image on non-XP system (for example, Window 98SE). For more information, see

Creating Windows XP Icons
Download Windows XP Icons

You can use a standard 8 or 4 bit icon if you wish, the IDE will automatically convert the image into 24 bit colour with an 8 bit alpha channel and scale to fit the toolbar.

If you would like to use a different icon for the plugin, that is, you don't want the IDE to extract the icon from the plugin executable, then simply place a 32x32 pixel icon file (*.ico) in the same folder as your plugin *.mcp file. The icon file should have the same name as the plugin *.mcp file. For example, if you have a file called MyPlugin.mcp, then your icon should be called MyPlugin.ico.

Link Options

The link options tab allows you to specify which program the IDE should execute.

The first field specifies which program, document or web page the plugin should link to. The second command line parameters field is an optional edit box for programs that haven't been designed to use the plugin manager DLL, supplied with version 1.0.1.0 or higher of the IDE. It has limited use for programs designed to use the IDE plugin framework and should normally be left empty.

The best way of specifying a link-to item is to select the drop down menu to the right of the 'link to' edit box, as shown below:

Program Executable or Document

This option enables you browse and point the plugin menu item to a specific executable or document. In the example above, the plugin links to a executable called 'Info.exe'. Notice the first part of the field contains $IDE. This ensures that no matter where the use has installed the IDE, the plugin will always be found. This is because $IDE will be replaced at runtime with the actual path of the current installation. If you plan to distribute your plugins to other people, you should always let the Editor use its relative path notations. Never use absolute path names.

Web Page

This option enables you to link to a web page.