Adding a Shell Command to the Application Toolbar

2012-05-31

This lesson shows how to add a command to the application toolbar and write code that executes when the command is clicked at run time. The command executes a parameterized query and displays the results on a search screen.

Adding a Shell Command

In the previous lesson add a command that appears on the command bar of a screen. You could also program a toolbar button to accomplish other tasks, for example, open another screen, apply a filter on data, or even send an email.

To add a parameterized query

In Solution Explorer, select the Customers node.
On the Project menu, click Add Query.
In the Properties window, in the Name field, type MatchCustomer.
In the Query Designer, click Add Filter.
In the second drop-down list, select ContactName.
In the fourth drop-down list, select Parameter.
In the final drop-down list, click Add New.

A new parameter, named ContactName, of type String is added to the Parameters section of the Query Editor.

To add a search screen

On the toolbar, click the Add Screen button.
In the Add New Screen dialog box, in the Select a screen template list, select Search Data Screen.
In the Screen Name field, type SearchCustomer.
In the Screen Data list, select – MatchCustomer and then click OK.
In the Screen Designer, select the CustomerContactName node.
In the Properties window, select the Is Parameter property.

In Solution Explorer, double-click ContactList.
In the Screen Designer, expand the Screen Command Bar node.
In the Add list, select New Button.

The Add Button dialog box appears.
In the Add Button dialog box, select New Method and type Find in the Name box, and then click OK.
In the Properties window, select Description and type Find the selected contact in the customer list..
Click the Choose Image link.
In the Select Image dialog box, click Import.
In the Open dialog box, navigate to a directory that contains pictures, select a picture, and then click Open.
Click OK to close the Select Image dialog box.
In the left pane, select Find.
In the Properties window, click Edit Execute Code.

The Code Editor appears and displays the Find_Execute() method.
In the Find_Execute() method, add the following code.
```
Application.ShowSearchCustomer(Contacts.SelectedItem.ContactName)
```
```
Application.ShowSearchCustomer(Contacts.SelectedItem.ContactName);
```
This code displays the ShowSearchCustomer screen when a user clicks the button that you just created.
Press F5 to run the application.

Verify the new command by selecting Howard Snyder in the Contacts list and then clicking the Find button.

The SearchCustomer screen should appear and should display the data for Great Lakes Food Market. When you click Great Lakes Food Market in the Company column, a Customer Details screen should appear.

Closer Look

This lesson showed how to create a parameterized query to return Customers that match a ContactName parameter, and how to create a search screen based on the query. You may have noticed that the SearchCustomer screen does not appear on the Navigation Menu in the running application. Screens based on parameterized queries can only be opened by executing a command and cannot be added to the menu.

The lesson then showed how to add a command to the ContactList screen, give it a Display Name, Description, and Image, and add the code that runs every time that the command button is clicked. The code executes the ShowSearchCustomer method, which displays the SearchCustomer screen. The code enclosed in parentheses is the parameter to the method, in this case the ContactName for the selected item in the Contacts collection.

You may have noticed that the command only appears on the application toolbar when the Contact List screen is selected. Because commands that are added to the toolbar are screen-specific, you must create a separate command for each screen.

Next Steps

In the next lesson, you will learn how to add an item to the navigation menu.

Next lesson: Customizing Menu Items

Share via

Adding a Shell Command to the Application Toolbar