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. The source code comes in a ZIP file titled SourceGrid_4_40_src.zip. A few people in the OpenPetra team have this file although it is not kept in our repository, due to its size.

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 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. Although the method itself contains very few lines of code, the call to ValidateAllData executes code that is very complex and potentially re-entrant, so 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 simply consists of:

    ShowDetails();

although, as we shall see in a moment, this is contained inside a simple IF statement.

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 not cancel any of 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! Likewise, if you get three events for invalid data, you must cancel the first and throw away (ignore) the other two. So 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 within 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. In this case it is possible to get a FocusedRowChanged event without a FocusRowLeaving event! In this case it would 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.

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;
    }

Handling a Sorted Grid

When a grid has sort headers, the highlighted row needs to change when the sort direction is changed, so that the same data row is selected. 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, as you will see in the code above.

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 FocusRowLeaving and FocusedRowChanged events 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.

This code snippet shows the line that selects the most recently added table row:

    SelectDetailRowByDataTableIndex(FMainDS.PInternationalPostalType.Rows.Count - 1);

This method calls the following underlying method

    private void SelectRowInGrid(int ARowIndex)
    {
        int nPrevRowChangedRow = FPrevRowChangedRow;
        grdDetails.SelectRowInGrid(ARowIndex, true);
        if (nPrevRowChangedRow == FPrevRowChangedRow)
        {
            // No row change occurred, so we still need to show details, because the data may be different
            ShowDetails();
        }
    }

You can see that grdDetails.SelectRowInGrid will normally result in firing our RowLeaving and RowChanged events, which would update the details, but there is a special case where the new row is at the same place in the grid as the 'old' row and in that case we make our own call to ShowDetails().

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 code snippet from ValidateAllData that manages the consequences of the row moving to a new location in the sorted grid as data is changed by the user in the details panel.

            int prevRowChangedRowBeforeValidation = FPrevRowChangedRow;
            GetDetailsFromControls(FPreviouslySelectedDetailRow);
            ValidateDataDetails(FPreviouslySelectedDetailRow);

            // Validation might have moved the row, so we need to locate it again
            // If it has moved we will call SelectRowInGrid (with events) to highlight the new row.
            // This will result in us getting called a second time (from FocusedRowLeaving), but the move will not be repeated a second time.
            // We thus avoid a cyclic loop and a stack overflow, yet never need to turn events off, or make a move without events
            // Note that we can (and must) set FPrevRowChangedRow here only because validation never actually changes the row object or the displayed details.
            FPrevRowChangedRow = grdDetails.DataSourceRowToIndex2(FPreviouslySelectedDetailRow) + 1;
            if (FPrevRowChangedRow != prevRowChangedRowBeforeValidation)
            {
                grdDetails.SelectRowInGrid(FPrevRowChangedRow, true);
            }

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 all of the following

• 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 Client | MPersonnel | 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. 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 Save button in the toolbar is enabled.
   4. Close the window without saving your changes.
   5. 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. Close the window without saving your changes.
   3. Errors: it is an error if the row does not appear inside the view-port, or the focus is not on the code control.
7. Creating new rows in a sorted grid (1)
   1. Reload the screen, click the Sort Header twice on the first column so that the items are sorted Z at the top and A at the bottom. Click New twice to create 2 new rows. Confirm that
      1. The two rows have been inserted into the grid correctly
      2. the second inserted row is the upper of the two and that the details panel shows the details for this second row.
      3. the CODE in the details panel has the focus
   2. Highlight a different row, then click New again. Confirm that the new row is highlighted and its correct details displayed.
   3. Close the window without saving your changes.
   4. Errors: There are numerous possible errors that can occur if there are mistakes in the code. The wrong row might be highlighted; the wrong details may be displayed; the focus may be incorrect.
8. Creating new rows in a sorted grid (2)
   1. Reload the screen, click the Sort Header twice on the second column so that the Description items are sorted Z at the top and A at the bottom. Click New twice to create 2 new rows. Confirm that
      1. The two rows have been inserted into the grid correctly
   2. Repeat, creating new rows but editing the description so that the rows are in different parts of the grid.
   3. Close the window without saving your changes.
   4. Errors: Look for the same class of error as when the first column was sorted.
