View source for SourceGrid specification and testing (Prior to Nov 2013)

== Important: This page refers to information that is partly out of date ==
The SourceGrid has been revised in November 2013.  The information that follows refers to the grid as used prior to that date.  You can read the [[SourceGrid specification and testing|up-to-date information here]]

== Introduction ==
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.  In the second section there is some important background information about Focus, Selection and Highlighting.  This will lead on to consideration of how to code for the events that we use.  In the fourth 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 ==
''(This section updated July 2013 - third bug fix added)''

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

The first relates to auto-sizing the grid columns; the second relates to the code that makes the horizontal and vertical scrollbars visible; the third relates to SHIFT selection of multiple rows.

=== 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.

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

becomes

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

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.

<pre>
	/// <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);
	}
</pre>

=== Using the SHIFT key to multi-select rows ===

This bug, though very simple to fix, caused a number of unwanted effects in the original code.  First, the action of pressing the SHIFT key caused a cascade of Selection_Changed events to fire, which is a very unexpected behaviour.  The noticeable effect of this was that, if you had several rows highlighted and then pressed SHIFT, the selection returned to being just the one active row.  More importantly the same bug meant that if you SHIFT+Left_Mouse_Clicked you could see a range of cells being highlighted, but then they immediately disappeared again!

The required fix is in the file GridVirtual.cs at the very end of the 'ProcessSpecialGridKey' method.

This is the ORIGINAL code
            if (shiftPressed)
            {
                Selection.ResetSelection(true);
                Selection.SelectRange(new Range(m_firstCellShiftSelected, Selection.ActivePosition), true);
            }

This is the REVISED code
            if (shiftPressed && e.Handled)
            {
                Selection.ResetSelection(true);
                Selection.SelectRange(new Range(m_firstCellShiftSelected, Selection.ActivePosition), true);
            }

It is only required to add the '&& e.Handled' to the if clause.

The behaviour becomes what you would expect.  There is now no effect of pressing the SHIFT key on its own.  When using the mouse you highlight a single row, then press SHIFT and click with the mouse.  A range is selected.  You can release the SHIFT key.  If you now press the SHIFT key again and left click in a different row you will highlight the range from the original row to the new clicked row - it doesn't matter if the click was below or above the previous selection, or inside it or outside it.

== Focus, Selection and Highlighting ==
It is important to understand the interplay between focus, selection and highlighting in the grid.  Actually the grid works the same way as most other Windows controls in that a whole row can be highlighted but there can only ever be one cell that is the cell with the focus.  Typically Windows displays the focused cell with a small dotted line border, or on more modern operating systems with a specific colour (often grey or light blue).  A highlighted row is typically shown in a dark blue colour.  There is no requirement for the focused cell to be in the same row as the highlighted (selected) row.  This has resulted in the past (when there were mistakes in our code) in having a 'stray blue cell' separate from the selected, highlighted, row.

Now it is possible programatically to set the focused cell in the grid or to un-set the focus so that no cell is focused.  However, you need to understand that if you programatically set the cell focus ''you also set the focus to the grid control itself'' so this will almost always upset the tab order for users who like to use the keyboard to enter data.

The code in the grid control DLL has been written so that when the grid itself has the focus the focused cell is automatically adjusted along with the selection highlight, but ''whenever the grid loses focus the cell focus is removed as well''.  This is actually a desirable behaviour.  When the grid does not have the focus we do not need a cell to have the focus either - we just want the selection highlight to remain.  Remember that the cell focus and row highlighting are independent functionalities.

A (good) consequence of this behaviour is that when the grid control has the focus we will get FocusRowLeaving events, because there is a focused cell to leave from; but when the grid control does not have the focus there will be no grid events and the 'active position' property of the grid will be indeterminate.  You will appreciate that when the grid does not have the focus we are much less interested in getting these events because any changes to the row selection are probably being driven by our code anyway, so we will not need an event to tell us what we know already!

So how do we manage cell focus and row highlighting?  The grid control itself removes the cell focus when the grid loses focus, but we need to make sure that the cell focus is restored when the grid control itself gets the focus back again.
<pre>
    private void grdDetails_Enter(object sender, EventArgs e)
    {
        if (FPetraUtilsObject.VerificationResultCollection.Count > 0)
        {
            // No need to focus the row if there are no errors.  This allows the user to have scrolled the view-port away from the selected row and keep it there.
            grdDetails.Selection.Focus(new SourceGrid.Position(FPrevRowChangedRow, 0), false);
        }
    }
