Action Pane

The Action Pane allows the user to perform actions on the items selected in the list. Adding groups and actions to the Action Pane is a multi-step process. You begin by defining constants for the actions that you want to add to the Action Pane. For instance, the following constants were defined for the Leads list:

ACTION_NEWLEAD: 1

ACTION_EDITLEAD: 2

ACTION_VIEWLEAD: 3

ACTION_DELETELEAD: 4

ACTION_QUALIFYLEAD: 5

 

The next step involves creating commands for each action and command lists for each group that will appear in the Action Pane. The commands will contain the code that performs the actions. Refer to Commands for the Action Pane for details about creating these commands. Continuing the example, the following commands and command lists are defined for the Leads list:

 

The script for each command contains code the will execute the action the user has chosen. For example, the following is the script defined for the EditLead command.

call ExecuteListAction of form syCardList, ACTION_EDITLEAD;

In some cases, you may want to have the user verify the action before it is performed. You can learn more about this in Verifying an action.

Use the CreateListRibbonData procedure to add groups and actions to the Action Pane for the list you are creating. You will use the functions AddGroup() and AddCommand() from the syListViewCmdBarObj form to add the groups and the actions for each group.

The CreateListRibbonData procedure runs only when no Action Pane items exist for the list. If you need to add additional items after the initial Action Pane items have been created, use the technique described in Adding to the Action Pane.


The CreateListRibbonData procedure for the Leads list creates six groups and adds the commands to those groups. It also adds the two user-defined groups, which by default are not visible. The user can add additional commands to these groups when they customize the Action Pane for the list.

[spacer]

The following is the complete CreateListRibbonData procedure.

in ListDictID nListDictID;
in ListID nListID;

local CmdDictID nCmdDictID, nParentDictID;
local CmdFormID nCmdFormID, nParentFormID;
local CmdID nCmdID, nParentCmdID;
local integer nStatus;
local CmdSequencenSeq, nGroupSeq;

nGroupSeq = 0;

