SourceGrid specification and testing

OpenPetra makes extensive use of the SourceGrid control available from http://sourcegrid.codeplex.com/. This open source control has many desirable features and is a fairly complex piece of code written by David Icardi. We currently use version 4.40 published on 16 July 2012.

With the exception of the two bugs described below, we are able to use this control 'out-of-the-box'. However, using the control successfully requires some careful programming and some knowledge of how the events that are fired by the control can best be used by OpenPetra.

First we will explain the two bug fixes, then we will examine how to code for the events that we use. In the third section we outline some of the commonest methods associated with the grid that you will want to use in your manual code. In the final section we will describe how to test that any changes that are made to the grid or to validation have not caused new bugs to appear.

Bug Fixes

Unfortunately the grid contains two bugs that we have discovered and corrected.

The first relates to auto-sizing the grid columns and the second relates to the code that makes the horizontal and vertical scrollbars visible.

Auto-Sizing the Grid Columns

When the screen is resized, the grid also resizes and the column widths change to try and show as much useful information as possible. Earlier versions of the grid had a behaviour in this respect that we prefer to the later implementation, so we make a small change to preserve the previous behaviour. If a column has no data, we prefer that the column never shrinks to a size less than the text in the header for that column. So we make the following change to AutoSizeView() inside ColumnInfoCollection.cs.

   List<int> list = Grid.Rows.RowsInsideRegion(Grid.DisplayRectangle.Y, Grid.DisplayRectangle.Height, true, false);       

becomes

   List<int> list = Grid.Rows.RowsInsideRegion(Grid.DisplayRectangle.Y, Grid.DisplayRectangle.Height);       

This has the effect of including the header row in the list of visible rows, whose text widths need consideration.

Automatic positioning of the Two ScrollBars

Particularly when a horizontal scrollbar is already present on the grid, the standard code does not make a good job of displaying the vertical scrollbar correctly. As a consequence it is possible for a new row to be 'hidden' behind the horizontal scrollbar with no means of scrolling the view-port to make it visible. It is also possible for the horizontal scrollbar not to be displayed when it should be.

In order to correct this we have the following code for the RecalcCustomScrollBars() method in CustomScrollControl.cs.

	/// <summary>
	/// Recalculate the scrollbars position and size.
	/// Use this to refresh scroll bars
	/// </summary>
	public void RecalcCustomScrollBars()
	{
            SuspendLayout();

            /////////////////////////////////////////////////////////////////////
            //ALAN
            if (GetScrollColumns(base.DisplayRectangle.Width) > 0)
            {
                // we definitely need a HScroll based on the base display rectangle
                PrepareScrollBars(true, false);
                if (GetScrollRows(DisplayRectangle.Height) > 0)
                {
                    // we need a VScroll too
                    PrepareScrollBars(true, true);
                }
            }
            else
            {
                // we don't need an HScroll (yet)
                if (GetScrollRows(base.DisplayRectangle.Height) > 0)
                {
                    // we definitely need a VScroll based on the base display rectangle
                    PrepareScrollBars(false, true);
                    if (GetScrollColumns(DisplayRectangle.Width) > 0)
                    {
                        // actually now we need an HScroll after all, because the VScroll has taken up space
                        PrepareScrollBars(true, true);
                    }
                }
                else
                {
                    // No scrolls needed - everything fits in the base display rectangle
                    PrepareScrollBars(false, false);
                }
            }

            //Finally I read the actual values to use (that can be changed because I have called PrepareScrollBars)
            if (VScrollBarVisible)
            {
                int scrollRows = GetScrollRows(DisplayRectangle.Height);
                scrollRows = scrollRows - GetActualFixedRows();
                RecalcVScrollBar(scrollRows);
            }
            if (HScrollBarVisible)
            {
                int scrollCols = GetScrollColumns(DisplayRectangle.Width);
                RecalcHScrollBar(scrollCols);
            }

	    //forzo un ridisegno
	    InvalidateScrollableArea();

	    ResumeLayout(true);
	}