</pre>
This snippet ensures that we do not miss the first FocusRowLeaving event after mousing onto the grid.

Note that the focus code does not include any row selection code.  Conversely our row selection code (see below) does not contain any focus code.  It is very important to keep focus and selection code separate.

=== Multi-Row Selection ===
Many of our screens now support multi-row selection, particularly in the context of deletion.  The grid control supports the following ways of highlighting multiple rows:
* Mouse clicking on a row (so it becomes the only highlighted row) and then CTRL+Left clicking on one or more contiguous or non-contiguous rows.
* Mouse clicking on a row and SHIFT dragging up or down through contiguous rows
* Using the keyboard to select a row and then SHIFT+Up arrow or SHIFT+Down arrow to select a contiguous range of rows.

The grid control does not support mouse clicking on a row and then SHIFT+Left mouse click on another row.  The reason for this is in the grid control and not in OpenPetra code.

The simplest thing is to try these different options yourself.  What you will observe is that every click (or Up/Down) '''changes the selection''' to that row - and hence shows the details for that row.  To put it another way, when you multi-select using CTRL+mouse click each click changes the details in the details panel.  But if you multi-select using click and SHIFT+drag the selected row is the first row you clicked on.  This is very standard Windows behaviour and feels entirely intuitive.

The important point to realise as a programmer is that, while the grid control maintains internal variables about the 'active cell', it does not hold any information about the '''selected''' typed data row.  It is our auto-generated Windows Form code that maintains state about the '''selected''' row.  The grid object can be queried for the '''highlighted''' rows but not for the '''selected''' row.  This impacts the way our code is designed and the methods and properties that you should use to deal with the '''selected''' row.

With that background in mind we are ready to examine in more detail how we hook up to the events that the grid makes available when it has the focus.

== 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:
<pre>
    if (!ValidateAllData(true, true))
    {
        e.Cancel = true;
    }
</pre>

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:
<pre>
    ShowDetails(e.Row);
</pre>
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:
<pre>
    /// 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 &lt; 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;
        }
    }
</pre>

Here is the complete code for FocusedRowChanged:
<pre>
    /// <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(e.Row);
        }
        FPrevRowChangedRow = e.Row;
    }
</pre>

=== 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:
<pre>
    SelectDetailRowByDataTableIndex(FMainDS.PInternationalPostalType.Rows.Count - 1);
</pre>
This method calls the following underlying method
<pre>
    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(ARowIndex);
        }
    }
</pre>
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.
<pre>
            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);
            }
</pre>

=== 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:
<pre>
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

</pre>
If the actDelete action is DeleteRecord the code generator will automatically create the DeleteRecord handler for you.  If the handler is named, say, RemoveRecord then you must create a RemoveRecord handler in manual code.  In all cases you must define the NewRecord handler in your manual code.  You will also almost always define a NewRowManual handler in which you need to find an unused set of primary key values:
<pre>
private void NewRecord(Object sender, EventArgs e)
{
	CreateNewPInternationalPostalType();
}

private void NewRowManual(PInternationalPostalTypeRow ARow)
{
	/* Initialise the fields in ARow so that they fulfil the unique table constraints */
}

/* ONLY NECESSARY IF YOUR DELETE ACTION IS NOT DeleteRecord() */
private void DeleteRecordManual(Object sender, EventArgs e)
{
	/* Do some stuff that needs to be done before calling the standard code */
	
	/* Now call the standard code */
	DeletePInternationalPostalType();
}
</pre>

== 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.
<pre>
    /// <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()
</pre>

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.
<pre>
    /// <summary>
    /// Gets the selected Data Row index in the grid.  The first data row is 1.
    /// </summary>
    /// <returns>The selected row - or -1 if no row is selected</returns>
    public Int32 GetSelectedRowIndex()
</pre>

=== Selecting a Row ===
The basic method for selecting an grid row is to specify the row number.  The underlying source grid code always uses the row index when manipulating the grid.  But you can also select a grid row by specifying the data row that you want to select.  (Only the primary key values are used to find the row.)

In your manual code you will normally select a grid row by its index.

