NPBuilder Plugins and their use
The NPBuilder application features Plugins which are a way to extend the features of the application (externally) and which allows you to customize it to your own specific needs. So, what is a Plugin ?
Simply put, a Plugin is a standard 32 bit Windows DLL (Dynamic Link Library). A Plugin though requires an entrance function to be exported which allows NPBuilder to recognize it as a valid Plugin. If found in the NPBuilder's \AppPlugins\ subfolder, NPBuilder will call this function one time at startup to initialize the Plugin and also pass it vital information for two-way communication between NPBuilder and the Plugin. Below is the Plugin entrance function. It must be an exported function so Windows will recognize it as such.
#INCLUDE "NPplugin.inc"
FUNCTION INIT_NPTOOL(BYREF ToolInfo AS NPTOOL) EXPORT AS DWORD
NPInitBuilderAPI ToolInfo ' required to allow calling back to Builder API
ToolInfo.ToolName = "Visual Basic"
ToolInfo.ToolImageID = 8
ToolInfo.ToolLangID = 0 ' language template ID number for above text
ToolInfo.ToolType = 2 ' Plugin type, in this case Code Generator Plugin for Code Blocks section of NPBuilder
ToolInfo.lpEvents = CODEPTR(MyFormEvents)
ToolInfo.lpDesign = CODEPTR(MyEnumAddControls)
ToolInfo.FormWidth = 65 ' -1 means default
ToolInfo.FormHeight = 23 ' -1 means default
FUNCTION = 1
END FUNCTION
Above is the entrance function all Plugins require. The code above is written for the Powerbasic compiler, but any compiler which can create a standard 32 bit Windows DLL can be used. An include file (in C they are called Header files) is used which predefines a number of important structures, constants and wrappers for key functions for communicating back to NPBuilder using callback functions via pointers. Part of the NPTOOL structure passes information to the Plugin and part of it is used to pass back information from the Plugin to NPBuilder.
NPBuilder always creates a blank Form (Dialog) when a Plugin Dialog is requested (sometimes by clicking icon buttons on a vertical toolbar or sometimes from a menu option). The Plugin must return two pointers for two special functions needed for creating the Plugins Dialog. The first is MyEnumAddControls (or any name you choose) which is defined below. This function is called every time the Plugin Dialog is requested and the function defines the controls which will appear on the Dialog. The second function is MyFormEvents (or any name you choose) which is where the NPBuilder application will forward events generated by the controls on the Plugins Dialog.
FUNCTION MyEnumAddControls(BYREF MyCtrl() AS NPCONTROL) AS LONG
' By filling in each item in the NPCONTROL structure array it defines each control for Form
' Plugin Form can define a maximum of 100 controls and no more
' Function then returns a value which is the number of controls defined
END FUNCTION
FUNCTION MyFormEvents(BYVAL MyID AS LONG, BYVAL CMsg AS LONG, BYVAL CVal AS LONG, BYREF CancelEvent AS LONG) AS LONG
' Parameters are:
' MyID passes the ID number of the control which generated event. If the event is the form itself the ID is zero
' CMsg passes a predefined constant for an event type. In Windows controls generate messages, which NPBuilder converts to event constants
' CVal passes a value for some events (ie. a Trackbar will pass its new position)
' CancelEvent passes a value of zero, but some events can be cancelled so setting this variable to 1 tells NPBuilder to cancel the event
' FUNCTION should return a value of 1
END FUNCTION
Here is an example of the above routines with actual code to define the Dialog and then process the control events:
FUNCTION MyEnumAddControls(BYREF MyCtrl() AS NPCONTROL) AS LONG
NPSetCtrlPtr VARPTR(MyCtrl(0)) ' stores pointer for shortcut API calls
NPSetAttr 100, %NP_Arial12B, 0, 25, "CF"
NPAddControl "LABEL", 1.25, 1.5, 62, 1.75, "Visual Basic Code Generator"
' -------------------------------------
NPSetAttr 105, %NP_Arial9B, -1, -1, ""
LOCAL CList$
CList$ = ""
CList$ = CList$ + "Generate Module Level Code (declares and library functions)|"
CList$ = CList$ + "Generate Get Device List Code|"
CList$ = CList$ + "Generate Code Block Primary (START/END) Code|"
CList$ = CList$ + "Generate Code Block Subroutine (SUB) Code"
VB_GenMode = 1 ' first item
NPAddControl "COMBOBOX", 4, 1.5, 62, 17.25, CList$
' -------------------------------------
NPSetAttr 107, %NP_Arial9, 0, 15, ""
NPAddControl "TEXTM", 6, 3.5, 58, 3.5, ""
' -------------------------------------
NPSetAttr 108, %NP_Arial9, 0, 125, ""
NPAddControl "CHECKBOX", 10.5, 3.5, 58, 1.5, "Build Strings using NP_AddVB API instead of using Visual Basic variables"
' -------------------------------------
NPSetAttr 109, %NP_Arial9, 0, 125, ""
NPAddControl "CHECKBOX", 12.25, 3.5, 58, 1.5, "Make Code Block SUB routines Private instead of Public"
' -------------------------------------
NPSetAttr 110, %NP_Arial11, 0, 25, ""
NPAddControl "ODBUTTON", 15, 1.5, 42, 2.75, "Generate Code and Copy to Windows Clipboard"
' -------------------------------------
NPSetAttr 112, %NP_Arial9, -1, -1, ""
NPAddControl "COMBOBOX", 14.75, 45, 19, 10, "NO Extra Spaces|Offset 5 Extra Spaces|Offset 10 Extra Spaces"
VB_AddSpace = 0
' -------------------------------------
NPSetAttr 113, %NP_Arial8, 0, 20, "C"
NPAddControl "LABEL", 16.5, 45, 19, 2, "Only for: Get Device code|or Code Block Primary code"
' -------------------------------------
NPSetAttr 114, %NP_Arial11, 0, 26, ""
NPAddControl "ODBUTTON", 19, 1.5, 42, 2.75, "Copy Runtimes (32 bit DLLs) to my VB Project"
' -------------------------------------
NPSetAttr 115, %NP_Arial12, 0, 23, ""
NPAddControl "ODBUTTON", 19.75, 56, 8, 2.75, "Exit"
' -------------------------------------
NPSetCtrlPtr 0 ' turns off shortcut syntax
FUNCTION = NPGetControlCount
END FUNCTION
FUNCTION MyFormEvents(BYVAL MyID AS LONG, BYVAL CMsg AS LONG, BYVAL CVal AS LONG, BYREF CancelEvent AS LONG) AS LONG
SELECT CASE MyID
CASE %NP_Form ' parent form event
IF CMsg = %NP_Loaded THEN
UpdateDescText 1
END IF
IF CMsg = %NP_Started THEN
END IF
IF CMsg = %NP_Close THEN
END IF
CASE 100 ' LABEL
CASE 105 ' COMBOBOX
IF CMsg = %NP_Change THEN
VB_GenMode = CVal + 1
UpdateDescText CVal + 1
END IF
CASE 110 ' ODBUTTON
IF CMsg = %NP_Click THEN
DoCodeGenVB VB_GenMode
END IF
CASE 112 ' combobox
IF CMsg = %NP_Change THEN
VB_AddSpace = CVal
END IF
CASE 114
IF CMsg = %NP_Click THEN
NP_RunTask "COPYFILES"
END IF
CASE 115 ' ODBUTTON
IF CMsg = %NP_Click THEN
NP_RunTask "EXIT"
END IF
CASE ELSE
END SELECT
FUNCTION = 1
END FUNCTION
Plugins can be hand coded, but NPBuilder also provides a faster way to get started in designing your plugin with its own Plugin Visual Designer and Code Generator.
NPBuilder supports Plugins for different purposes. So how does NPBuilder know what kind of Plugin it is ?
It looks at the values passed back by the Plugin when it is initialized.
FUNCTION INIT_NPTOOL(BYREF ToolInfo AS NPTOOL) EXPORT AS DWORD
NPInitBuilderAPI ToolInfo ' required to allow calling back to Builder API
ToolInfo.ToolName = "Visual Basic"
ToolInfo.ToolImageID = 8
ToolInfo.ToolLangID = 0 ' language template ID number for above text
ToolInfo.ToolType = 2 ' code gen plugin
ToolInfo.lpEvents = CODEPTR(MyFormEvents)
ToolInfo.lpDesign = CODEPTR(MyEnumAddControls)
ToolInfo.FormWidth = 65 ' -1 means default
ToolInfo.FormHeight = 23 ' -1 means default
FUNCTION = 1
END FUNCTION
In the above code notice the ToolInfo.ToolType field in the NPTOOL structure. The Plugin sets this value to tell NPBuilder what kind of Plugin it is. Currently 3 types of Plugins are supported:
ToolInfo.ToolType = 1 ' This is a Plugin for the BScript Editor vertical Toolbar
ToolInfo.ToolType = 2 ' This is a Plugin for the Code Block Editor vertical Toolbar
ToolInfo.ToolType = 9 ' This is a Plugin for the Other Languages option on the Plugin Visual Designer menu