9. Adding invalid rows to a sorted grid (1)
   1. Reload the screen, click the Sort Header twice on the first column so that the Code items are sorted Z at the top and A at the bottom. Click New once to create a new row in the middle of the grid. The CODE text box will have the focus, so without doing anything with the mouse or keyboard simply press the DEL key to make the CODE go blank. Now press TAB. Confirm that
      1. the highlighted row has jumped to the bottom (blank comes before A)
      2. the validation tooltip has shown invalid data
      3. the focus is now on the Description textbox
      4. all the other data entry details match the highlighted grid row information
   2. Now, using the mouse, click the New button. Confirm that
      1. a message box pops up notifying you of invalid data
   3. Close the box and confirm that
      1. the focus is now on the CODE text box once more
   4. Press CTRL+Z and confirm that
      1. the previous value of the CODE is restored
   5. Now press TAB to move to the description. Confirm that
      1. the highlighted row moves back into the middle region of the grid
   6. Close the window without saving your changes.
   7. Errors: There are numerous errors that can occur when the underlying code is wrong. These errors include the wrong row being highlighted, the wrong control being focussed and wrong information being displayed in the details panel.
10. Adding invalid rows to a sorted grid (2)
    1. You can repeat the previous test using a sorted second (Description) column, this time TABbing to the Description field and pressing DEL so that it becomes blank and the TABbing once more. Look for all the same errors. This time, instead of using CTRL+Z to restore the original text, simply edit it to a different value and confirm that it finds the correct location in the grid.
    2. Close the window without saving your changes.
11. Checking the Horizontal Scrollbar
    1. Reload the screen and resize the width so that a horizontal scrollbar appears at the bottom of the grid. Now resize the height so that there is enough room for one more row but not for two, without the second being at least partially masked.
    2. Click the New button to add a new row. Confirm that it appears and is highlighted. Now click the New button a second time. Confirm that
       1. a vertical scrollbar has been added to the grid and that the new row is entirely visible.
    3. Close the window without saving your changes.
    4. Errors: It is an error if the new row is partially hidden and no vertical scrollbar is visible.
12. Checking the Horizontal and Vertical Scrollbars
    1. Reload the screen and resize the width so that a horizontal scrollbar appears at the bottom of the grid. Then increase the width carefully until the scrollbar disappears. Now resize the height so that there is enough room for one more row but not for two, without the second being at least partially masked.
    2. Click the New button to add a new row. Confirm that it appears and is highlighted. Now click the New button a second time. Confirm that
       1. a vertical and horizontal scrollbar have been added to the grid and that the new row is entirely visible and so that you can scroll horizontally to see all the columns. The horizontal scrollbar had to be added because the vertical scrollbar covered the right hand edge of the right-most column. You might have to fiddle with the window width a few times to see this effect, because the grid column widths change with the overall width.
    3. Close the window without saving your changes.
    4. Errors: It is an error if the new row is partially hidden and no vertical scrollbar is visible, or if part of a column is not visible and there is no horizontal scrollbar.
13. Deleting Rows from the Grid
    1. Reload the screen and without sorting add five new rows, which will appear at the bottom of the grid. With the bottom row selected, click the Delete button and accept the message boxes. Confirm that
       1. the bottom row was deleted
       2. the new highlighted row is the new bottom row
       3. the details panel shows the details for the bottom row
    2. Now select the row one up from the bottom and click the Delete button once more. Confirm that
       1. the highlighted row was deleted
       2. the highlighted row index did not change, but the data has changed to the row that was at the bottom before the delete.
       3. the details panel shows the correct data.
    3. With these two tests you have covered the cases where the last row is deleted and where the deleted row has at least one row below.
    4. Close the window without saving your changes.
    5. Errors: It is an error if the wrong row is deleted, or if the highlight is wrong after deleting the row, or if the details after the delete do not match the information in the highlighted row.

Tests Using Contact Attributes

All of the tests conducted on International Postal Type can apply to the Contact Attributes screen, but there are additional tests that are important because the screen has some complex features. The information displayed in the lower grid depends on the row selected in the upper grid. It is not 'allowed' to have an empty lower grid, so when a new row is created in the upper grid the manual code automatically creates the first row in the lower grid as well.

It is important to start these tests with an empty database table, so please use your administration tool to delete all rows from p_contact_attribute and p_contact_attribute_detail before you start. Normally the demo database has no data in these tables.

