Jump to content

Project Provider Framework

From LabVIEW Wiki
Revision as of 22:18, 21 March 2024 by Q (talk | contribs) (→SourceControl Interface Methods: Added methods)

The Project Provider Framework is an unsupported API used to extend LabVIEW in various ways, mostly relating to the project interface. While NI does not provide official support for Project Providers, nor guarantee their stability in future versions, they have provided some documentation as well as a community forum for the framework; this was originally only available to NI-approved developers but has since been opened to the general public.

Features

Things that can be done using Project Providers:

  1. Add Menu Items (globally or per specific item types)
  2. Add Toolbar Buttons
  3. Add Items to the Project Tree
  4. Add Right-Click (Popup or Context) Menu Items
  5. Customize the Double-Click Behavior of an Item
  6. Modify the Name or Icon of an Item in the Project Tree
  7. Save More Information Related to an Item
  8. Drag and Drop Items to and Within a Project

Primary vs Secondary Providers

Providers can be either a Primary or a Secondary Provider.

  • A Primary Provider puts one or more new item types into the project tree.
  • A Secondary Provider adds additional functionality to existing items, but is not responsible for creating or managing those items.

Therefore, a Secondary Provider does not cause new items to be displayed in the tree but attaches to items shown by other Primary Providers.

Project Provider INI File

A Project Provider is defined by an INI file located in the [LabVIEW 20xx]\resource\Framework\Providers\GProviders directory in the LabVIEW installation directory. This file contains paths to "interface VI's", which determine the locations of other VI's that implement the plugin's functionality. 

[Provider]
SupportedType={D60740D6-F254-4BBC-5675-8858F35B810E}
GlobalItemInterfaceVI=..\SecondaryProviderExample1\SecondaryProviderExample1_Global_Interface.vi
ItemInterfaceVI=..\SecondaryProviderExample1\SecondaryProviderExample1_Item_Interface.vi
ProviderInterfaceVI=..\SecondaryProviderExample1\SecondaryProviderExample1_Provider_Interface.vi
IsPrimary=0
LicenseName=None
InterfaceVersion=1.0
Signature=J7W9927AAAAAA5TBNTSSTTLWR29CNT9X

The INI files can contain the following keys:

Keys Description
SupportedInterface Indicates which interfaces are supported by the provider.
SupportedType Specifies a GUID that represents the type of project item type. (See ProjectItems)

Must be formatted as follows: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} For a Secondary Provider, this can point to the Alias of the item type it wants to attach to instead of the GUID.

Alias Is a unique string that like the GUID, is used to identify the project item type (applies to Primary Providers only).
IsPrimary
  • 1 – Primary provider (defines a new item type in the project).
  • 0 – Secondary provider (adds functionality to the existing item(s) in the project).
ItemInterfaceVI Defines the VI that enumerates the “Item” interface.
ProviderInterfaceVI Defines the VI that enumerates the “Provider” interface.
GlobalItemInterfaceVI Defines the VI that enumerates the ”Global” item interface.
CreateNewWizardInterfaceVI Defines the VI that enumerates the “CreateNewWizard” interface.
SourceControlInterfaceVI Defines the VI that enumerates the “SourceControl” interface.
DeployInterfaceVI Defines the VI that enumerates the “Deploy” interface.
BuildInterfaceVI Defines the VI that enumerates the “Build” interface.
CreateNewWizardHost (Primary providers only) Defines which “New” menu to add to e.g., Source, Build.
InterfaceVersion Specifies the interface version used by the provider. Currently, this must be set to 1.0.
Signature Digital signature – generated by NI. (Or See Below)

Supported Types

The SupportedType key in a Primary Provider’s INI file acts as the type ID of the item it creates. If it is a new type this GUID must be in the form of: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

The SupportedType key in a Secondary Provider’s INI file defines which item type is supported (or Alias in the case of Primary Providers).

