This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies.
The SmartPart QuickStart shows you how to use SmartParts, workspaces, and WorkItems. In particular, it shows how to build SmartParts and structure them in a parent-child WorkItem relationship.
To run the SmartPart QuickStart
- Open the SmartPart QuickStartsolution in Visual Studio 2008.
- On the Build menu, click Rebuild Solution.
- Click the Start Debugging button on the standard toolbar, or click Start Debugging on the Debug menu.
This example is a simple application for displaying details of customers. The customer details are hard-coded into the application in this example, but otherwise it demonstrates how you can create attractive and interactive user interfaces for common tasks such as this. Figure 1 shows the application after you have selected a customer in the list on the left.
Selecting a customer to show the Details and Summary SmartParts
The shell form (the main window) contains a DeckWorkspace. As the application runs, it loads a SmartPart named CustomerMain into this workspace. The CustomerMainSmartPart contains a standard Windows Forms SplitContainer control, which itself contains a CustomerListViewSmartPart in the left panel and a DeckWorkspace in the right panel.
When you select a customer, the application loads a SmartPart called CustomerTabView into the DeckWorkspace in the right panel. The CustomerTabView SmartPart contains a TabWorkspace control, which itself contains an instance of the CustomerDetailViewSmartPart on the first tab, and a SmartPartPlaceholder that is populated by an instance of the CustomerSummaryViewSmartPart on the second tab. Figure 2 shows a graphical representation of the hierarchy of controls and SmartParts on the main form.
The overall structure of the Form, controls and SmartParts
When you click the Comments button in the CustomerDetailViewSmartPart, the application loads an instance of the CustomerCommentsViewSmartPart into the TabWorkspace as well, so that it now shows three SmartParts—as you can see in the hierarchical view in Figure 2. Meanwhile, Figure 3 shows what the application window looks like after loading the Comments view.
The CustomerCommentsView SmartPart
What You Need to Know
To understand this example, you should be familiar with the following:
- The Model View Controller design pattern
- The basic principles of the design of the Composite UI Application Block framework
- Creating Windows Forms user controls to implement SmartParts
- The types of controls used to display SmartParts
- The terms listed in the Glossary of Terms section
Design of the SmartPart QuickStart
The following steps describe the startup sequence of the example:
- The shell application defined in SmartPartApplication.cs inherits from FormShellApplication. It specifies the custom BrowseCustomersWorkItem class as its root WorkItem, and MainForm as the form to show when the application starts.
- The Main method in the SmartPartApplication.cs application shell file creates an instance of the SmartPartApplicationshell class and calls its Run method.
- In SmartPartApplication.cs, code over-rides the BeforeShellCreated method to load the State for the application (a list of customers) within the BrowseCustomersWorkItem.
- The Composite UI Application Block initialization process calls the Run method of the root WorkItem (BrowseCustomersWorkItem in this example). The WorkItem overrides the OnRunStarted method. In this method, it gets a reference to the MainFormWorkspace, which is a DeckWorkspace located on the MainForm shell form, and loads the CustomerMainSmartPart into it.
- The CustomerMainSmartPart contains a SplitContainer control, with the CustomerListViewSmartPart in the left panel and a DeckWorkspace control in the right panel.
- The CustomerListViewSmartPart is an implementation of the TitledSmartPart user control class that contains a Label as the title and exposes this title, and a ToolTip for it, as properties. The CustomerListViewSmartPart just adds a ListBox to the TitledSmartPart where customer names will display.
- The class implementing the CustomerMainSmartPart is decorated with the [SmartPart] attribute, which automatically adds this view to the WorkItem. It also implements the IWorkSpace interface, and so is itself a workspace as well as a SmartPart.
- The CustomerListViewSmartPart is loaded with the CustomerMainSmartPart. It uses dependency injection through the [CreateNew] attribute to create an instance of the CustomersController class.
- The CustomersController gets a reference to the customer list that is stored in state by decorating the customers property with the [State("Customers")] attribute.
- The CustomersController is also dependent on the root WorkItem named BrowseCustomersWorkItem, and gets a reference to this using the [ServiceDependency] attribute and specifying the WorkItem type.
- Code in the OnLoad event handler of the CustomerListViewSmartPart now calls the PopulateCustomersData method of the CustomersController, which adds the list of customers to the State held in the WorkItem, and then uses this list to populate the ListBox and display the customer's name in the Label control. It also registers a handler for the SelectedIndexChanged event of the ListBox.
The following steps describe what happens when you select a customer in the ListBox:
- Selecting a customer in the ListBox of the CustomerListViewSmartPart executes the event handler customerListBox_SelectedIndexChanged, which calls the ShowCustomerDetails method of the CustomersController, passing to it the selected customer's name as a Customer object.
- The ShowCustomerDetails method of the CustomersController calls the ShowCustomerDetails method of the BrowseCustomersWorkItem.
- TheShowCustomerDetails method of the BrowseCustomersWorkItem stores the specified customer in the State and creates a key based on the ID of the customer. Then it tries to get a reference to the ViewCustomerWorkItem instance for this customer using the Get method of the Items collection of the WorkItem.
- If an existing ViewCustomerWorkItem is not available for this customer (meaning that this customer is being selected for the first time), the ShowCustomerDetails method creates a new child ViewCustomerWorkItem named using the key created in Step 3, and injects the state for this customer into it.
- After a ViewCustomerWorkItem is available, the ShowCustomerDetails method calls its Run method, passing to it the DeckWorkspace on the right side of the main form.
- The Run method of theViewCustomerWorkItem creates (if not already created) a new CustomerSummaryViewSmartPart instance, which is another implementation of the TitledSmartPart (and so contains a Label as the title). It also has a TextBox to display the customer summary information.
- The Run method next creates a new CustomerTabView instance, which consists of a TabWorkspace containing a CustomerDetailView and a SmartPartPlaceholder. Then it displays the CustomerTabView in the DeckWorkspace passed to it by the ShowCustomerDetails method by calling the Show method of the DeckWorkspace.
- The CustomerDetailViewSmartPart is another implementation of TitledSmartPart, but this time containing some text boxes and a Comments button. Like the CustomerListViewSmartPart it uses dependency injection through the [CreateNew] attribute to create an instance of its controller—however, in this case, it is the CustomerController class (note the missing "s"). It also references the selected customer using the [State("Customer")] attribute (again, note the missing "s").
- Code in the OnLoad method of the CustomerDetailView displays the customer information in the TextBox controls when the SmartPart loads.
The following steps describe what happens when you click the Comments button in the CustomerDetailView SmartPart:
- Clicking the Comments button in the CustomerDetailView SmartPart executes the commentsButton_Click event handler, which calls the ShowCustomerComments method of the CustomerController.
- The CustomerController is dependent on the child WorkItem named ViewCustomersWorkItem, and gets a reference to this using the [ServiceDependency] attribute. By including the property Type=typeof(WorkItem) in the attribute, ObjectBuilder gets a reference to the WorkItem within which the controller is located.
- The ShowCustomerComments method of the CustomerController can then call the ShowCustomerComments method of the ViewCustomerWorkItem.
- The ShowCustomerComments method of the ViewCustomerWorkItem gets a reference to the TabWorkspace control and checks if the CustomerCommentsViewSmartPart is available. If not, it creates a new instance of the CustomerCommentsViewSmartPart and a new SmartPartInfo instance, sets the Title property of this SmartPartInfo instance, and registers the CustomerCommentsViewSmartPart and the SmartPartInfo with the WorkItem. The CustomerCommentsViewSmartPart is another implementation of the TitledSmartPart class that exposes the Title property, and so this sets the title of the SmartPart.
- The final line of code in the ShowCustomerComments method calls the Show method of the TabWorkspace to display the CustomerCommentsViewSmartPart as a separate tabbed page.
- Code in the OnLoad event handler of the CustomerCommentsView collects the customer details from the state and displays the information in the TextBox when the SmartPart loads.
Reviewing the SmartPart QuickStart
The following procedure describes how to review the execution of the SmartPart QuickStart.
To review the SmartPart QuickStart
- Open the SmartPart QuickStartsolution in Visual Studio 2008.
- On the Build menu, click Rebuild Solution.
- Insert breakpoints on the following lines of code:
The first line of the Main method in SmartPartApplication.cs
The first line of the customerListBox_SelectedIndexChanged method in CustomerListView.cs
The first line of the commentsButton_Click method in CustomerDetailView.cs
- On the Debug menu, click Start Debugging.
- When the debugger enters break mode, step through the code until you reach the Run method of the file CabApplication.cs. As you step through this method, pay particular attention to:
The initialization sequence of the application
The services added during initialization
The display of the SmartParts on the Form and in the Workspace.
- After the main form loads, select a customer in the list. Notice how the code in the controller calls a method in the WorkItem to create a new WorkItem to display the selected customer's details.
- Select the same customer in the list. Notice how this time an existing WorkItem is retrieved to display the selected customer's details.
- Click Comments. Notice how the code in the controller calls a method in the WorkItem to create a new viewdisplayed in the TabWorkspace for that customer.