Displaying Custom Text and Information

The first part of the Statistics section shows the number of overdue cases. The technique you use to add custom text to a screen relies on local string properties, and you’ll now find out how to create these.

To create a string property that shows overdue issues, create a details screen that’s based on the Engineer entity and name your screen EngineerDashboard. Click the Add Data Item button, and add a new string property called IssuesOverdueLabel (as shown in Figure 7-2).

You can then set the text of this property by writing code in the InitializeDataWorkspace method. (See Listing 7-1.) This code uses the outstandingIssues query from Chapter 6 to return the issue count.

Listing 7-1.  Building Text to Display on a Screen

VB:
File:HelpDeskVBClientUserCodeEngineerDashboard.vb
  
IssuesOverdueLabel = String.Format(
    "You have {0} issues overdue",
    outstandingIssues.Where(
        Function(item) item.TargetEndDateTime < Date.Today).
           Count().ToString()
)
  
C#:
File:HelpDeskCSClientUserCodeEngineerDashboard.cs
  
IssuesOverdueLabel = String.Format(
    "You have {0} issues overdue",
    outstandingIssues.Where(
        item => item.TargetEndDateTime < Date.Today).
           Count().ToString()
);

To display this text on your screen, simply drag the IssuesOverdueLabel property from the Screen Member list onto your Screen Content Tree. By default, LightSwitch renders IssuesOverdueLabel as a text box, so you need to change the control type to a label to render a read-only version of the data.

Local properties are a key part of screen design. Any content you want to add to a screen must be bound to a property, so you use local properties to work with data that’s disconnected from the main data on your screen.

Adding Data Controls to a Screen

The Engineer Dashboard screen includes a Quick Find feature engineers can use to quickly find and open issue records by using an autocomplete box. Therefore, you need to add an autocomplete box that’s not connected to the main data shown on your screen.

As with the string property example, you can add additional data controls by using the Add Data Item button. Because you want to add an autocomplete box that shows issues, select Issue from the type drop-down box and name your property IssueSelectionProperty.

To create the autocomplete box, simply drag IssueSelectionProperty from the Screen Member list onto your Screen Content Tree.

By default, the autocomplete box searches all records in the issue table. If you want to restrict the autocomplete box choices, create a query on the issue table and apply some filters. Add the query to your screen using the Add Data Item dialog and amend the Choices property of your autocomplete box using the Properties sheet.

To open the issue the user selects in a new screen, write code that calls the show method that relates to your issue details screen, and pass in the issue ID of the IssueSelectionProperty. You’ll see an example of how to do this later on. (See Listing 7-4.)

Setting Control Values and Default Values

You’ll often need to set the value that’s displayed on text boxes, date pickers, and other controls. In LightSwitch, you don’t set control values by accessing the Silverlight controls directly. If you recall the Model-View-ViewModel (MVVM) principles described in Chapter 1, controls are views that bind to the view model. So to set the value that’s shown on a control, you should update the value on the underlying property.

The new issue screen allows users to set a priority by using an autocomplete box. To default the priority to medium when the screen loads, add the code from Listing 7-2 to the InitializeDataWorkspace method of your screen.

Listing 7-2.  Setting Control Values

VB:
File:HelpDeskVBClientUserCodeCreateNewIssue.vb
  
Me.IssueProperty.Priority =
   DataWorkspace.ApplicationData.Priorities.Where(
      Function(item) item.PriorityDesc = "Medium").
        FirstOrDefault()
  
C#:
File:HelpDeskCSClientUserCodeCreateNewIssue.cs