==== Selecting the row by its row index ====
There is a simple method to select a specific row in the grid.  This one call does many things.
<pre>
    /// <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)
</pre>
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
* Validates the current row and if necessary displays a message box and cancels the row change to your desired row
* 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
* Clears the controls in the details panel if the grid is empty

All these actions happen automatically and may or may not be 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.

You can call SelectRowInGrid(9999) or SelectRowInGrid(-99) on a grid with only 5 rows, or even no rows at all and the correct actions will be taken; there should be no need in your manual code for tests to check whether your preferred new row index is within the limits of the row count.

==== Selecting a row by specifying the DataRow ====
Much less commonly you may want to select a row for which you know the DataRow object but do not know where it is. In this case you first find the row index and then make the standard call.
<pre>
int rowToSelect = grdDetails.DataSourceRowToIndex2(TheDataRowToSelect);
SelectRowInGrid(rowToSelect);
</pre>
As you will see, this still uses SelectRowInGrid so has all the fetaures described above.

=== Scrolling a Row Into View ===
This task is normally taken care of simply by selecting a row in the grid (see above), but if you need to do this explicitly there is a method to do it, which will ensure that, if possible, the highlighted row has at least one row above and below it.
<pre>
        /// <summary>
        /// This is the OpenPetra override.  It scrolls the window so that the specified row is shown.
        /// The standard grid behaviour would be simply to ensure the selected row is within the grid.
        /// With this method, where possible there is always one unselected row above or one row below.
        /// </summary>
        /// <param name="ARowNumberInGrid">The grid row number that needs to be inside the viewport</param>
        /// <returns>False if the grid scrolls to a new position.  True if the specified row is already in the view port</returns>
        public bool ShowCell(int ARowNumberInGrid)
</pre>

=== 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.

'''Please note that the following code is for illustration only.  The InternationalPostalType screen does not in fact use any of these manual methods because the default behaviour is all that is necessary.'''
* We should use the standard deletion question wherever possible in order to maintain consistency between screens
* We should not normally have a completion message like 'The row was deleted successfully'.  That annoys the user and it is obvious because the row is no longer in the grid! It is good to have a completion message in cases where the behaviour is somewhat non-standard, such as where the code has already saved the changes, which happens on a few finance screens.
* We should not wrap our deletion code in a try/catch block.  There is already a try/catch block in the calling code.
* We should not display message boxes inside these methods because on multi-row delete they would get shown every time.
<pre>
/// <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.  Validate that the specified row can be deleted?*/

	/*Code to modify the deletion question*/

	/*return true if deleting this row is allowed*/
	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, ref string ACompletionMessage)
{
	bool deletionSuccessful = false;
	
	/*Code to prepare for deletion*/

	/*Code to delete rows from dependent tables first*/

	/*Code to perform the row deletion on this table*/
	
	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 - for example updating the main screen*/

}
</pre>

The DeleteRowManual()'s second argument, ref 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.

Please note that when multiple rows are deleted together the deletion question is ignored.  The completion question is displayed after all the rows have been deleted.  This means that if you check its content at each call to DeleteRowManual it will be empty the first time so you should set it to a suitable string for a single row delete.  If the string is not empty this must be a multi-row delete and you may wish to change the text.

You can read more about [[Adding Delete Functionality to a Screen or Control]] here.

=== Coding For Using the Keyboard ===
The grid control contains handlers as standard for the Home/End, Up/Down and PgUp/PgDn keys.  The Insert and Delete keys also do what their name suggests as an alternative to clicking the ''New'' or ''Delete'' buttons on a form, provided that the YAML file specification has '''btnNew''' and/or '''btnDelete'''.

Coding for the ''ENTER'' key only requires slightly more work as you can see, for example, in Ict.Petra.Client.MFinance.Gui.Gift.UC_GiftBatches.yaml

Under the grdDetails section we have:
<pre>
ActionDoubleClick: ShowTransactionTab
ActionEnterKeyPressed: ShowTransactionTab
</pre>
The code then generates:
<pre>
this.grdDetails.EnterKeyPressed += new TKeyPressedEventHandler(this.ShowTransactionTab);
</pre>
This allows the programmer to capture the ''ENTER'' key for any grid and call any code. In this example it is the same code as the double click, but it doesn't have to be, of course.

