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 Contact History list:

ACTION_UPDATECONTACT: 1

ACTION_EDITCUSTOMER: 2

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 Contact History list:

• EditCustomer
• UpdateContact
• CL_ActionsGroup
• CL_GoToGroup
• CL_ReportsGroup

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 EditCustomer command.

call ExecuteListAction of form syTrxList, ACTION_EDITCUSTOMER;

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 for the Contact History list creates four 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.

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 CmdSequence nSeq, nGroupSeq;

nGroupSeq = 0;

{ Actions group }
increment nGroupSeq;
nCmdDictID = IG_PROD_ID;
nCmdFormID = resourceid(form ListObj_ContactHistoryTrx);
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_ContactHistoryTrx);

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

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


{ Restrictions group }
increment nGroupSeq;
call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_TRX, 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;

	{ Date Restriction }
	increment nSeq;
	call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_TRX, LISTACTION_DATERESTRICT, 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;

	{ Include/Exclude Active Customers Restriction }
	increment nSeq;
	call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_TRX, 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_ContactHistoryTrx);
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_TRX, 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_ContactHistoryTrx);
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;

	{ Send To Excel }
	increment nSeq;
	call List_GetIDsForCoreCommand of form syListObj, LISTTYPE_TRX, 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_TRX, 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_TRX, 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 Contact History list.

inout ListObjState list_object;

{ Actions }
List_RegisterGroup(list_object, command CL_ActionsGroup) of form syListObj;
List_RegisterAction(list_object, command UpdateContact, LISTCMDTYPE_SINGLESELECT, ACTION_UPDATECONTACT) of form syListObj;
List_RegisterAction(list_object, command EditCustomer, LISTCMDTYPE_SINGLESELECT, ACTION_EDITCUSTOMER) 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;

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 Update Contact action can be performed when a single item is marked in the list. This action would be active as long as the user has marked exactly one item.

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:

The following is the CheckActionAccessForRecord procedure for the Contact History list. By default, the marking or unmarking actions are considered neutral. The Update Contact and Edit Customer 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 EditCustomer) then
	nAccessStatus = LISTACTIONACCESS_COUNT_FOR;
elseif nActionCmdTag = Command_GetTag(command UpdateContact) then
	nAccessStatus = LISTACTIONACCESS_COUNT_FOR;
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 Contact History 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_EDITCUSTOMER, DEFAULT_ACTION]
		open form RM_Customer_Maintenance;
		'Customer Number' of window RM_Customer_Maintenance of form
		RM_Customer_Maintenance = 'Customer Number' of table (list_object:'Table Reference');
		run script 'Customer Number' of window RM_Customer_Maintenance of form RM_Customer_Maintenance;
	in [ACTION_UPDATECONTACT]
		open form RM_Customer_Maintenance;
		'Customer Number' of window RM_Customer_Maintenance of form RM_Customer_Maintenance = 'Customer Number' of table (list_object:'Table Reference');
		run script 'Customer Number' of window RM_Customer_Maintenance of form RM_Customer_Maintenance;

		open form IG_Contact_History;
		'Customer Number' of window 'Contact History' of form IG_Contact_History = 'Customer Number' of table (list_object:'Table Reference');
		run script 'Customer Number' of window 'Contact History' of form IG_Contact_History;
end case;

Documentation Feedback

---