See ProjectItems for the list of LabVIEW Item Types.

Supported Interfaces

Primary Providers specify their supported interfaces by including them in their INI file. Secondary Providers specify their supported interfaces through:

  1. Implicitly inheriting the Interfaces through the Primary Provider they support as defined by the SupportedType key
  2. Explicitly defining the Interfaces through the regular keys in the INI file just as the Primary Provider does

Signature

For LabVIEW to load a project provider, its INI file must contain a valid "signature" consisting of an enciphered MD5 hash of certain other values in the INI file, generated using a signing tool provided by NI. This is an artifact from before the framework was officially made public, though the method of generating the signature had been reverse-engineered and was publicly known before that point.

Algorithm

What follows is an explanation of how the "signature" is determined. If you are using the official signing tool (or an unofficial one) you do not need to know this, but it might be useful for tool developers or anyone curious.

First, take the values (not the keys) in the INI file in order, and concatenate them. Only include the values for keys in this list (rule of thumb: string values, not Boolean or numeric values, and don't include the Signature key of course):

  • "InterfaceVersion"
  • "LicenseRestrictions"
  • "LicenseVersion"
  • "LicenseName"
  • "Alias"
  • "SupportedType"
  • "SupportedInterface"
  • "CreateNewWizardHost"
  • "BuildInterfaceVI"
  • "DeployInterfaceVI"
  • "SourceControlInterfaceVI"
  • "CreateNewWizardInterfaceVI"
  • "GlobalItemInterfaceVI"
  • "ProviderInterfaceVI"
  • "ItemInterfaceVI"

Do not include spaces or other delimiters between values in the concatenated string. Take the MD5 hash of this string, and apply the following substitution cipher to each of the digits: 

Change: 0123456789ABCDEF
    To: T3C5K7W9SBNRJLX2

Finally, for each pair of two consecutive digits, switch them. For example, CRTTR3X7 would become RCTT3R7X.

Interface VIs

The framework specifies a list of interfaces that providers must implement. Each interface VI is a list of paths to dispatch VIs that point to each of the required methods that the providers must implement. Only the methods that the provider will provide need to be implemented. The VIs implementing these methods must conform to the particular Connector Pane but the contents can be completely customized. Once a provider-based event occurs the provider framework will run the appropriate VI if a method has been customized for that event in the provider. For example if Item.OnSelect has been implemented, it will be called when the project item is selected. The Interface VIs:

  1. Build
  2. CreateNewWizard
  3. Global
  4. Item
  5. ProjectDeployItem
  6. Provider
  7. SourceControl

Build Interface Methods

Primary Providers Only Defines events that apply to builds, i.e. items under Build Specifications, in the project tree. These include:

Methods need definitions
Method Definition
Invoke
Preview
IsRunnable
Run
On-Duplicate

CreateNewWizard Interface Methods

Primary Providers Only Defines events that occur while adding items of new types to the project tree.

Method Definition
Finalize Description: Called after the new item has been created.

Inputs:

  • Wizard (ItemRef) - Reference to the wizard
  • Item (ItemRef) - Reference to the newly created item

Outputs: None

GetCreateNewWeight Description: Called when the appropriate New menu is being constructed.

Inputs:

  • Wizard (ItemRef) - Reference to the wizard

Outputs:

  • Weight (I32) - Controls the relative position of the entry in the New menu
GetNewItemInfo Description: Called whenever right-clicked on an item that supports this New menu.

Inputs:

  • Wizard (ItemRef) - Reference to the wizard

Outputs:

  • NewInfo (CreateNewInfo) - Unknown
IncludeItem Description: Called when the appropriate New menu is being constructed.

Inputs:

  • Wizard (ItemRef) - Reference to the wizard

Outputs:

  • IncludeItem (Boolean) - Controls inclusion of the item in the New menu based on some logic
Init Description: Called to initialize the wizard.

Inputs:

  • Wizard (ItemRef) - Reference to the wizard

Outputs:

  • Enable Next (Boolean) - Controls whether the CreateNewWizard_Invoke is called or not on creating a new item.
  • Enable Finish (Boolean) - Unknown
  • Label (String) - The text that shows up in the New pop-up menu
Invoke Description: Called when an entry added to a New menu by this provider is selected.

Inputs:

  • Wizard (ItemRef) - Reference to the wizard
  • New Item Parent (mxLvNIIM) - Item Moniker representing the parent of the item to be created

Outputs:

  • Canceled (Boolean) - Controls whether the framework should create the new item (false if done through VI Server)

Global Interface Methods

Defines global-level events that are not tied into a specific object type.

Method Definition
Init Description: Called every time the provider is loaded. This happens when LabVIEW.exe runs and whenever a project explorer window is created (open, new, etc.). It should be used to construct menus and do any other initialization tasks. If licensing is not integrated, the check should be performed here (in addition to any licensing-based initialization).

Inputs:

  • Object (ItemRef) - Reference to the global item

Outputs: None

OnCommand Description: Called when executing global menu and toolbar commands. Should be used to define or call button/menu behaviors.

Inputs:

  • Item (ItemRef) - Reference to the global item
  • CommandID (String) - Menu tag of the command that was selected (defined when registered)

Outputs: None

OnUpdateCommand Description: Called during framework update operations. Building menus calls this for each customized menu item. When in the project window, this is called in a loop to make sure all the menus are in the most recent state.

Inputs:

  • Item (ItemRef) - Reference to the global item
  • Menu Item (mxLvMenuItem) - In The menu item being updated

Outputs: None

Exit Description: Not currently called.

Inputs:

  • Item (ItemRef) - Reference to the global item

Outputs: None

Item Interface Methods

Defines events that occur to individual items in the project tree.

Method Definition
CanDelete Description: Determines if the project item can be deleted

Inputs:

  • Object (ItemRef) - Reference to the project item

Outputs:

  • CanDelete (Boolean)- Controls whether the item can be deleted (true) or not (false)
CanDoHelp Description: Determines if the project item supports help.

Inputs:

  • Object (ItemRef) - Reference to the project item

Outputs:

  • CanDoHelp (Boolean) - Controls if help is supported (true) or not (false)
CanDoProperties Description: Determines if the project item supports properties.

Inputs:

  • Object (ItemRef) - Reference to the project item

Outputs:

  • Boolean CanDoProperties Controls whether properties are supported (true) or not (false)
CanDragToExternalWindow Description: Called when the project item is dragged to an external window.

Inputs:

  • Object (ItemRef) - Reference to the project item

Outputs:

  • CanDrag (Boolean) - Controls whether the item can be dragged to an external window.
CanDragToProjectWindow Description: Called when an item is dragged into the project window.

Inputs:

  • Object (ItemRef) - Reference to the project item
  • ItemRef DropTarget Reference to the item being dropped on

Outputs:

  • CanDrag (Boolean) - Controls whether DropTarget can be dragged to project window
CanDropExternalData Description: Called when an item from an external window is dragged onto this item.

Inputs:

  • Object (ItemRef) - Reference to the project item

Outputs:

  • CanDrop (Boolean) - Controls if the project item is available for dropping an external item. (Setting it to true does not drop the external item on the project item though)
CanDropItem Description: Called when another project item is dragged to the item.

Inputs:

  • Object (ItemRef) - Reference to the project item
  • DropItem - (ItemRef) - Reference to the item being dragged

Outputs:

  • CanDrop (Boolean) - Controls whether DropItem can be dropped on Object
CanRename Description: Determines if the project item can be renamed.

Inputs:

  • Object (ItemRef) - Reference to the project item

Outputs:

  • Boolean CanRename Controls whether rename is supported (true) or not (false)
Exit Description: Not currently called.

Inputs:

  • ItemRef Object Reference to the project item

Outputs: None

GetAddCategories Description: TBD

Inputs: None Outputs: None

GetCreateNewCategories Description: TBD

Inputs: None Outputs: None

Init Description: Called when initializing a single item in the project.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs: None

NotifyChanged Description: Called when the item is modified (item created or modified, file created or modified, item added or renamed, item added to or modified for SCC).

Inputs:

  • ItemRef (Object) - Reference to the project item
  • ChangeType (mxLvChangeType) - Type of change

Outputs: None

OnCommand Description: Called when a menu entry installed by the provider is selected on a single item.

Inputs:

  • ItemRef (Object) - Reference to the project item
  • CommandID (String) - Menu tag defined when the command was registered

Outputs: None

OnDblClick Description: Called when the user double-clicks on an item in the project tree.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs: None

OnDelete Description: Called when the project item is deleted.

Inputs:

  • ItemRef (Object) - Reference to the project item
  • Silently (Boolean) - Controls whether the provider's delete method should display any UI (false) or not (true)

Outputs: None

OnDoHelp Description: Called when Help... is selected from the popup menu for the project item.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs: None

OnDoProperties Description: Called when Properties is selected from the popup menu for an item.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs: None

OnDropFiles Description: Called when one or more files are dragged from the explorer and dropped on a project item.

Inputs:

  • ItemRef (Object) - Reference to the project item
  • DropFilesList (Path[]) - List of files

Outputs: None

OnDropItem Description: Called when another project item is dropped on the item.

Inputs:

  • ItemRef (Object) - Reference to the project item
  • DropItem (ItemRef) - Reference to the item being dropped

Outputs: None

OnPopupMenu Description: Called right before the project item's popup menu is displayed—menu can be modified before display.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs: None

OnRename Description: Called when the item is renamed.

Inputs:

  • ItemRef (Object) - Reference to the project item
  • New Name (String) - New name of the item.

Outputs: None

OnSelect Description: Called when the project item is selected in the project tree.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs: None

OnUnselect Description: Called when the project item is unselected in the project tree.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs: None

OnUpdateCommand Description: Called to update the specified command right before it is about to be displayed in a menu or popup.

Inputs:

  • ItemRef (Object) - Reference to the project item
  • Command ID (String) - Menu tag of the command being updated (defined when registered)

Outputs:

  • Menu Item Out (mxLvMenuItem)
OnWizardComplete Description: Notifies the project item that the Create New Wizard process is finished.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs: None

PrefersFPHeap Description: Determines if item wants the VI Front Panel or Block Diagram reference when WasDroppedOnVI is called.

Inputs:

  • ItemRef (Object) - Reference to the project item

Outputs:

  • Prefers FP (Boolean) - True if Front Panel reference, false if Block Diagram reference
ValidateRename Description: Determines if the new name is valid for the project item.

Inputs:

  • ItemRef (Object) - Reference to the project item
  • New Name (String) - New name of item

Outputs:

  • Can Rename (Boolean) - Controls whether the new name is valid (true) or not (false)
WasDroppedOnItem Description: Called when the project item was dropped on another project item in the tree.

Inputs:

  • ItemRef (Object) - Reference to the project item
  • Drop Item (ItemRef) - The item that the project item was dropped on

Outputs: None

WasDroppedOnVI Description: Called when the project item is dropped on an open VI (either front panel or block diagram).

Inputs:

  • ItemRef (Object) - Reference to the project item
  • X (I32) - X-coordinate of drop
  • Y (I32) - Y-coordinate of drop
  • VI (Diagram Refnum) - Front panel or Block Diagram reference (determined by PrefersFPHeap method)
  • Front Panel? (Boolean) - Specifies whether item has been dropped on Front Panel (true) or not (false)
  • Flags (I32) - NOTE: REFER TO _lvProjectDragDropFlags IN LvProject.h

Outputs:

  • Can Drop (Boolean) - Controls whether object can be dropped or not
  • Result (lvProjectDropresults) - NOTE: REFER TO lvProjectDropResults IN LvProject.h

ProjectDeployItem Interface Methods

Defines events that support deploying of an item in the project tree.

Methods need definitions
Method Definition
GetSupportedCommands
GetDeployState
NotifyCommandCompleted

Provider Interface Methods

Defines events that occur to multiple items in the project tree.

Key Description / Inputs / Outputs
InitItems Description: Called when multiple items in the project are bound.

Inputs:

  • Items Array (ItemRef[]) - Array of references to project items

Outputs: None

LoadComplete Description: Called when the project has finished loading.

Inputs:

  • Project (ItemRef) - Reference to the project

Outputs: None

LoadCompleteWithWarnings Description: Same as LoadComplete except save warnings are optionally returned.

Inputs:

  • Project (ItemRef) - Reference to the project

Outputs:

  • warnSummaryStrings (String[]) - Warning summary messages
  • warnStrings (String[]) - Warning messages
NotifyChanged Description: Called when changes occur involving multiple items (create, add, etc.)

Inputs:

  • item IDs (ItemRef[])
  • Change Type (mxLvChangeType)
  • error in (Error Cluster) - Input error cluster

Outputs:

  • error out (Error Cluster) - Output error cluster
OnCommand Description: Called when a command is invoked on multiple items (menu or toolbar).

Inputs:

  • Items Array (ItemRef[])
  • Command ID (String) - Menu tag defined when command was registered

Outputs: None

OnPopupMenu Description: Called right before the project items' popup menu is displayed—can modify menu.

Inputs:

  • objects (ItemRef[]) - References to the selected items

Outputs: None

OnSaveForPrevious Description: Called when a project is being saved to a previous version—gives provider a chance to modify property bag to match the previous version.

Inputs:

  • Version (U32) - Version number that is being saved for
  • ObjectsIn (ItemRef[]) - References to items being saved

Outputs: None

OnSaveForPreviousEx Description: Same as OnSaveForPrevious except the provider is also passed to the method.

Inputs:

  • Version (U32) - Version number that is being saved for
  • ObjectsIn (ItemRef[]) - References to items being saved
  • Provider Item (ItemRef) - Reference to this provider

Outputs: None

OnSaveForPreviousWithWarnings Description: Same as OnSaveForPreviousEx except save warnings are optionally returned.

Inputs:

  • Version (U32) - Version number being saved for
  • ObjectsIn (ItemRef[]) - References to items being saved
  • Provider Item (ItemRef) - Reference to this provider

Outputs:

  • Warning Summaries (String[]) - Warning summary messages
  • Warnings (String[]) - Warning messages
OnSaveProject Description: Called when the project is being saved.

Inputs:

  • Project (ItemRef) - Reference to the project

Outputs: None

OnUpdateCommandBegin Description: Called before UpdateCommand is called for each command in the toolbar or menu.

Inputs:

  • Project (ItemRef) - Reference to the project

Outputs: None

OnUpdateCommandEnd Description: Called after UpdateCommand is called for each command in the toolbar or menu.

Inputs:

  • Project (ItemRef) - Reference to the project

Outputs: None

Shutdown Description: Called when the project shuts down.

Inputs:

  • Project (ItemRef) - Reference to the project
  • Is LV Exiting? (Boolean) - Specifies whether LabVIEW is exiting (true) or not (false)

Outputs: None

Startup Description: Called when the project is created.

Inputs:

  • Project (ItemRef) - Reference to the project

Outputs: None

SourceControl Interface Methods

Defines events that apply to source code control functionality.

Methods need definitions
Method Definition
GetRequiredFiles
GetDependents
GetCallers

Documentation and Examples

See also

Retrieved from "https://labviewwiki.org/w/index.php?title=Project_Provider_Framework&oldid=32407"