Handling Grid Events in OpenPetra Code

Almost everywhere that we use a grid control we hook up two key events: FocusRowLeaving and FocusedRowChanged. The FocusRowLeaving event has the possibility to programatically cancel the row change. Once FocusedRowChanged happens the code has to respond to the fact that the grid selection has changed.

The comments that follow describe the code that gets auto-generated, so normally you will not have to worry about coding anything in the manual code. However, in a few places it is possible that you cannot use auto-generated code and in that case you should manually code your screen according to these guidelines. In fact the best course of action would be to copy an example of the auto-generated code into your own manual code.

Inside the FocusRowLeaving Event

The only action that we might take inside this event handler is to cancel the RowLeaving because the current data entered fails validation. So this event handler contains the line:

    if (!ValidateAllData(true, true))
    {
        e.Cancel = true;
    }

This call to ValidateAllData is the one that will show a message box to the user that there are uncorrected errors in the data entry and that he cannot leave the row until these have been fixed.

It is worth stating here that it is important to be very aware of all the code that runs during the FocusRowLeaving event - it is quite easy to do something in validation that will cause another FocusRowLeaving event to occur, which, if not handled correctly will lead to a stack overflow.

Inside the FocusedRowChanged Event

Once the row has changed, the only thing that we normally do is to be sure that we show the details of the current row in the matching data entry controls. So this event handler will certainly contain:

    ShowDetails();

That's all we have to do in response to a row change.

Handling Multiple Events

This is the most difficult issue for OpenPetra programmers in respect of the grid. Although these simple lines of code are all that we need inside each of these two methods, the complexity arises because both of these events can be fired multiple times for what would seem to be a single row change. In particular the RowLeaving event can be fired 3 or even 4 times. This is down to the specific implementation of code within the grid DLL and is partly (or mainly) explained by the fact that it gets fired both by a cell leaving and row leaving event as each cell is validated. So the big question becomes: how to deal with multiple event calls for what is in essence the same user action?

The first thing to say, perhaps counter-intuitively, is that it is wrong to cancel a duplicate event, just because it is a duplicate. If you get 3 events for a particular row that contains good data, you must just throw away the two duplicates and not cancel them. Please take my word for it that if you do cancel them the code will appear to work but those cancelled events will come back to bite you later!

Now the important point to understand is that if you get multiple leaving events, you must only make the call to validate data once. If you get this wrong, you will soon realise it because on a row with errors you will get multiple identical Invalid Data message boxes popping up one after the other!

We have two strategies for handling multiple RowLeaving events. In the first case we never respond to an event in which the new, proposed row is -1. This is really just a cell leaving event and not a row leaving one. The second case, where the proposed row seems valid is literally to keep track of the time delay between consecutive events. If the current and proposed rows are the ones we had last time and the event is with 2 milliseconds of the previous event, we regard it as a duplicate and throw the event away. Two milliseconds for a computer is a very long time but still much shorter than, say, any keyboard repeat time.

Although the FocusedRowChanged event does not cascade like the leaving event, it is still possible to get duplicates as the user tabs around the screen and it may not be a good idea to copy the details back from the grid to the data entry controls (because while the user is tabbing around the controls should update the grid and not the other way around). So once again we need protection to only go grid->controls once on a particular row.

Handling a Sorted Grid

When a grid has sort headers, the highlighted row needs to change when the sort direction is changed. The grid is set up with a property that means that it handles the row highlighting automatically in this case; we simply get notified that the FocusedRow has changed. Since this is not a row data change there is nothing for us to do, and we ignore the event.