{ Actions group }
increment nGroupSeq;
nCmdDictID = IG_PROD_ID;
nCmdFormID = resourceid(form ListObj_Leads);
nCmdID = resourceid(command CL_ActionsGroup);
nStatus = AddGroup(nListDictID, nListID, LIST_PRIMARYVIEWID, nGroupSeq,
		nCmdDictID, nCmdFormID, nCmdID, 
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

	{--- add default commands to the Actions group ---}
	nSeq = 0;

	nParentDictID = nCmdDictID;
	nParentFormID = nCmdFormID;
	nParentCmdID = nCmdID;

	nCmdDictID = IG_PROD_ID;
	nCmdFormID = resourceid(form ListObj_Leads);

	{ Qualify Lead }
	increment nSeq;
	nStatus = AddCommand(nListDictID, nListID, LIST_PRIMARYVIEWID, 
		nParentDictID, nParentFormID, nParentCmdID,
		nSeq, 
		nCmdDictID, nCmdFormID, resourceid(command QualifyLead), 
		LISTACTIONPRIORITY_PRIMARY,
		LISTACTIONBTNSIZE_LARGE,
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

{ Modify group }
increment nGroupSeq;
nCmdDictID = IG_PROD_ID;
nCmdFormID = resourceid(form ListObj_Leads);
nCmdID = resourceid(command CL_ModifyGroup);
nStatus = AddGroup(nListDictID, nListID, LIST_PRIMARYVIEWID, nGroupSeq,
		nCmdDictID, nCmdFormID, nCmdID, 
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

	{--- add default commands to the Modify group ---}
	nSeq = 0;

	nParentDictID = nCmdDictID;
	nParentFormID = nCmdFormID;
	nParentCmdID = nCmdID;

	nCmdDictID = IG_PROD_ID;
	nCmdFormID = resourceid(form ListObj_Leads);

	{ Edit Lead }
	increment nSeq;
	nStatus = AddCommand(nListDictID, nListID, LIST_PRIMARYVIEWID,
		nParentDictID, nParentFormID, nParentCmdID,
		nSeq, 
		nCmdDictID, nCmdFormID, resourceid(command EditLead),
		LISTACTIONPRIORITY_PRIMARY,
		LISTACTIONBTNSIZE_LARGE,
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

	{ Delete Lead }
	increment nSeq;
	nStatus = AddCommand(nListDictID, nListID, LIST_PRIMARYVIEWID, 
		nParentDictID, nParentFormID, nParentCmdID,
		nSeq,
		nCmdDictID, nCmdFormID, resourceid(command DeleteLead), 
		LISTACTIONPRIORITY_PRIMARY,
		LISTACTIONBTNSIZE_LARGE,
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

{ New group }
increment nGroupSeq;
nCmdID = resourceid(command CL_NewGroup);
nStatus = AddGroup(nListDictID, nListID, LIST_PRIMARYVIEWID, nGroupSeq, 
					nCmdDictID, nCmdFormID, nCmdID, 
					""{caption}, 
					true{visible}) of form syListViewCmdBarObj;
				
				
	{--- add default commands to the New group ---}
	nSeq = 0;

	nParentDictID = nCmdDictID;
	nParentFormID = nCmdFormID;
	nParentCmdID = nCmdID;

	nCmdDictID = IG_PROD_ID;
	nCmdFormID = resourceid(form ListObj_Leads);

	{ New Lead }
	increment nSeq;
	nStatus = AddCommand(nListDictID, nListID, LIST_PRIMARYVIEWID, 
		nParentDictID, nParentFormID, nParentCmdID,
		nSeq,
		nCmdDictID, nCmdFormID, resourceid(command NewLead), 
		LISTACTIONPRIORITY_PRIMARY,
		LISTACTIONBTNSIZE_LARGE,
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;
		
{ Restrictions group }
increment nGroupSeq;
call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_CARD, LISTRIBBONGROUP_RESTRICT, nCmdDictID, nCmdFormID, nCmdID;
nStatus = AddGroup(nListDictID, nListID, LIST_PRIMARYVIEWID, nGroupSeq,
		nCmdDictID, nCmdFormID, nCmdID, 
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

	{--- add default commands to the Restrictions group ---}
	nSeq = 0;

	nParentDictID = nCmdDictID;
	nParentFormID = nCmdFormID;
	nParentCmdID = nCmdID;

	{ Include/Exclude Qualified Restriction }
	increment nSeq;
	call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_CARD, LISTACTION_LISTRESTRICT, nCmdDictID, nCmdFormID, nCmdID;
	nStatus = AddCommand(nListDictID, nListID, LIST_PRIMARYVIEWID, 
		nParentDictID, nParentFormID, nParentCmdID,
		nSeq,
		nCmdDictID, nCmdFormID, nCmdID, 
		LISTACTIONPRIORITY_PRIMARY,
		LISTACTIONBTNSIZE_LARGE,
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;
						
{ Reports group }
increment nGroupSeq;
nCmdDictID = IG_PROD_ID;
nCmdFormID = resourceid(form ListObj_Leads);
nCmdID = resourceid(command CL_ReportsGroup);

nStatus = AddGroup(nListDictID, nListID, LIST_PRIMARYVIEWID, nGroupSeq,
	nCmdDictID, nCmdFormID, nCmdID, 
	""{caption}, 
	true{visible}) of form syListViewCmdBarObj;

	{--- add default commands to the Reports group ---}
	nSeq = 0;

	nParentDictID = nCmdDictID;
	nParentFormID = nCmdFormID;
	nParentCmdID = nCmdID;

	{ Print This List }
	increment nSeq;
	call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_CARD, LISTACTION_PRINTLIST, nCmdDictID, nCmdFormID, nCmdID;
	nStatus = AddCommand(nListDictID, nListID, LIST_PRIMARYVIEWID, 
		nParentDictID, nParentFormID, nParentCmdID,
		nSeq, 
		nCmdDictID, nCmdFormID, nCmdID,
		LISTACTIONPRIORITY_PRIMARY,
		LISTACTIONBTNSIZE_LARGE,
		""{caption},
		true{visible}) of form syListViewCmdBarObj;

{ Go To group }
increment nGroupSeq;
nCmdDictID = IG_PROD_ID;
nCmdFormID = resourceid(form ListObj_Leads);
nCmdID = resourceid(command CL_GoToGroup);
nStatus = AddGroup(nListDictID, nListID, LIST_PRIMARYVIEWID, nGroupSeq,
		nCmdDictID, nCmdFormID, nCmdID, 
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

	nSeq = 0;

	nParentDictID = nCmdDictID;
	nParentFormID = nCmdFormID;
	nParentCmdID = nCmdID;

	{ View Lead }
	increment nSeq;
	nStatus = AddCommand(nListDictID, nListID, LIST_PRIMARYVIEWID,
		nParentDictID, nParentFormID, nParentCmdID,
		nSeq, 
		nCmdDictID, nCmdFormID, resourceid(command ViewLead), 
		LISTACTIONPRIORITY_PRIMARY,
		LISTACTIONBTNSIZE_LARGE,
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

	{ Send To Excel }
	increment nSeq;
	call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_CARD, LISTACTION_EXPORTTOEXCEL, nCmdDictID, nCmdFormID, nCmdID;
	nStatus = AddCommand(nListDictID, nListID, LIST_PRIMARYVIEWID, 
		nParentDictID, nParentFormID, nParentCmdID,
		nSeq,
		nCmdDictID, nCmdFormID, nCmdID, 
		LISTACTIONPRIORITY_PRIMARY,
		LISTACTIONBTNSIZE_LARGE,
		""{caption}, 
		true{visible}) of form syListViewCmdBarObj;

{ User Defined Group 1 }
increment nGroupSeq;
call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_CARD, LISTRIBBONGROUP_USERDEF1, nCmdDictID, nCmdFormID, nCmdID;
nStatus = AddGroup(nListDictID, nListID, LIST_PRIMARYVIEWID, nGroupSeq,
	nCmdDictID, nCmdFormID, nCmdID,
	""{caption},
	false{visible}) of form syListViewCmdBarObj;

{ User Defined Group 2 }
increment nGroupSeq;
call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_CARD, LISTRIBBONGROUP_USERDEF2, nCmdDictID, nCmdFormID, nCmdID;
nStatus = AddGroup(nListDictID, nListID, LIST_PRIMARYVIEWID, nGroupSeq, 
	nCmdDictID, nCmdFormID, nCmdID,
	""{caption}, 
	false{visible}) of form syListViewCmdBarObj;

To control access for the commands added to the Action Pane, the actions must be registered. The RegisterCommands procedure for the list performs this action. In this procedure, you will use the List_RegisterGroup() and List_RegisterAction() functions of the syListObj form to register each item you added to the Action Pane. The following is the RegisterCommands procedure for the Leads list.

inout ListObjState list_object;

{ Actions }
List_RegisterGroup(list_object, command CL_ActionsGroup) of form syListObj;
List_RegisterAction(list_object, command QualifyLead, LISTCMDTYPE_MULTISELECT, ACTION_QUALIFYLEAD) of form syListObj;

{ Modify }
List_RegisterGroup(list_object, command CL_ModifyGroup) of form syListObj;
List_RegisterAction(list_object, command EditLead, LISTCMDTYPE_SINGLESELECT, ACTION_EDITLEAD) of form syListObj;
List_RegisterAction(list_object, command DeleteLead, LISTCMDTYPE_MULTISELECT, ACTION_DELETELEAD) of form syListObj;

{ New }
List_RegisterGroup(list_object, command CL_NewGroup) of form syListObj;
List_RegisterAction(list_object, command NewLead, LISTCMDTYPE_ALWAYSAVAILABLE, ACTION_NEWLEAD) of form syListObj;

{ Reports }
List_RegisterGroup(list_object, command CL_ReportsGroup) of form syListObj;

{ Go To }
List_RegisterGroup(list_object, command CL_GoToGroup) of form syListObj;
List_RegisterAction(list_object, command ViewLead, LISTCMDTYPE_SINGLESELECT, ACTION_VIEWLEAD) of form syListObj;

The actions in the Action Pane are enabled or disabled automatically, based on the number and specific type of lines the user has marked in the list. Microsoft Dynamics GP tracks two counts for every action in the Action Pane. The “count for” counter tracks the number of items marked to determine whether the single-select or multi-select actions should be enabled. The “count against” counter tracks the number items marked that would prevent an action from being enabled. If there are any “count against” lines marked, the action will be disabled.

For example, assume that the Qualify action can be performed for the items selected in the list. This action would be active as long as the user has marked one or more items to qualify. However, if the user marked an item that had already been qualified, the “counts against” counter would be incremented, causing the Qualify action to be disabled.

The CheckActionAccessForRecord procedure is called multiple times when the user marks or unmarks an item in the list. The procedure has the following parameters:

in ListObjState list_object;
in integer nActionCmdTag;
out integer nAccessStatus;

Each time the procedure is called, a command tag is passed in. The procedure specifies how the item marked or unarked in the list should be considered when determining whether the action corresponding to that tag should be accessible. You will use the 'Table Reference' component of the list object composite passed into the procedure to determine which row is being marked or unmarked in the list.

The parameter value returned through the “out” parameter this trigger processing procedure specifies how the marked row should be considered. The value corresponds to one of the following constants:

[spacer]

Constant

Description

LISTACTIONACCESS_COUNT_NEUTRAL

The marked row won’t affect the count for the action.

LISTACTIONACCESS_COUNT_FOR

The marked row will increase or decrease the “count for” counter by one.

LISTACTIONACCESS_COUNT_AGAINST

The marked row will increase or decrease the “count against” counter by one.


The following is the CheckActionAccessForRecord procedure for the Leads list. By default, the marking or unmarking actions are considered neutral. The Delete, Edit, View, and Qualify actions have specific conditions for which they will be enabled or disabled.

in ListObjState list_object;
in integer nActionCmdTag;
out integer nAccessStatus;

nAccessStatus = LISTACTIONACCESS_COUNT_NEUTRAL;

if nActionCmdTag = Command_GetTag(command DeleteLead) then
	nAccessStatus = LISTACTIONACCESS_COUNT_FOR;
elseif nActionCmdTag = Command_GetTag(command EditLead) then
	nAccessStatus = LISTACTIONACCESS_COUNT_FOR;
elseif nActionCmdTag = Command_GetTag(command ViewLead) then
	nAccessStatus = LISTACTIONACCESS_COUNT_FOR;
elseif nActionCmdTag = Command_GetTag(command QualifyLead) then
	{Examine whether the lead is already qualified}
	if 'Qualified Lead' of table (list_object:'Table Reference') = 1 then
		{Lead has not been qualifed}
		nAccessStatus = LISTACTIONACCESS_COUNT_FOR;
	else
		{Lead has already been qualified, so disable that action}
		nAccessStatus = LISTACTIONACCESS_COUNT_AGAINST;
	end if;
end if;

To execute the actions you have defined for your list, you will add the ExecuteAction procedure. This procedure is called every time a user chooses an action for the list. The value corresponding to the action is also passed into the procedure. The procedure must contain the code to perform the action the user chose.

The ExecuteAction script must also handle the default action for the list window. The default action occurs when the user presses the Enter key or double-clicks on a line in the list. The value corresponding to the constant DEFAULT_ACTION indicates the default action.

Executing an action for a list can be an involved process, since the action can be performed for multiple items marked in the list. Refer to Performing actions for marked rows for details about processing actions for multiple items.

The ExecuteAction procedure must also be able to handle any errors that occur during action processing. Refer to Logging action status and Acting on action errors for detailed information about how to log and act on errors encountered as actions are processed.

The following is the ExecuteAction script for the Leads list in the sample integrating application. Notice that the list object is passed into the procedure. The reference to the main table contained in this object is used to find what row the user had marked in the list for the single-select actions.

inout ListObjState list_object;
in long iAction;

case iAction
	in [ACTION_NEWLEAD] 
		open form IG_Lead_Maintenance;
	in [ACTION_EDITLEAD]
		open form IG_Lead_Maintenance;
		'Lead ID' of window 'Lead Maintenance' of form IG_Lead_Maintenance = 'Lead ID' of table (list_object:'Table Reference');
		run script 'Lead ID' of window 'Lead Maintenance' of form IG_Lead_Maintenance;
	in [ACTION_DELETELEAD]
		call DeleteLeads of form ListObj_Leads, list_object;
	in [ACTION_VIEWLEAD]
		open form IG_Lead_Inquiry;
		'Lead ID' of window IG_Lead_Inquiry of form IG_Lead_Inquiry = 'Lead ID' of table (list_object:'Table Reference');
		run script 'Lead ID' of window IG_Lead_Inquiry of form IG_Lead_Inquiry;
	in [ACTION_QUALIFYLEAD]
		call QualifyLeads of form ListObj_Leads, list_object;
	in [DEFAULT_ACTION]
		open form IG_Lead_Maintenance;
		'Lead ID' of window 'Lead Maintenance' of form IG_Lead_Maintenance = 'Lead ID' of table (list_object:'Table Reference');
		run script 'Lead ID' of window 'Lead Maintenance' of form IG_Lead_Maintenance;
end case;


Documentation Feedback