== Code Snippets That Should NOT Appear in Your Manual Code ==
The manual code class contains several variables and methods that are used to maintain state.  A number of them seem at first glance to be useful in manual code, but you must resist the temptation!  There are certain variables that you should not modify and the use of some of the methods may mean that important variables do not get set.

Here is a list of coding statements that should not appear in your code.
{| border="1" cellpadding="5" cellspacing="0"
!Code!!Comment
|-
|grdDetails.Selection.ResetSelection(false)
|This call clears the selection in the grid and is often followed by the grdDetails.SelectRowInGrid(rowToSelect) call.  Often this will produce the effect that you want but there are circumstances where the details panel will not show the correct details for the row of your choice.  You must use the standard SelectRowInGrid method instead.
|-
|grdDetails.SelectRowInGrid(rowToSelect)
|See the comment for the row above.
|-
|grdDetails.Selection.ActivePosition.Row
|This property looks like a good way to access the selected row but it only returns a positive value when the grid has the focus, which will almost certainly not be true when in manual code.  Use GetSelectedRowIndex() instead.
|-
|FPreviouslySelectedDetailRow = null
|You should not modify this Form variable directly, or, if you do you must be sure to follow it with a call to SelectRowInGrid(N) so that the variable can be reset to a valid object that reflects the content of the details panel.
|-
|FPrevRowChangedRow = 1
|Same comments applies as the row above
|-
|this.FocusedRowChanged(this, new SourceGrid.RowEventArgs(1))
|This seems like an easy way of running the same code as would run when a row is changed.  The most important reason why this is bad practice is that it ignores the possibilty of validating the row change.
|-
|ShowDetails(ADataRow)
|This would almost certainly give rise to a mismatch between the selected row and the content of the details panel
|-
|ShowDetails()
|This line in your code would not be 'bad' but I cannot think of a reason that you would need it!  It simply shows the details for the 'current' row, which should be the details already shown.  So, usually this line would be superfluous.
|}
Unfortunately many of these snippets have appeared in our manual code over time as the auto-generated code has developed.  Now that most grid templates have more standardised methods we need to progress to using these and remove some of the older code.  Usually it will result in fewer lines of code - which will be better in itself!

== 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.