However, when a new row is added into a sorted grid, its position is unlikely to be the last row, which it always is on an unsorted grid. So we have to find the position of the new row and highlight that one. This normally gives rise to further FocusRowLeaving and FocusedRowChanged events (with different FromRow/ToRow) and everything works as you would expect - the details get shown for the new row. However there is a special case where the selected row prior to the New button being pressed is the same row as where the new row ends up. In that case we do NOT get any RowLeaving or RowChanged events (because the row number is unchanged) - but we have to make sure that the details in the data entry controls are updated for the new row's data.

Handling Validation

Row data validation has introduced new complexities into the event handling mix. The way that validation works is that most data entry controls now have a validated event handler which has the effect of updating the grid column for that row as the user tabs away from the control - typically a text box or combo box. If the column for that data entry control is sorted, the position of the row will change (but not the highlight unless we do that programatically). The validation routine needs to be the only place where we transfer data entry values into the grid. This is typically with the method GetDetailsFromControls(ARow). You should never call this method outside of a validation routine because, if you do, you will by-pass the possibility of handling erroneous data. So the validation routine becomes the single place where a data row might move to a different location in the grid, and inside the routine we need to 'find' the row after every call to GetDetailsFromControls(). If it has moved we need to highlight the new position, which itself will cause further RowLeaving and RowChanged events. The RowLeaving event will trigger another call to the validation routine, which needs to respond to that event as well.

So you can see that when we use a sorted grid and we change the data in the sorted column we will get multiple events that we need to respond to, because when you glue them together you see the history of where the row started and where it ended up. With careful programming we can capture all the correct events and respond in a completely standard way. Please understand that in the generated code we never 'turn off' any events, nor do we ever 'cancel' any (see above), but we do 'ignore' genuine duplicates, as explained above.

Here is the complete code for FocusRowLeaving:

    /// FocusedRowLeaving can be called multiple times (e.g. 3 or 4) for just one FocusedRowChanged event.
    /// The key is not to cancel the extra events, but to ensure that we only ValidateAllData once.
    /// We ignore any event that is leaving to go to row # -1
    /// We validate on the first of a cascade of events that leave to a real row.
    /// We detect a duplicate event by testing for the elapsed time since the event we validated on...
    /// If the elapsed time is < 2 ms it is a duplicate, because repeat keypresses are separated by 30 ms
    /// and these duplicates come with a gap of fractions of a microsecond, so 2 ms is a very long time!
    /// All we do is store the previous row from/to and the previous UTC time
    /// These three form level variables are totally private to this event call.
    private void FocusRowLeaving(object sender, SourceGrid.RowCancelEventArgs e)
    {
        if (!grdDetails.Sorting && e.ProposedRow >= 0)
        {
            double elapsed = (DateTime.UtcNow - FDtPrevLeaving).TotalMilliseconds;
            bool bIsDuplicate = (e.Row == FPrevLeavingFrom && e.ProposedRow == FPrevLeavingTo && elapsed < 2.0);
            if (!bIsDuplicate)
            {
                if (!ValidateAllData(true, true))
                {
                    e.Cancel = true;
                }
            }
            FPrevLeavingFrom = e.Row;
            FPrevLeavingTo = e.ProposedRow;
            FDtPrevLeaving = DateTime.UtcNow;
        }
    }

Here is the complete code for FocusedRowChanged:

    /// <summary>
    /// This variable is managed by the generated code.  It is used to manage row changed events, including changes that occur in data validation on sorted grids.
    /// Do not set this variable in manual code.
    /// You may read the variable.  Its value always tracks the index of the highlighted grid row.
    /// </summary>
    private int FPrevRowChangedRow = -1;
    private void FocusedRowChanged(System.Object sender, SourceGrid.RowEventArgs e)
    {
        // The FocusedRowChanged event simply calls ShowDetails for the new 'current' row implied by e.Row
        // We do get a duplicate event if the user tabs round all the controls multiple times
        // It is not advisable to call it on duplicate events because that would re-populate the controls from the table,
        //   which may not now be up to date, so we compare e.Row and FPrevRowChangedRow first.
        if (!grdDetails.Sorting && e.Row != FPrevRowChangedRow)
        {
            ShowDetails();
        }
        FPrevRowChangedRow = e.Row;
    }