1. Initial Load
   1. Load the screen and visually check that the grids are empty and that both details panels are disabled. Check that the grid has the initial focus by pressing TAB: the New button should now be focussed. Continue TABbing and check that all the controls that are enabled get the focus in turn.
   2. Errors: It is an error if, for example, the details panel is not disabled.
2. Adding Rows Using the Keyboard (1)
   1. Reload the screen, TAB to the New button and press SPACE. Confirm that
      1. a new row is added
      2. the focus is on the NEWCODE for the upper grid
      3. a new row is added to the lower grid
      4. both details panels match the highlighted grid rows
   2. Edit the code and continue editing/TABbing until you reach the New button for the lower grid. Press SPACE. Confirm that
      1. a new row is added to the lower grid
      2. the focus is on the CODE for the lower panel
      3. all the details match the grids
   3. Close the window without saving your changes.
   4. Errors: It is an error if the focus is on the wrong control, or if you cannot TAB round all the controls in sequence. It is an error if the highlighted grid information is not the same as its corresponding details panel.
3. Adding Rows Using the Keyboard (2)
   1. Reload the screen, but this time add rows to the top grid by pressing INS three times. Confirm that
      1. three rows got added to the upper grid, each having one row in the lower grid
      2. the focus is still on the upper grid
   2. Now TAB to the lower grid and press the INS key twice. Confirm that
      1. the lower grid now has three rows for the selected row in the upper grid
      2. the lower grid still has the focus
   3. SHIFT+TAB back to the upper grid again and use the Up/Down arrow keys to move through the rows. Confirm that
      1. two upper grid rows have just one lower grid row, while the third one has three rows.
   4. Close the window without saving your changes.
   5. Errors: It is an error if the focus is on the wrong control, or if you cannot TAB round all the controls in sequence, or use the arrow keys to select different rows. It is an error if the highlighted grid information is not the same as its corresponding details panel.
4. Adding Rows Using the Mouse
   1. Reload the screen, but this time add three rows to the top grid by clicking the New button three times. Confirm that
      1. the upper grid has three rows
      2. the focus is on the CODE for the upper grid
      3. there is one row in the lower grid
      4. all the details are correct for the highlighted grid rows
   2. Click the New button for the bottom grid three times. Confirm that
      1. the lower grid has four rows
      2. the focus is on the CODE for the lower grid
      3. the details are all correct
   3. Close the window without saving your changes.
   4. Errors: It is an error if the focus is on the wrong control, or if you cannot TAB round all the controls in sequence, or use the arrow keys to select different rows. It is an error if the highlighted grid information is not the same as its corresponding details panel.
5. Deleting Rows
   1. Background: If you delete a row from the upper grid, all the associated rows in the lower grid are also deleted. If you delete a row in the lower grid it has no effect on the upper grid, except that the column that shows the number of detail attributes will change.
   2. Repeat each of the tests above (keyboard and mouse) and create, say three rows in the upper grid each with a different number of rows in the lower one.
   3. Now TAB or SHIFT+TAB to each of the Delete buttons in turn and press SPACE. Check the correct row(s) are deleted. Or just click the Delete buttons with the mouse.
   4. Do this on the first row in a grid and the last row in a grid.
   5. Continue deleting until all the rows have been deleted.
   6. Repeat this test multiple times in different ways
   7. In all these tests confirm that
      1. the correct row is deleted
      2. the focus remains on the relevant grid
      3. the details panel always matches the grid
   8. Close the window without saving your changes.
6. Editing the Contact Attribute Code
   1. Background: If you change the CODE for the upper grid, you also modify a field in the table associated with the lower grid. If this doesn't work right you can appear to 'lose' the details for the attribute you just edited.
   2. Reload the screen and create a few attributes rows in the upper grid.
   3. Add a few details in the lower grid for each of these attributes.
   4. Be sure that you know the values for the details corresponding to a particular attribute, by editing them to something unique.
   5. Highlight, say, the second or third detail attribute in the lower grid.
   6. Go to the text box for the upper grid's CODE and edit it to be a different value, then TAB to the next control. Confirm that
      1. the new code value has been entered into the upper grid
      2. the lower grid content has not changed
      3. the lower grid selection has not changed
   7. Close the window without saving your changes.
   8. Errors: when you change the attribute code the detail table has to be updated and the content for the grid re-filtered. This should not change the result set to be displayed but this is a good test of several grid display issues. It is an error if the lower grid content changes or the highlighted row changes.