# '''Initial Load'''
## 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.
## ''Errors:''  It is an error if, for example, the initial highlight is on the Code in the details panel.
# '''Using the keyboard to move around the screen'''
## 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.
## ''Errors:''  It is an error if, for example, TABbing from the postal code control in the details panel jumps you back to the grid.
# '''Using the mouse to move around the screen'''
## 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.
# '''Using the keyboard to create new rows (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
### a new row is added at the bottom and is highlighted
### the grid scrolls to show it
### the focus moves to the NEWCODE control
## 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.
## Confirm that the ''Save'' button in the toolbar is enabled.
## Close the window without saving your changes.
## ''Errors:''  it is an error if the row does not appear inside the view-port, or the data in the grid does not match the data in the details panel when you have TABbed back to the grid, or the focus of the new row is not on the CODE control.
# '''Using the keyboard to create new rows (2)'''
## Reload the screen, shrink the height so that not all rows can be displayed, then press the ''Insert'' key.  Confirm that
### one new row has been added at the bottom
### the grid has scrolled to show it
### the focus has moved to the text box for the CODE
## Edit the CODE and TAB back to the grid.  Press the ''Insert'' key again and repeat the test.
## Close the window without saving your changes.
## ''Errors:''  It is an error, for example, if the focus does not change to the NEWCODE control.
# '''Using the mouse to create new rows'''
## Reload the screen, shrink the height so that not all rows can be displayed, then click the ''New'' button once.  Confirm that
### one new row has been added at the bottom
### the grid has scrolled to show it
### the focus moves to the NEWCODE control
## Close the window without saving your changes.
## ''Errors:''  it is an error if the row does not appear inside the view-port, or the data in the grid does not match the data in the details panel when you have TABbed back to the grid, or the focus of the new row is not on the CODE control.
# '''Creating new rows in a sorted grid (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.  Shrink the height of the window so that not all rows can be displayed.  Click ''New'' twice to create 2 new rows.  Confirm that
### The two rows have been inserted into the grid correctly
### If necessary the grid has scrolled the rows into view
### the second inserted row is the upper of the two and that the details panel shows the details for this second row.
### the CODE in the details panel has the focus
## Highlight a different row, then click ''New'' again.  Confirm that the new row is highlighted and its correct details displayed.
## Close the window without saving your changes.
## ''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.
# '''Creating new rows in a sorted grid (2)'''
## 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.  Shrink the height of the window so that not all rows can be displayed.  Click ''New'' twice to create 2 new rows.  Confirm that
### The two rows have been inserted into the grid correctly
### If necessary the grid has scrolled the rows into view
## Repeat, creating new rows but editing the description so that the rows are in different parts of the grid.
## Be sure to test the case where the highlighted row before you create a new row is the row where the new row will appear (the row where the description text is just '''before''' ''Please Enter Description'' in the alphabet).
## Close the window without saving your changes.
## ''Errors:''  Look for the same class of error as when the first column was sorted.
# '''Adding invalid rows to a sorted grid (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
### the highlighted row has jumped to the bottom (blank comes before A)
### the validation tooltip has shown invalid data
### the focus is now on the Description textbox
### all the other data entry details match the highlighted grid row information
## Now, using the mouse, click the ''New'' button.  Confirm that
### a message box pops up notifying you of invalid data
## Close the box and confirm that
### the focus is now on the CODE text box once more
## Press CTRL+Z and confirm that
### the previous value of the CODE is restored
## Now press TAB to move to the description.  Confirm that
### the highlighted row moves back into the middle region of the grid
## Close the window without saving your changes.
## ''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.
# '''Adding invalid rows to a sorted grid (2)'''
## 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.  Instead of activating the message box by clicking ''New'', do so by clicking ''Save''.  Also, 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.
## Close the window without saving your changes.
# '''Adding invalid rows to a sorted grid (3)'''
## 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 click somewhere in the grid with the mouse.  Confirm that
### The highlighted row jumps to the correct position for a blank CODE
### The error dialog immediately pops up, preventing you from moving to the row you clicked on.
## Accept the dialog and confirm that
### The focus moves to the offending control
## Close the window without saving your changes.
## ''Errors:''  It is a serious error if the dialog does not appear or if the row highlight moves to the row you clicked on.
# '''Editing existing data'''
## Reload the screen and add 4 new rows (which will appear at the bottom)
## Now select each of the first two rows in turn using the mouse and edit their contents, without causing validation errors.  Confirm that the data appears correctly in the grid.
## Now using the keyboard only (arrow keys and TAB key), repeat the test on the second pair of added rows.
## Now repeat these two tests using mouse/keyboard, but make the CODE blank and make the Description blank.  Confirm that
### The tab sequence was correct and that all controls are in the TAB sequence
### The tool-tips appeared advising of Bad Data
### That you cannot leave a row that contains bad data using the cursor keys when the grid has focus
### That you cannot leave a row that contains bad data by clicking ''New'' or ''Save''
### That after the accepting the message box listing all the current errors, the first error control is focussed ready to be corrected.
## Close the window without saving your changes.
## ''Errors:''  There are numerous errors that can occur when the underlying code is wrong.  These errors include the wrong control being focussed and wrong information being displayed in the details panel.
# '''Editing existing data in a sorted grid (1)'''
## Reload the screen and click on the sort header of the first column twice, so it is sorted Z at the top and A at the bottom
## Add 1 new row (which will appear near the middle).  The CODE should be focussed.
## Edit the CODE, without causing validation errors.  TAB to the Description.  Confirm that
### the data appears correctly in the grid 
### the 'current' row still has the highlight wherever it has moved to.
## Shift+TAB back to the CODE and try various other values, confirming that the highlight always tracks the row.
## Now repeat this test, but make the CODE blank and make the Description blank.  Confirm that
### The tab sequence was correct and that all controls are in the TAB sequence
### The tool-tips appeared advising of Bad Data
### That you cannot leave a row that contains bad data using the cursor keys when the grid has focus
### That you cannot leave a row that contains bad data by clicking ''New'' or ''Save''
### That after the accepting the message box listing all the current errors, the first error control is focussed ready to be corrected.
## Close the window without saving your changes.
## ''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.
# '''Editing existing data in a sorted grid (2)'''
## Reload the screen and click on the sort header of the '''second''' column twice, so it is sorted Z at the top and A at the bottom
## Add 1 new row (which will appear near the middle).  The CODE should be focussed.
## TAB to the Description and edit it, without causing validation errors.  TAB away from the Description.  Confirm that
### the data appears correctly in the grid 
### the 'current' row still has the highlight wherever it has moved to.
## Shift+TAB back to the Description and try various other values, confirming that the highlight always tracks the row.
## Now repeat this test, but make the Description blank.  Confirm that
### The tab sequence was correct and that all controls are in the TAB sequence
### The tool-tip(s) appeared advising of Bad Data
### That you cannot leave a row that contains bad data using the cursor keys when the grid has focus
### That you cannot leave a row that contains bad data by clicking ''New'' or ''Save''
### That after the accepting the message box listing all the current errors, the first error control is focussed ready to be corrected.
## Close the window without saving your changes.
## ''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.
# '''Checking the Horizontal Scrollbar'''
## 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.
## 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
### a vertical scrollbar has been added to the grid and that the new row is entirely visible.
## Close the window without saving your changes.
## ''Errors:''  It is an error if the new row is partially hidden and no vertical scrollbar is visible.
# '''Checking the Horizontal and Vertical Scrollbars'''
## 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.
## 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
### 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.
## Close the window without saving your changes.
## ''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.
# '''Deleting Rows from the Grid'''
## 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
### the bottom row was deleted
### the new highlighted row is the new bottom row
### the details panel shows the details for the bottom row
## Now select the row one up from the bottom and click the ''Delete'' button once more.  Confirm that
### the highlighted row was deleted
### the highlighted row index did not change, but the data has changed to the row that was at the bottom before the delete.
### the details panel shows the correct data.
## 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.
## Close the window without saving your changes.
## ''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.