Adding and Deleting Rows Using the Keyboard

The grid now responds to the INS and DEL key presses on the keyboard and attempts a row insert and delete respectively. To do this, it looks for the existence on the form of buttons called btnNew and btnDelete and executes their click event accordingly. To access this functionality, you obviously need the buttons named correctly, but this doesn't stop you changing the label of the button if New or Delete do not best fit the form's context, e.g. the GL Batch form uses buttons with labels Add and Cancel.

Here is a typical yaml file section for the two buttons:

Actions:
	actNew: {Label=&New, ActionClick=NewRecord}
	actDelete: {Label=&Delete, ActionClick=DeleteRecord}
Controls:
	pnlContent:
		Controls: [pnlGrid, pnlDetails]
		Dock: Fill
	pnlGrid:
		Dock: Fill
		Controls: [grdDetails, pnlButtons]
	pnlButtons:
		Dock: Right
		Controls: [btnNew, btnDelete]
	btnNew:
		Action: actNew
	btnDelete:
		Action: actDelete

And then in the manual code, you call the generated code to create/delete a record:

private void NewRecord(Object sender, EventArgs e)
{
	CreateNewPInternationalPostalType();
}

private void DeleteRecord(Object sender, EventArgs e)
{
	DeletePInternationalPostalType();
}

Common Code Tasks

The auto-generated code handles everything to do with the most common grid tasks, including sorting and validation. Even so, your manual code will still need to know which row is selected or to highlight a specific row in response to a row filter change, for example.

Discovering the Current Row

There are two methods to access the current row.

The first one returns the row as a typed data row object so you can access the underlying content. This is taken from the InternationalPostalType screen.

    /// <summary>
    /// Gets the highlighted Data Row as a PInternationalPostalType record from the grid
    /// </summary>
    /// <returns>The selected row - or null if no row is selected</returns>
    public PInternationalPostalTypeRow GetSelectedDetailRow()

The second returns the index of the row in the grid, where 0 corresponds to the header row and 1 is the first row of data.

   int nSelectedRow = grdDetails.SelectedRowIndex();

Selecting a Row

There is a simple method to select a specific row in the grid. This one call does many things.

    /// <summary>
    /// Selects the specified grid row and shows the details for the row in the details panel.
    /// The call still works even if the grid is empty (in which case no row is highlighted).
    /// Grid rows holding data are numbered 1..DataRowCount.
    /// If the specified grid row is less than 1, the first row is highlighted.
    /// If the specified grid row is greater than DataRowCount, the last row is highlighted.
    /// The details panel is disabled if the grid is empty or in Detail Protect Mode
    ///    otherwise the details are shown for the row that has been highlighted.
    /// </summary>
    /// <param name="ARowIndex">The row index to select.  Data rows start at 1</param>
    private void SelectRowInGrid(int ARowIndex)

As the comment indicates, the single parameter is the row that you want to select, where the first data row is number 1.

This method call does a number of things

• Forces the specified row to be within the range 1..RowCount
• Highlights the row
• Ensures that the specified row is visible in the view-port, scrolling the grid if necessary. If possible there will be at least one other visible row above and below the selected row.
• Shows the details for the row
• Enables the grid panel unless the grid is empty or in detail protect mode

All these actions happen automatically and are driven by single RowLeaving and RowChanged events as described above.

If you have manual row addition or deletion code, you can simply call this one method and the nearest available row will be selected and its details displayed. SelectRowInGrid is a powerful method that does everything you need to highlight a row and show all its details.

Showing the Details for the Current Row