this.IssueProperty.Priority =
   DataWorkspace.ApplicationData.Priorities.Where(
      (item => item.PriorityDesc == "Medium").
        FirstOrDefault();

The properties you can access in code correspond to the items that the screen designer shows in the Screen Member list. (See Figure 7-3.)

Notice that you cannot set the priority value by simply setting a string value of medium. Priority is a related item, so you need to assign an object that represents a medium priority to the IssueProperty.Priority property. The LINQ query shown in Listing 7-2 retrieves the medium priority by priority description, and it enables you to make this assignment.

Setting the Screen Title in Code

The Engineer Dashboard screen shows a custom title rather than the engineer summary property. To set a screen title in code, you set the DisplayName property as shown in Listing 7-3.

Listing 7-3.  Setting the Screen Title in Code

VB:
File:HelpDeskVBClientUserCodeEngineerDashboard.vb
  
Private Sub Engineer_Loaded(succeeded As Boolean)
    Me.DisplayName = "Engineer Dashboard"
End Sub
  
C#:
File:HelpDeskCSClientUserCodeEngineerDashboard.cs
  
partial void Engineer_Loaded(bool succeeded)
    this.DisplayName = "Engineer Dashboard";
End Sub

Figure 7-5 shows the screen tab title at runtime. LightSwitch also includes a method called SetDisplayNameFromEntity. You use this method to pass in an entity and to set the screen title using the summary property of the entity you supplied. By default, LightSwitch uses this method on any screens that you created based on the Details Screen template.

Creating an Advanced Search Screen

The HelpDesk application includes an advanced search screen engineers can use to search for issues by using multiple combinations of search criteria. This screen uses the IssueSearchAll query you created in Exercise 6.1. An important topic you’ll work with in this section is how to set query parameters.

Begin by creating an editable grid screen that uses the IssueSearchAll query, and name your screen IssueSearchAll. When you create a screen that uses a query with parameters, LightSwitch automatically creates properties and controls that allow the user to enter the parameter values.

You’ll notice that LightSwitch creates an EngineerId property and renders it as a text box onto the search screen. In terms of usability, be aware that your users won’t thank you for making them search for issues by the numeric engineer ID. A much better approach is to show the engineer names in an autocomplete box, and to bind the selected engineer ID to your query parameter.

To do this, create an autocomplete box in the same way as in the earlier example by adding a local engineer property called EngineerSelectionProperty. Now use the Properties sheet to set the Parameter Binding value to the ID value of EngineerSelectionProperty, as shown in Figure 7-6. You can now delete the autogenerated EngineerId property because it’s no longer needed.

When you run this screen, you’ll be able to use the autocomplete box to filter the issues by engineer. (You’ll extend this screen in the “Hiding and Showing Controls” section later in this chapter.)

Opening Screens from Buttons or Links

In Chapter 3, you learned how to launch child screens by adding labels and setting their Target Screen properties. A disadvantage of this approach is that it’s tricky to alter the text shown on the label, and you can choose to open only details screens that match the entity shown on your label. I’ll now show you another approach you can use to open screens.

The Quick Links section in the Engineer Dashboard provides the user with quick access to other screens. These links are bound to screen commands. You use screen commands to add buttons or links to perform some action in code.

To create a new command, select a group container, such as a Rows Layout, right-click, and select the Add Button option. After you add the button, you can use the Properties sheet to change the control to a link. (See Figure 7-7.)

Although it’s fairly simple to add a button or link, the actual screen layout takes a bit of effort. Figure 7-8 shows you how this layout looks at design time compared with how it looks at runtime. Notice how the layout uses sets of groups, each containing one command. To make sure all your links line up, you need to verify that the horizontal alignment settings are all set to left rather than stretch.

Laying out controls at design time is difficult because you can’t visualize how your screen will appear. As I mentioned in Chapter 3, the trick to effective layout design is to use the runtime screen designer. By doing so, you can change the appearance settings and immediately see the effect the change has on your running screen.

Once you create your command, you can double-click it to open the code window. Here, you can write code that uses the Application object’s Show methods to open your screens (as discussed in Chapter 4).

Another area where you’ll want to open screens is through a cell on a data grid. Chapter 3 showed you how to do this by using labels and specifying the link settings. The problem with this approach is that you can open only details screens that match the entities shown in the grid. Another problem is that the data grid binds the display text to a property, which means you can’t use static text.

The way around this problem is to use a grid row command. In the designer, expand the Command Bar group in the Data Grid Row, and click the Add button to add a new button. In this example, the grid row command is called ViewDashboard.

Figure 7-9 shows an engineer selection page that’s used by managers. It includes two links that appear on the right side of the grid to allow a manager to view the dashboard and time-tracking screens for an engineer.

The code that opens the dashboard is shown in Listing 7-4. Notice how the code uses the SelectedItem property of the visual collection to return the ID of the engineer in the selected row.

Listing 7-4.  Opening Screens from a Data Grid Command

VB:
File:HelpDeskVBClientUserCodeEngineersManagerGrid.vb

Private Sub ViewDashboard_Execute()
    Application.ShowEngineerDashboard(
        Engineers.SelectedItem.Id)
End Sub
  
C#:
File:HelpDeskCSClientUserCodeEngineersManagerGrid.cs
  
partial void ViewDashboard_Execute()
    this.Application.ShowEngineerDashboard(
        Engineers.SelectedItem.Id);
End Sub

Refreshing All Open Screens

The dashboard page includes a link to refresh all screens that are open in the application. The code that performs this refresh is shown in Listing 7-5.

Listing 7-5.  Refreshing All Open Screens

VB:
File:HelpDeskVBClientUserCodeEngineerDashboard.vb
  
Dim screens = Me.Application.ActiveScreens()                         
For Each s In screens

Dim screen = s.Screen
    screen.Details.Dispatcher.BeginInvoke(                           
         Sub()
            screen.Refresh()                                         
         End Sub)
Next
  
C#:
File:HelpDeskCSClientUserCodeEngineerDashboard.cs
  
var screens = this.Application.ActiveScreens;                        
foreach (var s in screens)
{
    var screen = s.Screen;
    screen.Details.Dispatcher.BeginInvoke(() =>                      
    {
        screen.Refresh();                                            
    });
}

This code uses the Application object’s ActiveScreens collection to find all open screens. It then calls the Refresh method on each screen. The code needs to call the Refresh method on the same thread that owns the screen. The threading code in invokes the logic on the correct thread, and you’ll learn more about this in the “Working with Threads” section.

Passing Arguments into Screens

You can use the screen designer to create screen parameters that accept arguments when you open a screen.

The first link in the Quick Links section opens the custom search screen you created earlier. This example shows you how to supply an engineer property to the Search screen when it opens. This allows you to default the engineer autocomplete box to the value that’s passed to it from the Engineer Dashboard screen.

To turn your Search screen’s engineer property into a parameter, select the engineer property and select the Is Parameter check box as shown in Figure 7-10.

To pass an engineer to the Search screen, you can simply call the screen’s show method and provide the engineer you want to use. The code in Listing 7-6 passes to the Search screen the engineer that’s represented by the dashboard screen’s engineer property.

Listing 7-6.  Passing Screen Parameters

VB:
File:HelpDeskVBClientUserCodeEngineerDashboard.vb
  
Private Sub OpenIssueSearchScreen_Execute()
    Application.ShowIssueSearchAll (Me.Engineer.Id)
End Sub
  
C#:
File:HelpDeskCSClientUserCodeEngineerDashboard.cs
  
partial void OpenIssueSearchScreen_Execute(){
    this.Application.ShowIssueSearchAll (this.Engineer.Id);
}

If you defined multiple parameters, IntelliSense shows you the correct order in which to pass in the arguments.

Creating a Continuous New Data Screen

The screens you create with the New Data Screen template behave in a specific way. When a user saves her record, LightSwitch closes the screen and reopens the record by using the Details Screen for your entity.

In some circumstances, you might want to allow the user to immediately enter another record rather than show the newly created record in a details screen.

To make this change, open the code file for your New Data Screen and delete the two lines in the Saved method that closes the screen and reopens the entity in the details screen. (See Listing 7-7.) To allow the entry of another new record, add a line that creates an instance of a new entity.

Listing 7-7.  Reset the New Data Screen After a Save

VB:
File:HelpDeskVBClientUserCodeCreateNewIssue.vb
  
Private Sub CreateNewIssue_Saved()
    'Delete the auto generated lines below
    'Me.Close(False)
    'Application.Current.ShowDefaultScreen(Me.IssueProperty)
    Me.IssueProperty = New Issue
End Sub
  
C#:
  
File:HelpDeskCSClientUserCodeCreateNewIssue.cs
  
partial void CreateNewIssue_Saved(){
    //Delete the auto generated lines below
    //this.Close(false);
    //Application.Current.ShowDefaultScreen(Me.IssueProperty);
    this.IssueProperty = new Issue();
}

VB:
File:HelpDeskVBClientUserCodeSetup.vb
  
Private Sub ArchiveIssues_Execute()
    If Me.ShowMessageBox(
            "Are you sure you want delete all issues older than 12 months?",
            "Confirm Delete", MessageBoxOption.YesNo) =
            System.Windows.MessageBoxResult.Yes Then
        DeleteOldIssues()
    End If
End Sub

C#:
File:HelpDeskCSClientUserCodeSetup.cs
  
partial void ArchiveIssues_Execute()
{
    if (this.ShowMessageBox(
        "Are you sure you want delete all issues older than 12 months?",
        "Confirm Delete", MessageBoxOption.YesNo) ==
        System.Windows.MessageBoxResult.Yes)
    {
        DeleteOldIssues();
    }
}

Finding Controls Using FindControl

The key to working with controls is to use the FindControl method. This returns an object of type IContentItemProxy, which represents LightSwitch’s View-Model object. The IContentItemProxy members you can access are shown in Table 7-2.

As you can see, there are some useful properties you can access, especially the IsVisible and IsEnabled properties.

A related method is the FindControlInCollection method. You use this to obtain an IContentItemProxy reference to a control that belongs inside a data grid (or any control that shows a collection of data, such as a list). You’ll see an example of how to use this method later on.

VB:
File:HelpDeskVBClientUserCodeCreateNewIssue.vb
  
Me.FindControl("ProblemDescription").Focus()
  
C#:
File:HelpDeskCSClientUserCodeCreateNewIssue.cs
  
this.FindControl("ProblemDescription").Focus();

VB:
File:HelpDeskVBClientUserCodeIssueSearchAll.vb
  
Private Sub ToggleVisibility_Execute()
    Dim rowLayout = Me.FindControl("AdvancedGroup")
    rowLayout.IsVisible = Not (rowLayout.IsVisible)                                   
  
    If rowLayout.IsVisible Then
        Me.FindControl("ToggleVisibility").DisplayName =
           "Show Simple Filters"                                                      
    Else
        Me.FindControl("ToggleVisibility").DisplayName =
           "Show Advanced Filters"                                                    
    End If
End Sub
  
C#:
File:HelpDeskCSClientUserCodeIssueSearchAll.cs
  
partial void ToggleVisibility_Execute()
{
    var rowLayout = this.FindControl("AdvancedGroup");
    rowLayout.IsVisible = !(rowLayout.IsVisible);                                    
  
    if (rowLayout.IsVisible)
       {
        this.FindControl("ToggleVisibility").DisplayName =
           "Show Simple Filters";                                                    
       }
    else
       {
        this.FindControl("ToggleVisibility").DisplayName =
           "Show Advanced Filters";                                                  
       }
}

VB:
File:HelpDeskVBClientUserCodeEngineersManagerGrid.vb
  
For Each eng In Engineers                                             
    Me.FindControlInCollection(
        "SecurityVetted", eng).IsEnabled = False                      
Next
  
C#:
File:HelpDeskCSClientUserCodeEngineersManagerGrid.cs

foreach (Engineer eng in Engineers)                                   
{
    this.FindControlInCollection(
        "SecurityVetted", eng).IsEnabled = false;                     
}

Reference the Underlying Silverlight Control

As you’ll recall from Figure 7-1, the Engineer Dashboard screen displays the number of outstanding issues. If the number of outstanding issues exceeds 10, the label should be shown in red.

Although you can use the IContentItemProxy object to set the visibility, focus, and read-only state of a control, you cannot use it to access other control attributes. To do this, you need to reference the underlying Silverlight control.  

Once again, this requires you to use the FindControl method to return an IContentItemProxy object. This provides you with two ways to access the Silverlight control. You can either handle the ControlAvailable event or data-bind your screen properties to dependency properties on your control by calling the SetBinding method. Chapter 9 shows you how to apply the SetBinding technique.

To use the ControlAvailable method, add the code in Listing 7-12 to the InitializeDataWorkspace method of your Engineer Dashboard screen.

Listing 7-12.  Referencing a Control Using ControlAvailable

VB:
File:HelpDeskVBClientUserCodeEngineerDashboard.vb
  
AddHandler Me.FindControl("IssuesOverdueLabel").ControlAvailable,
    Sub(sender As Object, e As ControlAvailableEventArgs)
    Dim issueLabel = CType(e.Control,
        System.Windows.Controls.TextBlock)                              
    issueLabel.Foreground = New SolidColorBrush(Colors.Red)             
End Sub
  
C#:
File:HelpDeskCSClientUserCodeEngineerDashboard.cs
  
using System.Windows.Media;
  
var control = this.FindControl("IssuesOverdueLabel");
  
control.ControlAvailable +=
(object sender, ControlAvailableEventArgs e) =>
{
    var issueLabel =
        (System.Windows.Controls.TextBlock)e.Control;                  
    issueLabel.Foreground = new SolidColorBrush(Colors.Red);           
};

When you handle the ControlAvailable event, the ControlAvailableEventArgs parameter allows you to access the underlying Silverlight control.

Because you know that LightSwitch labels are rendered as a Silverlight Text Blocks, you can simply declare a variable and cast IssuesOverdueLabel to an object of type System.Windows.Controls.TextBlock . This allows you to access all of the text-block properties in code and to set the foreground color .

If you want to access a LightSwitch control in code but don’t know what the underlying Silverlight type is, you can handle the ControlAvailable event, set a breakpoint in this method, and query e.Control.GetType() in the immediate window.

As the name suggests, LightSwitch fires the ControlAvailable event when the control becomes available. This means that when you write code that handles this event, you won’t encounter the errors that might occur if you try to access the control too early.

Handling Silverlight Control Events

When you write code in the ControlAvailable method, you can also add event handlers to handle the events raised by the Silverlight control.

To give you an example of the sorts of events you can handle, Table 7-3 shows you some of the events that the Silverlight text-box control raises. There are many more events you can use; this table shows only a subset, but it gives you a flavor of the sort of events you can handle.

The Issue Response screen allows engineers to respond to users. The maximum response text allowed is 1000 characters.

This example shows you how to provide the user with a running count of the number of remaining characters as soon as they’re entered by the user.

To create this example, create a new screen based on the Issue Response table, add a new local integer property called ResponseTextCount, and enter the code shown in Listing 7-13.

Listing 7-13.  Handling the Text Box KeyUp Event

VB:
File:HelpDeskVBClientUserCodeCreateNewIssueResponse.vb
  
Private Sub CreateNewIssueResponse_InitializeDataWorkspace(
   saveChangesTo As List(Of Microsoft.LightSwitch.IDataService))
    Me.IssueResponseProperty = New IssueResponse()
  
    Dim control = Me.FindControl("ResponseText")
    AddHandler control.ControlAvailable,
        AddressOf TextBoxAvailable                                           
  
    ResponseTextCount = 1000
  
End Sub
  
Private Sub TextBoxAvailable(
   sender As Object, e As ControlAvailableEventArgs)
    AddHandler CType(e.Control,
        System.Windows.Controls.TextBox).KeyUp,
            AddressOf TextBoxKeyUp                                           
End Sub
  
Private Sub TextBoxKeyUp(
    sender As Object, e As System.Windows.RoutedEventArgs)

    Dim textbox = CType(sender, System.Windows.Controls.TextBox)
    ResponseTextCount = 1000 - textbox.Text.Count()                          
End Sub
  
C#:
File:HelpDeskCSClientUserCodeCreateNewIssueResponse.cs
  
partial void CreateNewIssueResponse_InitializeDataWorkspace(
    List<IDataService> saveChangesTo)
{
    this.FindControl("ResponseText").ControlAvailable += TextBoxAvailable;       
    ResponseTextCount = 1000;
  
}
  
private void TextBoxAvailable(object sender, ControlAvailableEventArgs e)
{
    ((System.Windows.Controls.TextBox)e.Control).KeyUp += TextBoxKeyUp;          
}
  
private void TextBoxKeyUp(object sender, System.Windows.RoutedEventArgs e)
{
    var textbox = (System.Windows.Controls.TextBox)sender;
    ResponseTextCount = 1000 - textbox.Text.Count();                             
}

When the screen first loads, the code in the InitializeDataWorkspace method adds an event handler called TextBoxAvailable, which handles the ControlAvailable event of the ResponseText text box . This initial code also initializes the ResponseTextCount to 1000.

When the ResponseText control becomes available, the code adds an event handler called TextBoxKeyUp that handles the KeyUp event of the control .

The TextBoxKeyUp method runs whenever the user types a character into the response text text box, and it recalculates the number of remaining characters . Figure 7-14 shows how the screen appears at runtime.

Designing an Add/Edit Screen

As you now know, you can create screens to view data by using the Details Screen template. For adding data, you can add a screen that uses the New Data template. However, LightSwitch doesn’t include a screen template you can use to both edit and view data using the same screen.

In this example, you’ll find out how to create a combined Add and Edit screen. If you need to create screens that look consistent for adding and viewing data, this technique saves you from having to carry out the same customization in two places. It’ll also make your application more maintainable because there’ll be fewer screens to maintain in your application.

Here are the steps to build a combined add/edit screen:

1. Create a details screen for the issue entity, and make it the default screen. Name your screen AddEditIssue.
2. LightSwitch creates an ID property called IssueId. Make this optional by deselecting the Is Required check box.
3. Click the Add Data Item button, and add a local property of data type issue. Name this IssueProperty.
4. Delete the content on the screen that’s bound to the issue query.
5. Re-create the screen controls by dragging the IssueProperty property onto the Screen Content Tree. By default, LightSwitch creates IssueProperty as an autocomplete box. Change the control type to Rows Layout.

Now add the following code to the query’s loaded method, as shown in Listing 7-14.

Listing 7-14.  Issue Add and Edit Code

VB:
File:HelpDeskVBClientUserCodeAddEditIssue.vb
  
Private Sub Issue_Loaded(succeeded As Boolean)
  
    If Not Me.IssueId.HasValue Then
        Me.IssueProperty = New Issue()                                
    Else
        Me.IssueProperty = Me.Issue                                   
    End If
  
    Me.SetDisplayNameFromEntity(Me.Issue)
  
End Sub
   
C#:
File:HelpDeskCSClientUserCodeAddEditIssue.cs
  
partial void Issue_Loaded(bool succeeded)
{
    if (!this.IssueId.HasValue)
    {
        this.IssueProperty = new Issue();                                 
    }
    else
    {
        this.IssueProperty = this.Issue;                                  
    }
    this.SetDisplayNameFromEntity(this.IssueProperty);
}

When you create a screen that uses the Details Screen template, LightSwitch creates a query that returns a single issue using the primary key value. It creates a screen parameter/property called IssueId.

If all of your screen controls are bound to this query, your screen won’t work in Add mode. Therefore, you need to create a local property called IssueProperty and bind the UI controls on your screen to this property.

You then need to make the IssueId screen parameter optional. If the code that opens the screen doesn’t supply an IssueId value, the code sets IssueProperty to an instance of a new issue and allows the user to enter a new issue.

If the code that opens the screen supplies an IssueId, the code sets IssueProperty to the issue that’s returned by the issue query .

Because you set this screen as the default screen, any issue you display using the summary control will use this screen.

The code in Listing 7-15 shows the code that’s used on the Engineer Dashboard screen to open the screen in Add mode.

Listing 7-15.  Opening the Combination Screen to Add a New Record

VB:
File:HelpDeskVBClientUserCodeEngineerDashboard.vb
  
Private Sub OpenNewIssueScreen_Execute()
    Application.ShowAddEditIssue(Nothing)
End Sub
     
C#:
File:HelpDeskCSClientUserCodeEngineerDashboard.cs
  
partial void OpenNewIssueScreen_Execute()
{
    this.Application.ShowAddEditIssue(null);
}

Customizing Data Grid Dialogs

The Data Grid control includes buttons that enable users to add and edit records. But the data entry screens that LightSwitch shows are autogenerated and can’t be modified. (See Figure 7-15.)

If you want to customize the data entry windows that open up from the data grid, remove the default Add and Edit buttons and build your own modal window.

In this example, you’ll customize the data grid on the issue search screen. You’ll modify the autogenerated window shown in Figure 7-15 to hide the issue closing details and make the Problem Description field multiline.

Here are the steps that you need to carry out to build a custom modal window screen:

1. Open your issues search screen (IssueSearchAll).
2. At the root level of the screen, add a new group and change the group type to Modal Window. Name this group IssueWindow.
3. Add the data items you want to show by dragging them from the IssueSearchAll SelectedItem property onto your modal window. Make the Problem Description field multiline by setting the lines property to a value greater than 1.
4. Add an OK button to your modal window by right-clicking the modal window group and choosing the Add Button option. Name your button SaveItem. Now add a Cancel button and call it CancelItem.
5. Hide the modal window’s Show button by deselecting the Show Button check box in the Properties sheet. You’ll be opening this modal window in code, so the default Show button isn’t necessary.
6. Delete the data grid’s Add, Edit, and Delete buttons in the command bar of your data grid (if they exist).
7. Add new Add, Edit, and Delete buttons in your data grid’s Command Bar section. (Name these methods AddItem, EditItem, and DeleteItem.) Create their Execute methods.

You screen should now look like Figure 7-16. Now add the code that’s shown in Listing 7-16.

Listing 7-16.  Controlling the Custom Modal Window

VB:
File:HelpDeskVBClientUserCodeIssueSearchAll.vb
  
Private Sub AddItem_Execute()
    Issues.AddNew()                                                              
    Me.OpenModalWindow("IssueWindow")                                            
End Sub
  
Private Sub EditItem_Execute()
    Me.OpenModalWindow("IssueWindow")                                            
End Sub
  
Private Sub SaveItem_Execute()
    Me.CloseModalWindow("IssueWindow")
End Sub
  
Private Sub CancelItem_Execute()
    CType(Issues.SelectedItem, Issue).Details.DiscardChanges()                   
    Me.CloseModalWindow("IssueWindow")
End Sub
  
C#:
File:HelpDeskCSClientUserCodeIssueSearchAll.cs
  
partial void AddItem_Execute()
{
    Issues.AddNew();                                                             
    this.OpenModalWindow("IssueWindow");                                         
}
  
partial void EditItem_Execute()
{
    this.OpenModalWindow("IssueWindow");                                         
}
  
partial void SaveItem_Execute()
{
    this.CloseModalWindow("IssueWindow");
}
  
partial void CancelItem_Execute()
{
   ((Issue)Issues.SelectedItem).Details.DiscardChanges();                    
    this.CloseModalWindow("IssueWindow");
}

LightSwitch includes two methods you use to work with modal windows (the OpenModalWindow and CloseModalWindow methods). Both of these methods require you to supply the name of the modal window you want to open or close.

The Add Item button creates a new issue by calling the visual collection’s AddNew method . Once you add a new issue, the new issue becomes the selected item. When the code opens your modal window , it’ll show the new record because the contents of the modal window are bound to the visual collection’s selected item.

The Edit button simply calls the OpenModalWindow method and displays the issue that’s currently selected in the data grid. Both the Save and Cancel buttons close the modal window by calling the CloseModalWindow method. The Cancel button calls the DiscardChanges method to undo any changes that have been made to the issue. This method restores the issue to the state it was in when the screen was first loaded. Unfortunately, it isn’t simple to undo only the changes that the user made in the modal window without writing lots of extra code.

Figure 7-17 shows how the screen looks at runtime. As you can see, this is big improvement over the autogenerated window. (See Figure 7-15.)

To extend this sample further, you can set the title of the modal window so that it shows the entity that’s being edited. To do this, you set the DisplayName property of the modal window by calling the FindControl method. You can also change the text buttons to image buttons by using the option in the Properties sheet.

Nesting Autocomplete Boxes

Another scenario you might encounter is the need to create sets of nested autocomplete boxes.

In this example, you’ll create an editable grid screen called IssuesByUser that allows managers to find issues filtered by user. This screen contains an autocomplete box that shows a list of departments. When the user selects a department, it populates a second autocomplete box that shows the users who belong in the department.

To carry out this example, you need to create a couple of queries. The first query returns a set of issues that are filtered by user. This query populates the main data grid that’s shown on the screen. The second query returns a list of users filtered by department. It’s used to populate the second autocomplete box.

Here are the steps you need to carry out to create these queries:

1. Create a query called IssuesByUsers that filters the User Id property by an integer parameter called UserId.
2. To allow the Users autocomplete box to be filtered by department, create a query called UsersByDepartment on the User table. Filter the Department Id property by a new parameter called DepartmentId. Both of these queries are shown in Figure 7-18.

Now create an editable screen based on the IssuesByUser query, and name your screen IssuesByUserGrid. Carry out the remaining steps in the screen designer:

1. Add two autocomplete boxes to your screen by adding a local department property called DepartmentProperty and a local user property called UserProperty.
2. Create autocomplete boxes by dragging these properties onto your screen.
3. Click the Add Data Item button, and add the UsersByDepartment query you created earlier.
4. Set the DepartmentId parameter value of your UsersByDepartment query to the value that’s selected in the department AutoCompleteBox. To do this, select the DepartmentId parameter and set the parameter binding to DepartmentProperty.Id.
5. Select your Users autocomplete box, and view the Properties sheet. Use the Choices drop-down list to change the data source from Users to UsersByDepartment.
6. Change the parameter binding of the IssuesByUser UserId parameter so that it points to UserProperty.Id rather than the default binding of IssueUserId that LightSwitch sets up for you.

When you run your screen, the Users autocomplete box will be filtered by the value that the user selects in the department autocomplete box, as shown in Figure 7-19. As you’ll notice, the presentation of this screen has been improved by placing the autocomplete boxes in a group and providing more friendly descriptions.

Bulk Updating Records by Using a Multiselect Grid

One of the limitations of the built-in data grid is that you can’t select multiple records. In this example, you’ll modify the IssuesManagerGrid so that it allows managers to close multiple issues.

To begin, you need to add a reference to the System.Windows.Controls.Data assembly. To do this, follow these steps:

1. Switch your project to File View and right-click your Client project.
2. Choose the Add Reference option, and select the System.Windows.Controls.Data assembly.

Now return to Logical View and carry out the following tasks:

1. Create an editable grid screen based on the issue entity, and name it IssuesManagerGrid.
2. Click the Add Data Item button, and add a new method called CancelSelectedIssues.
3. Create a button by dragging the CancelSelectedIssues method onto a suitable place in your screen.
4. Add the code that’s shown in Listing 7-17.

Listing 7-17.  Bulk-Closing Multiple Records

VB:
File:HelpDeskVBClientUserCodeIssuesManagerGrid.vb
  
Private WithEvents _datagridControl As DataGrid = Nothing
  
Private Sub IssuesManagerGrid_Created()
    '  1 Replace grid with the name of your data grid control                           
    AddHandler Me.FindControl("grid").ControlAvailable,
        Sub(send As Object, e As ControlAvailableEventArgs)
             _datagridControl = TryCast(e.Control, DataGrid)
             _datagridControl.SelectionMode =
                 DataGridSelectionMode.Extended                                            
        End Sub
End Sub
  
Private Sub CancelSelectedIssues_Execute()
  
    Dim closedStatus = DataWorkspace.ApplicationData.IssueStatusSet.Where(
        Function(i) i.StatusDescription = "Closed").FirstOrDefault                         
  
    Dim closedEng = DataWorkspace.ApplicationData.Engineers.Where(
        Function(e) e.LoginName=Application.User.Identity.Name).FirstOrDefault             
  
    For Each item As Issue In _datagridControl.SelectedItems                               
        item.IssueStatus = closedStatus
        item.ClosedByEngineer = closedEng
        item.ClosedDateTime = Date.Now
    Next
End Sub
   
  
C#:
File:HelpDeskCSClientUserCodeIssuesManagerGrid.cs
  
using System.Windows.Controls;
  
private DataGrid _datagridControl = null;
  
partial void IssuesManagerGrid_Created()
{
    //1 Replace grid with the name of your data grid control                               
    this.FindControl("grid").ControlAvailable +=
        (object sender, ControlAvailableEventArgs e) =>
        {
            _datagridControl = ((DataGrid)e.Control);
            _datagridControl.SelectionMode =
                DataGridSelectionMode.Extended;                                            
        };
}
  
partial void CancelSelectedIssues_Execute()
{
  
    var closedStatus = DataWorkspace.ApplicationData.IssueStatusSet.Where(
        i => i.StatusDescription == "Closed").FirstOrDefault();                            
  
    var closedEng = DataWorkspace.ApplicationData.Engineers.Where(
        e => e.LoginName == Application.User.Identity.Name).FirstOrDefault();              
  
    foreach (Issue item in _datagridControl.SelectedItems)                                 
  
    {
        item.IssueStatus = closedStatus;
        item.ClosedByEngineer = closedEng;
        item.ClosedDateTime = DateTime.Now;
    }
}

When the screen first loads, the code in the Created method adds an event handler that handles the ControlAvailable event of the data grid. The code uses the FindControl method to return a reference to the data grid. By default, this is called grid, so you might need to change this line of code if you named your data grid differently.

When the data grid becomes available, the code sets the SelectionMode of the data grid to Extended . This setting allows the user to select multiple records.

When a user clicks the CancelSelectedIssues button, the code loops through the selected items on the grid and cancels the issues. The queries in this method retrieve the “closed state” and “closed by engineer” entities that are needed to close the issue.

The code in works on the assumption that you enabled authentication in your application. (See Chapter 16.) When you enable authentication, Application.User.Identity.Name returns the name of the logged-in user. The Engineer table is designed to store the login name of each engineer so that you can match engineer records with login names.

Figure 7-20 shows how the screen looks at runtime. Notice how you can select multiple rows by using the Ctrl key.

VB:
File:HelpDeskVBClientUserCodeEngineerDetail.vb
  
Private Sub AssignSubordinate_Execute()
    Engineer.Subordinates.Add(EngineerToAdd)                                  
    Subordinates.Refresh()
End Sub
  
Private Sub UnassignSubordinate_Execute()
    Engineer.Subordinates.Remove(Subordinates.SelectedItem)                   
    Subordinates.Refresh()                                                    
End Sub
  
C#:
File:HelpDeskCSClientUserCodeEngineerDetail.cs
  
partial void AssignSubordinate_Execute()
{
    Engineer.Subordinates.Add(EngineerToAdd);                             
    Subordinates.Refresh();
}
  
partial void UnassignSubordinate_Execute()
{
    Engineer.Subordinates.Remove(Subordinates.SelectedItem);              
    this.Save();                                                          
    Subordinates.Refresh();
}

VB:
File:HelpDeskVBClientUserCodeAppOptionsEdit.vb
  
Private Sub AppOptionsEdit_InitializeDataWorkspace(
    saveChangesTo As List(Of Microsoft.LightSwitch.IDataService))
    Me.AppOptionProperty =
        DataWorkspace.ApplicationData.AppOptions.FirstOrDefault()    
    If AppOptionProperty Is Nothing Then
        AppOptionProperty = New AppOption                            
    End If
End Sub
  
C#:
File:HelpDeskCSClientUserCodeAppOptionsEdit.cs
  
partial void AppOptionsEdit_InitializeDataWorkspace(
   List<IDataService> saveChangesTo)
{
    this.AppOptionProperty =
        DataWorkspace.ApplicationData.AppOptions.FirstOrDefault();   
  
    if (AppOptionProperty == null){
        this.AppOptionProperty = new AppOption();                    
    }
}

Working with Threads

So far, you’ve seen a few examples of code that includes threading syntax. I’ll now explain how this works in more detail.

LightSwitch applications are multithreaded. This means that your application can perform multiple tasks at the same time, which results in better use of resources and a more responsive user interface.

Although each thread provides an independent execution path, threads are not completely isolated from one another. The threads in a LightSwitch application are able to share data and memory. This is the reason why multithreading is so useful. In a LightSwitch application, one thread can fetch data from the data service while another thread updates the UI as soon as the data arrives.

Threads can be categorized into two distinct types: UI threads and worker threads. UI threads are responsible for creating and controlling UI elements, whereas worker threads are generally responsible for carrying out long-running tasks such as fetching data.

Multithreaded applications start with a single thread (the main thread) that’s created by the operating system and CLR (the .NET Common Language Runtime). LightSwitch creates additional threads off of the main thread, and your application thus becomes multithreaded.

When you write user code in LightSwitch, you can execute it in one of three threads. Certain tasks will work only on a specific thread. So if your code attempts to run on the wrong thread, you’ll receive a runtime exception.

From a practical prospective, the key point to understand is that you must run code on the correct thread. .NET threading is a complex topic and beyond the scope of this book. But to help you choose the correct thread, here are three simple rules:

1. UI Rule: Any code that interacts with the user must be executed on the UI thread. If you try to perform UI tasks on a worker thread, you’ll get an exception.
2. Thread Affinity Rule: Silverlight objects and controls inherit from the DependencyObject class. By doing so, these objects have thread affinity. This means that only the thread that instantiates the object can subsequently access its members. If you try accessing these members from a different thread, you’ll get an exception.
3. Worker Thread Rule: If you want to perform data access or long-running tasks, you should carry out this work on a worker thread. If you carry out this work on the UI thread, you’ll make your application unresponsive. This means that it’ll be slow to respond to keystrokes and mouse clicks, or it might freeze for long periods of time.

Figure 7-24 illustrates the threads that make up a LightSwitch application. Your application starts execution on a main UI thread. The main thread spawns an application thread. This thread is responsible for opening screens and for performing global logic that isn’t associated with any specific screen. The code in your Application class executes in this thread. You’ll find the code file in the folder ClientUsercode.

Each screen in a LightSwitch application also has its own worker (or logic) thread. By default, LightSwitch executes any user code you write on the screen’s logic thread. For example, if you click the Write Code button and write some code in the screen’s created method, or if you write some custom code that handles the click of a button, that code will execute on the screen’s logic thread. This is good news because you don’t need to worry about inadvertently doing something that could freeze your UI.

If you need to run some code that updates your UI, you need to execute that code on the main UI thread. To do that, you use a Dispatcher object. The syntax you use to reference the three threads is as follows:

• Main Dispatcher (UI thread):
  Microsoft.LightSwitch.Threading Dispatchers.Main
• Screen Dispatcher (screen logic thread):
  Screen.Details.Dispatcher
  (Use the Me.Details.Dispatcher (VB) or this.Details.Dispatcher (C#) syntax in your screen code.)
• Application Dispatcher (application thread):
  Application.Details.Dispatcher

The Dispatcher object includes a method called BeginInvoke. You use this method to supply the code you want to execute on the thread and execute it asynchronously. This means that the calling code carries on executing, and the code you want to invoke will be queued for execution.

By adding an imports (VB) or using statement to the  Microsoft.LightSwitch.Threading namespace at the start of your screen code file, you can access an extension method through the Dispatcher object called Invoke. The difference between BeginInvoke and Invoke is that the Invoke method executes your code synchronously, and the calling thread will wait for the code to complete before it continues.  By calling Invoke rather than BeginInvoke, you can block your application while your code runs, and LightSwitch displays an hourglass to the user during this process. The advantage of using Invoke is that in some scenarios, you might want your application to show a 'wait state' in order to provide a positive indication that your process is in progress. Also, Invoke makes it easier for you to handle any return values from the code that you invoke, and can simplify any error handling code that you want to write.

VB:
File:HelpdeskVBClientUserCodeCreateNewIssue.vb
  
Me.IssueProperty = New Issue                                                            
  
Me.Details.Dispatcher.BeginInvoke(
    Sub()
       'This code executes on the screen logic thread
       Me.IssueProperty.ProblemDescription = "Desc. (screen logic thread)"              
    End Sub)
  
Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(
    Sub()
       //This code executes on the UI thread
       Me.IssueProperty.ProblemDescription = "Desc. (main thread)"                      
    End Sub)
  
C#:
File:HelpDeskCSClientUserCodeCreateNewIssue.cs
  
this.IssueProperty = new Issue();                                                       
  
this.Details.Dispatcher.BeginInvoke(() =>
   {
       //This code executes on the screen logic thread
       this.IssueProperty.ProblemDescription = "Desc. (screen logic thread)" ;          
   }
);
  
Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(() =>
   {
       //This code executes on the UI thread
       this.IssueProperty.ProblemDescription = "Desc. (main thread)";                   
    }
);

?Me.IssueProperty.Details.Dispatcher.ToString

"Microsoft.LightSwitch.Threading.BackgroundDispatcher"

Reacting to Data Changes

In any advanced application, you’ll want some way to make your UI react to changes in your data.

LightSwitch entities implement the INotifyPropertyChanged interface and raise an event called PropertyChanged whenever the value of any property in the entity changes. To make your application react to data changes, you can handle this event and carry out any UI changes in an event handler.

Although you can achieve similar results by handling Silverlight’s LostFocus event, there are several advantages to using PropertyChanged. If you want to use the LostFocus technique to monitor multiple properties, you need to create an event handler for each control. By using the PropertyChanged method, you need to set up only one event handler and you can use that to detect changes in any number of properties.

Furthermore, the LostFocus method is more fragile because it assumes what your underlying Silverlight control will be. You could potentially break your application by changing the control type.

In the example that follows, you’ll create a new data screen based on the Engineer table. This table includes properties that relate to security clearance, such as

• SecurityVetted: Required, Boolean field.
• SecurityClearanceRef: String field.
• VettingExpiryDate: Date field.

By default, the screen hides the security reference and vetting expiry date text boxes. When the user selects the security vetted check box, your screen will reveal the hidden controls.

The PropertyChanged method works differently on screens that are based on the New Data Screen and Details Screen templates. This section begins by describing the technique on a New Data Screen template.

VB:
File:HelpDeskVBClientUserCodeCreateNewEngineer.vb
  
Imports System.ComponentModel
  
Private Sub CreateNewEngineer_Created()
    Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(
        Sub()
           AddHandler DirectCast(
             Me.EngineerProperty, INotifyPropertyChanged
           ).PropertyChanged, AddressOf EngineerFieldChanged                      
        End Sub)
  
    'Set the initial visibility here
    Me.FindControl("SecurityGroup").IsVisible =
        EngineerProperty.SecurityVetted
End Sub
  
Private Sub EngineerFieldChanged(
    sender As Object, e As PropertyChangedEventArgs)
    If e.PropertyName = "SecurityVetted" Then                                 
        Me.FindControl("SecurityGroup").IsVisible =
           EngineerProperty.SecurityVetted
    End If
End Sub
  
C#:
File:HelpDeskCSClientUserCodeCreateNewEngineer.cs
  
using System.ComponentModel;
  
partial void CreateNewEngineer_Created()
{
    Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(() =>
    {
        ((INotifyPropertyChanged)this.EngineerProperty).PropertyChanged +=
            EngineerFieldChanged;                                             
    });
  
    //Set the initial visibility here
    this.FindControl("SecurityGroup").IsVisible =
        EngineerProperty.SecurityVetted;
}
  
  
private void EngineerFieldChanged(object sender, PropertyChangedEventArgs e)
{
    if (e.PropertyName == "SecurityVetted")                                   
    {
        this.FindControl("SecurityGroup").IsVisible =
            EngineerProperty.SecurityVetted;
    }
}

VB:
File:HelpDeskVBClientUserCodeEngineerDetail.vb
  
Imports System.ComponentModel

Private monitoredEngineer As Engineer
  
Private Sub EngineerDetail_InitializeDataWorkspace(
   saveChangesTo As List(Of Microsoft.LightSwitch.IDataService))
    ' Write your code here.
    Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(
      Sub()
          AddHandler Me.Details.Properties.Engineer.Loader.ExecuteCompleted,
              AddressOf Me.EngineerLoaderExecuted                                  
      End Sub)
End Sub
   
Private Sub EngineerLoaderExecuted(
    sender As Object, e As Microsoft.LightSwitch.ExecuteCompletedEventArgs)
  
    If monitoredEngineer IsNot Me.Engineer Then
        If monitoredEngineer IsNot Nothing Then
            RemoveHandler TryCast(monitoredEngineer,
                INotifyPropertyChanged).PropertyChanged,
                    AddressOf Me.EngineerChanged
        End If
  
        monitoredEngineer = Me.Engineer                                            
  
        If monitoredEngineer IsNot Nothing Then
            AddHandler TryCast(
               monitoredEngineer, INotifyPropertyChanged).PropertyChanged,
                  AddressOf Me.EngineerChanged
  
            'Set the initial visibility here
            Me.FindControl("SecurityGroup").IsVisible =
                monitoredEngineer.SecurityVetted
  
        End If
    End If
End Sub
  
Private Sub EngineerChanged(
   sender As Object, e As PropertyChangedEventArgs)
    If e.PropertyName = "SecurityVetted" Then
        Me.FindControl("SecurityGroup").IsVisible =
            monitoredEngineer.SecurityVetted                                   
    End If
End Sub
  
  
C#:
File:HelpDeskCSClientUserCodeEngineerDetail.cs
  
using System.ComponentModel;
private Engineer monitoredEngineer;
  
partial void EngineerDetail_InitializeDataWorkspace(
    List<IDataService> saveChangesTo)
{
    Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(() =>
    {
        this.Details.Properties.Engineer.Loader.ExecuteCompleted +=
            this.EngineerLoaderExecuted;                                       
    });
}
  
private void EngineerLoaderExecuted(
    object sender, Microsoft.LightSwitch.ExecuteCompletedEventArgs e)
{
  
    if (monitoredEngineer != this.Engineer)
    {
        if (monitoredEngineer != null)
        {
            (monitoredEngineer as INotifyPropertyChanged).PropertyChanged -=
                this.EngineerChanged;
        }
  
        monitoredEngineer = this.Engineer;                                         
        if (monitoredEngineer != null)
        {
            (monitoredEngineer as INotifyPropertyChanged).PropertyChanged +=
                this.EngineerChanged;
  
            //set the initial visibility here
            this.FindControl("SecurityGroup").IsVisible =
                monitoredEngineer.SecurityVetted;
        }
    }
}
  
private void EngineerChanged(
    object sender, PropertyChangedEventArgs e)
{
    if (e.PropertyName == "SecurityVetted")
    {
        this.FindControl("SecurityGroup").IsVisible =
            monitoredEngineer.SecurityVetted;                                      
    }
}

Working with Files

You can use the LightSwitch table designer to define properties with a data type of binary. By using this data type, you can allow users to store and retrieve files. However, LightSwitch doesn’t include a built-in control that allows users to upload and download files. Instead, you need to write your own code that uses the Silverlight File Open and Save File dialog boxes.

VB:
File:HelpDeskVBClientUserCodeCreateNewIssueDocument.vb
  
Imports System.Windows.Controls
Imports Microsoft.LightSwitch.Threading
  
Private Sub UploadFileToDatabase_Execute()

    '1 Invoke the method on the main UI thread                                
    Dispatchers.Main.Invoke(
        Sub()
  
            Dim openDialog As New Controls.OpenFileDialog                     
            openDialog.Filter = "All files|*.*"
            'Use this syntax to only allow Word/Excel files
            'openDialog.Filter = "Word Files|*.doc|Excel Files |*.xls"
  
            If openDialog.ShowDialog = True Then
                Using fileData As System.IO.FileStream =
                    openDialog.File.OpenRead
  
                    Dim fileLen As Long = fileData.Length
  
                    If (fileLen > 0) Then
                        Dim fileBArray(fileLen - 1) As Byte
                        fileData.Read(fileBArray, 0, fileLen)                 
                        fileData.Close()
  
                        Me.IssueDocumentProperty.IssueFile = fileBArray       
                        Me.IssueDocumentProperty.FileExtension =
                            openDialog.File.Extension.ToString()
                        Me.IssueDocumentProperty.DocumentName =
                            openDialog.File.Name
  
                    End If
  
                End Using
            End If
  
        End Sub)
  
End Sub
     
C#:
File:HelpDeskCSClientUserCodeCreateNewIssueDocument.cs
  
using System.Windows.Controls;
using Microsoft.LightSwitch.Threading;
  
partial void UploadFileToDatabase_Execute()
{
    //1 Invoke the method on the main UI thread                               
    Dispatchers.Main.Invoke(() =>
    {
        OpenFileDialog openDialog = new OpenFileDialog();                     
        openDialog.Filter = "Supported files|*.*";
        //Use this syntax to only allow Word/Excel files
        //opendlg.Filter = "Word Files|*.doc|Excel Files |*.xls";
  
        if (openDialog.ShowDialog() == true)
        {
            using (System.IO.FileStream fileData =
                openDialog.File.OpenRead())
            {
                int fileLen = (int)fileData.Length;
  
                if ((fileLen > 0))
                {
                    byte[] fileBArray = new byte[fileLen];
                    fileData.Read(fileBArray, 0, fileLen);                            
                    fileData.Close();
  
                    this.IssueDocumentProperty.IssueFile = fileBArray;                
                    this.IssueDocumentProperty.FileExtension =
                        openDialog.File.Extension.ToString();
                    this.IssueDocumentProperty.DocumentName =
                        openDialog.File.Name;
                }
            }
        }
  
    });
}

VB:
File:HelpDeskVBClientUserCodeIssueDocumentDetails.vb
  
Imports System.Windows.Controls
Imports Microsoft.LightSwitch.Threading
  
Private Sub SaveFileFromDatabase_Execute()
  
    '1 Invoke the method on the main UI thread                               
    Dispatchers.Main.Invoke(
        Sub()
            Dim ms As System.IO.MemoryStream =
                New System.IO.MemoryStream(IssueDocument.IssueFile)
  
            Dispatchers.Main.Invoke(
                Sub()
                    Dim saveDialog As New Controls.SaveFileDialog
  
                    If saveDialog.ShowDialog = True Then                     
                        Using fileStream As Stream = saveDialog.OpenFile
                            ms.WriteTo(fileStream)                           
                        End Using
                    End If
                End Sub)
        End Sub)
  
End Sub
     
C#:
File:HelpDeskCSClientUserCodeIssueDocumentDetails.cs

using System.Windows.Controls;
using Microsoft.LightSwitch.Threading;
  
partial void SaveFileFromDatabase_Execute()
{
    //1 Invoke the method on the main UI thread                              
    Dispatchers.Main.Invoke(() =>
    {
        System.IO.MemoryStream ms =
            new System.IO.MemoryStream(IssueDocument.IssueFile);
  
        Dispatchers.Main.Invoke(() =>
        {
            SaveFileDialog saveDialog = new SaveFileDialog();
  
            if (saveDialog.ShowDialog() == true)                                     
            {
                using (Stream fileStream = saveDialog.OpenFile())
                {
                    ms.WriteTo(fileStream);                                          
                }
            }
        });
    });
}

VB:
File:HelpDeskVBClientUserCodeIssueDocumentDetails.vb
  
Imports System.Windows.Controls
Imports Microsoft.LightSwitch.Threading
Imports System.Runtime.InteropServices.Automation
  
Private Sub OpenFileFromDatabase_Execute()

   Try
      If (AutomationFactory.IsAvailable) Then
         'here's where we'll save the file
         Dim fullFilePath As String =
            System.IO.Path.Combine(
               Environment.GetFolderPath(
                  Environment.SpecialFolder.MyDocuments),
                     IssueDocument.DocumentName)                               
  
         Dim fileData As Byte() = IssueDocument.IssueFile.ToArray()

         If (fileData IsNot Nothing) Then
            Using fs As New FileStream(
                  fullFilePath, FileMode.OpenOrCreate, FileAccess.Write)
               fs.Write(fileData, 0, fileData.Length)                          
               fs.Close()
            End Using
         End If
  
         Dim shell = AutomationFactory.CreateObject("Shell.Application")
         shell.ShellExecute(fullFilePath)                                      
  
      End If
   Catch ex As Exception
       Me.ShowMessageBox(ex.ToString())
   End Try
  
End Sub
  
C#:
File:HelpDeskCSClientUserCodeIssueDocumentDetails.cs
  
using System.Runtime.InteropServices.Automation;
  
partial void OpenFileFromDatabase_Execute()
{
    try
    {
        if ((AutomationFactory.IsAvailable))
        {
            //this is where we'll save the file
            string fullFilePath = System.IO.Path.Combine(
                Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments),
                IssueDocument.DocumentName);                                      
  
            byte[] fileData = IssueDocument.IssueFile.ToArray();
  
            if ((fileData != null))
            {
                using (FileStream fs =
                    new FileStream(
                        fullFilePath, FileMode.OpenOrCreate, FileAccess.Write))
                {
                    fs.Write(fileData, 0, fileData.Length);                       
                    fs.Close();
                }
            }
  
            dynamic shell = AutomationFactory.CreateObject("Shell.Application");
            shell.ShellExecute(fullFilePath);                                     
        }
    }
    catch (Exception ex)
    {
        this.ShowMessageBox(ex.ToString());
    }
}

Summary

This chapter showed you how to enrich your Silverlight applications by employing advanced screen design techniques.

When you’re building a LightSwitch application, you can’t just add UI controls to a screen. A screen consists of controls that data-bind to properties. To display a new control that’s unrelated to the main data on your screen, you have to first add a local property that backs your control. You can use the Add Data Item dialog to do this. In addition to adding local properties with this dialog, you also can add queries and methods. Adding a query to your screen allows you to show additional collections of data on your screen. You also can use queries to customize the choices that an autocomplete box or modal window picker shows. Another important feature of local properties is that you can set them up as parameters. This allows you to pass values to a screen when it opens.

Chapter 4 showed you the screen events you can handle. You use these events to run code when a screen opens, closes, or performs a save operation. If you want to run code when a change in data occurs, you can do this by handling the PropertyChanged event for your entity.

By using the LightSwitch API, you can access entity and property values by name. When you change the value of a property in code, LightSwitch automatically refreshes all controls bound to your property. With the FindControl method, you can access a specific control in code. This method returns an IContentItemProxy object that you can use to set the visibility and read-only properties of a control. Once you obtain a reference to an IContentItemProxy, you can add an event handler for the ControlAvailable event. The code that handles the ControlAvailable event allows you to access the underlying Silverlight control and add additional event handlers to handle the events that the Silverlight control raises. This allows you, for example, to handle a text box’s KeyUp event.

LightSwitch applications are multithreaded. This improves your application’s performance because it allows a screen logic thread to perform data operations, while a main UI thread deals with updating your user interface. In general, you don’t need to worry too much about executing code on a specific thread. But on the rare occasions where this is necessary, you can achieve this by using a dispatcher object.

This chapter contains plenty of screen design examples. These examples include how to create a combined add/edit screen, how to create a custom search screen, and how to create a screen for managing single-row tables. You also saw demonstrations of how to create nested autocomplete boxes, how to work with recursive data, and how to allow users to upload and download files.

A combined data entry and edit screen saves you from having to create and maintain two separate screens. To create such a screen, you begin with a Details Screen template and use the default query to populate a local property. You then bind your screen controls to the local property.

By default, the data entry screens that open from the data grid are autogenerated and can’t be modified. You can overcome this limitation by creating your own modal windows and attaching them to commands on your data grid. To allow users to select multiple rows in a data grid, you write code that sets the data grid’s DataGridSelectionMode property to Extended.

Nested autocomplete boxes (ACBs) make it easier for users to find or enter data. For example, you could limit user choices in an ACB to the department that’s been selected in a parent ACB. To do this, you set the data source of your users’ ACB to a parameterized query that’s bound to your parent ACB.

Finally, you learned how to upload and download files by using Silverlight’s OpenFileDialog and SaveFileDialog controls. In a desktop application, you can allow users to open files in their native applications. To accomplish this, you save the file locally and use the Windows Shell command to open the file.