# '''Initial Load'''
## 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.
## ''Errors:''  It is an error if, for example, the details panel is not disabled.
# '''Adding Rows Using the Keyboard (1)'''
## Reload the screen, TAB to the New button and press SPACE.  Confirm that
### a new row is added
### the focus is on the NEWCODE for the upper grid
### a new row is added to the lower grid
### both details panels match the highlighted grid rows
## Edit the code and continue editing/TABbing until you reach the New button for the lower grid.  Press SPACE.  Confirm that
### a new row is added to the lower grid
### the focus is on the CODE for the lower panel
### all the details match the grids
## Close the window without saving your changes.
## ''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.
# '''Adding Rows Using the Keyboard (2)'''
## Reload the screen, but this time add a row to the top grid by pressing the ''INS'' key.  Confirm that
### one row got added to the upper grid, and one row in the lower grid
### the focus is CODE for the upper grid
## Now TAB to the lower grid and press the INS key.  Confirm that 
### one row got added to the '''upper''' grid, and one row in the lower grid
### the focus is CODE for the '''upper''' grid
## This shows a limitation of the implementation of the keyboard shortcut handler.  It is associated with the main grid and not the child grid.
## Close the window without saving your changes.
## ''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.
# '''Adding Rows Using the Mouse'''
## Reload the screen, but this time add three rows to the top grid by clicking the ''New'' button three times.  Confirm that
### the upper grid has three rows
### the focus is on the CODE for the upper grid
### there is one row in the lower grid
### all the details are correct for the highlighted grid rows
## Click the ''New'' button for the bottom grid three times.  Confirm that
### the lower grid has four rows
### the focus is on the CODE for the lower grid
### the details are all correct
## Use the mouse or the keyboard arrow keys to confirm that there is one selection in the top grid that has four rows in the bottom grid, while the other top selections only have one bottom grid row
## Close the window without saving your changes.
## ''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.
# '''Deleting Rows'''
## ''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.
## 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.
## 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.
## Do this on the first row in a grid and the last row in a grid.
## Continue deleting until all the rows have been deleted.
## Repeat this test multiple times in different ways
## In all these tests confirm that
### the correct row is deleted
### the focus remains on the relevant grid
### the details panel always matches the grid
## Close the window without saving your changes.
# '''Editing the Contact Attribute Code'''
## ''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.
## Reload the screen and create a few attributes rows in the upper grid.
## Add a few details in the lower grid for each of these attributes.
## Be sure that you know the values for the details corresponding to a particular attribute, by editing them to something unique.
## Highlight, say, the second or third detail attribute in the lower grid.
## 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
### the new code value has been entered into the upper grid
### the lower grid content has not changed
### the lower grid selection has not changed
## Close the window without saving your changes.
## ''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.