A simple call to ShowDetails() shows the details for the currently selected row. There is no need to call this if you have already called SelectRowInGrid(ARowIndex), because that method already calls it.

    /// <summary>
    /// This overload shows the details for the currently highlighted row.
    /// The method still works when the grid is empty and no row can be selected.
    /// The Details panel is disabled when the grid is empty, or when in Detail Protected Mode
    /// The variable FPreviouslySelectedDetailRow is set by this call.
    /// </summary>
    private void ShowDetails()

Adding Rows

Standard code for adding rows is part of the templates. An appropriate new record is added to the database and the new row is highlighted - bearing in mind that we have to locate it in the grid. It will not be the last row if the grid is sorted. Usually there is a small requirement for manual code when adding a row, in order to ensure that the new row has a unique primary key.

Deleting Rows

The code for deleting rows is now in the templates. In the simplest case the manual code only needs to handle the button click event and call the standard auto-generated code method. For the InternationalPostalType screen the method is DeletePInternationalPostalType().

The auto-generated Delete{#DETAILTABLE} procedure can call up to 3 optional manual code methods that control the deletion process. If you want more control over the deletion process than is provided by the generic code, then you can include your own variant of any or all of the following in your manual code file.

/// <summary>
/// Performs checks to determine whether a deletion of the current
///  row is permissible
/// </summary>
/// <param name="ARowToDelete">the currently selected row to be deleted</param>
/// <param name="ADeletionQuestion">can be changed to a context-sensitive deletion confirmation question</param>
/// <returns>true if user is permitted and able to delete the current row</returns>
private bool PreDeleteManual(PInternationalPostalTypeRow ARowToDelete, ref string ADeletionQuestion)
{
	/*Code to execute before the delete can take place*/
	ADeletionQuestion = String.Format(Catalog.GetString("Are you sure you want to delete Postal Type Code: '{0}'?"),
					  ARowToDelete.InternatPostalTypeCode);
	return true;
}

/// <summary>
/// Deletes the current row and optionally populates a completion message
/// </summary>
/// <param name="ARowToDelete">the currently selected row to delete</param>
/// <param name="ACompletionMessage">if specified, is the deletion completion message</param>
/// <returns>true if row deletion is successful</returns>
private bool DeleteRowManual(PInternationalPostalTypeRow ARowToDelete, out string ACompletionMessage)
{
	bool deletionSuccessful = false;
	
	try
	{
		//Must set the message parameters before the delete is performed if requiring any of the row values
		ACompletionMessage = String.Format(Catalog.GetString("Postal Type Code: '{0}' deleted successfully."),
						   ARowToDelete.InternatPostalTypeCode);
		ARowToDelete.Delete();
		deletionSuccessful = true;
	}
	catch (Exception ex)
	{
		ACompletionMessage = ex.Message;
		MessageBox.Show(ex.Message,
				"Deletion Error",
				MessageBoxButtons.OK,
				MessageBoxIcon.Error);
	}
	
	return deletionSuccessful;
}

/// <summary>
/// Code to be run after the deletion process
/// </summary>
/// <param name="ARowToDelete">the row that was/was to be deleted</param>
/// <param name="AAllowDeletion">whether or not the user was permitted to delete</param>
/// <param name="ADeletionPerformed">whether or not the deletion was performed successfully</param>
/// <param name="ACompletionMessage">if specified, is the deletion completion message</param>
private void PostDeleteManual(PInternationalPostalTypeRow ARowToDelete, bool AAllowDeletion, bool ADeletionPerformed, string ACompletionMessage)
{
	/*Code to execute after the delete has occurred*/
       	if (ADeletionPerformed && ACompletionMessage.Length > 0)
       	{
       		MessageBox.Show(ACompletionMessage,
       		                "Deletion Completed",
       		                MessageBoxButtons.OK,
       		                MessageBoxIcon.Information);
       		
       		if (!pnlDetails.Enabled) //set by FocusedRowChanged if grdDetails.Rows.Count < 2
       		{
       			ClearControls();
       		}
       	}
	else if (!AAllowDeletion)
	{
		//message to user	
	}
	else if (!ADeletionPerformed)
	{
		//message to user
	}
}

The DeleteRowManual()'s second argument, out string ACompletionMessage (which is passed local variable completionMessage), is always sent in empty. If it is populated in the method after a successful delete and there is no PostDeleteManual() method present, then a MessageBox displaying completionMessage string will appear. If you create a PostDeleteManual() method, completionMessage is passed in as an argument.

Grid Testing

Currently, all code generated from the templates compiles and a number of basic maintain screens have been tested for correct behaviour. A small stand-alone application would be needed to test the behaviour in isolation. However any testing would need to include all the validation framework as well as addition and deletion of data and so on.

For the present time this documentation lists all the tests that need to be performed manually to ensure that the grid behaviour is correct. In the future it may be possible to automate all these tests.

The tests use two screens:

• International Postal Type (in Client | MCommon | Gui | Setup). This screen has add and delete functionality as well as manual and automatic data validation.
• Contact Attributes (in Personnel | Gui | Setup). This screen has two grids dependent on each other, row filtering and add/delete.

Each test is numbered and described and the expected outcome is explained.

Tests Using International Postal Type

The demo database already contains a useful amount of data for this screen.

1. Initial Load
   1. Load the screen and visually check that the first row in the grid is highlighted and that the details panel is showing the correct data for the first row. Check that the grid has the initial focus by pressing TAB: the 'New' button should now be focussed.
   2. Errors: It is an error if, for example, the initial highlight is on the Code in the details panel.
2. Using the keyboard to move around the screen
   1. Reload the screen. Do not touch the mouse, but use the keyboard to TAB from control to control. Confirm that each control is focussed in turn. Initially the Delete button will always be disabled because you are not allowed to delete data that is already in the database. When you have TABbed back to the grid use the up/down arrow keys to cursor through the grid rows. Ensure that the details update correctly every time. Resize the window so that you can experiment with the PgUp/PgDn keys.
   2. Errors: It is an error if, for example, TABbing from the postal code control in the details panel jumps you back to the grid.
3. Using the mouse to move around the screen
   1. Reload the screen. Repeat the previous keyboard tests using the mouse (do not click the new button yet and do not change any data). Confirm that the details panel always shows the correct data for the row that you have highlighted.
4. Using the keyboard to create new rows (1)
   1. Reload the screen, shrink the height so that not all rows can be displayed, press the TAB key once, then press SPACE. Confirm that
      1. a new row is added at the bottom and is highlighted
      2. the grid scrolls to show it
      3. the focus moves to the NEWCODE control
   2. Now edit the text for the code and press TAB. Edit the description and press TAB. Do not intentionally fail validation yet (that comes in a later test!). Keep TABbing and editing until you reach the New button again. Then press SPACE to add another row. Repeat this until you have added three new rows. Confirm that all your edits have been applied and that there was never a time where you TABbed to an unexpected control.
   3. Confirm that the Delete button is now enabled (because your new data has not yet been saved), and that you can TAB around every control, including the Delete button.
   4. Confirm that the Save button in the toolbar is enabled.
   5. Close the window without saving your changes.
   6. Errors: it is an error if the row does not appear inside the view-port, or the focus is not on the code control.
5. Using the keyboard to create new rows (2)
   1. Reload the screen, shrink the height so that not all rows can be displayed, then press the INS key twice. Confirm that
      1. two new rows have been added at the bottom
      2. the grid has scrolled to show them
      3. the focus has remained on the grid
   2. Close the window without saving your changes.
   3. Errors: In this case it is an error if the focus changes to the NEWCODE control.
6. Using the mouse to create new rows
   1. Reload the screen, shrink the height so that not all rows can be displayed, then click the New button once. Confirm that
      1. one new row has been added at the bottom
      2. the grid has scrolled to show it
      3. the focus moves to the NEWCODE control
   2. Errors: it is an error if the row does not appear inside the view-port, or the focus is not on the code control.