SourceGrid specification and testing

The SourceGrid control and its implementation in OpenPetra, has required that modifications be made to its event handling to ensure consistent and predictable event firing in relation to selecting, adding, deleting, sorting and saving rows in the grid. This includes detecting and cancelling repating and unwanted events (mainly FocusRowLeaving event) and invoking events (mainly FocusedRowChanged) when no event is fired (when it should be). Below are the changes that have been introduced to the grid, the grid wrapper and the templates that affect use of the grid throughtout OpenPetra.

Event Handling

The two events that have been the focus of the changes to the grid-related code are FocusRowLeaving (when the currently selected row loses focus) and FocusRowChanged (when a new row receives focus).

Event - Keyboard handling

The grid fires row-level events when the grid itself loses focus even though the current row had not changed. I remmed out two lines of code in the SourceGrid code that related to the user tabbing away or clicking away from the entire grid itself to stop the firing of these events. No other in-grid events are affected. Here are the changes found in GridVirtual.cs:

    protected override void OnValidated(EventArgs e)
    {
        base.OnValidated(e);

	//NOTE: I use OnValidated and not OnLostFocus because is not called when the focus is on another child control
        // (for example an editor control) or OnLeave because before Validating event and so the validation can still be stopped

        if ((Selection.FocusStyle & FocusStyle.RemoveFocusCellOnLeave) == FocusStyle.RemoveFocusCellOnLeave)
	{
		//Changed by CT - 2012-07-03
		//Selection.Focus(Position.Empty, false);
	}

	if ((Selection.FocusStyle & FocusStyle.RemoveSelectionOnLeave) == FocusStyle.RemoveSelectionOnLeave)
	{
		//Changed by CT - 2012-07-03
		//Selection.ResetSelection(true);
	}
    }

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

Event - FocusRowLeaving

This is the even that fires most often and needs to be curtailed and checked for repeats. Here's the code from the template with supporting methods etc.:

    private bool FInitialFocusEventCompleted = false;
    private bool FNewFocusEvent = false;
    private bool FRepeatLeaveEventDetected = false;
    private int FDetailGridRowsCountPrevious = 0;
    private int FDetailGridRowsCountCurrent = 0;
    private int FDetailGridRowsChangedState = 0;

    private void FocusPreparation(bool AIsLeaveEvent)
    {
        if (FRepeatLeaveEventDetected)
        {
            return;
        }

        FDetailGridRowsCountCurrent = grdDetails.Rows.Count;

        //first run only
        if (!FInitialFocusEventCompleted)
        {
            FInitialFocusEventCompleted = true;
            FDetailGridRowsCountPrevious = FDetailGridRowsCountCurrent;
        }

        //Specify if it is a row change, add or delete
        if (FDetailGridRowsCountPrevious == FDetailGridRowsCountCurrent)
        {
            FDetailGridRowsChangedState = 0;
        }
        else if (FDetailGridRowsCountPrevious > FDetailGridRowsCountCurrent)
        {
            FDetailGridRowsCountPrevious = FDetailGridRowsCountCurrent;
            FDetailGridRowsChangedState = -1;
        }
        else if (FDetailGridRowsCountPrevious < FDetailGridRowsCountCurrent)
        {
            FDetailGridRowsCountPrevious = FDetailGridRowsCountCurrent;
            FDetailGridRowsChangedState = 1;
        }

    }

    private void InvokeFocusedRowChanged(int AGridRowNumber)
    {
        SourceGrid.RowEventArgs rowArgs  = new SourceGrid.RowEventArgs(AGridRowNumber);
        FocusedRowChanged(grdDetails, rowArgs);
    }

    private void FocusRowLeaving(object sender, SourceGrid.RowCancelEventArgs e)
    {
        //Ignore this event if currently sorting
        if (grdDetails.Sorting)
        {
            FNewFocusEvent = false;
            return;
        }

        if (FNewFocusEvent == false)
        {
            FNewFocusEvent = true;
        }

        FocusPreparation(true);

        if (!FRepeatLeaveEventDetected)
        {
            FRepeatLeaveEventDetected = true;

            if (FDetailGridRowsChangedState == -1 || FDetailGridRowsCountCurrent == 2)  //do not run validation if cancelling current row
                                                                    // OR only 1 row present so no rowleaving event possible
            {
                e.Cancel = true;
            }

            Console.WriteLine("FocusRowLeaving");

            if (!ValidateAllData(true, true))
            {
                e.Cancel = true;
            }
        }
        else
        {
            // Reset flag
            FRepeatLeaveEventDetected = false;
            e.Cancel = true;
        }
    }

Basically, the supporting code needs to identify the user action and behave accordingly, this includes selecting, sorting, adding and deleting rows. The InvokeFocusedRowChanged() method allows the calling of the FocusedRowChanged event code when it needs to be called manually.

    private void FocusedRowChanged(System.Object sender, SourceGrid.RowEventArgs e)
    {
        FNewRecordUnsavedInFocus = false;

        FRepeatLeaveEventDetected = false;

        if (!grdDetails.Sorting)
        {
            //Sometimes, FocusedRowChanged get called without FocusRowLeaving
            //  so need to handle that
            if (!FNewFocusEvent)
            {
                //This implies start of a new event chain without a previous FocusRowLeaving
                FocusPreparation(false);
            }

            //Only allow, row change, add or delete, not repeat events from grid changing focus
            if(e.Row != FCurrentRow && FDetailGridRowsChangedState == 0)
            {
                // Transfer data from Controls into the DataTable
                if (FPreviouslySelectedDetailRow != null)
                {
                    GetDetailsFromControls(FPreviouslySelectedDetailRow);
                }

                // Display the details of the currently selected Row
                FPreviouslySelectedDetailRow = GetSelectedDetailRow();
                ShowDetails(FPreviouslySelectedDetailRow);
                pnlDetails.Enabled = true;
            }
            else if (FDetailGridRowsChangedState == 1) //Addition
            {

            }
            else if (FDetailGridRowsChangedState == -1) //Deletion
            {
                if (FDetailGridRowsCountCurrent > 1) //Implies at least one record still left
                {
                    int nextRowToSelect = e.Row;
                    //If last row deleted, subtract row index to select by 1
                    if (nextRowToSelect == FDetailGridRowsCountCurrent)
                    {
                        nextRowToSelect--;
                    }
                    // Select and display the details of the currently selected Row without causing an event
                    grdDetails.SelectRowInGrid(nextRowToSelect, TSgrdDataGrid.TInvokeGridFocusEventEnum.NoFocusEvent);
                    FPreviouslySelectedDetailRow = GetSelectedDetailRow();
                    ShowDetails(FPreviouslySelectedDetailRow);
                    pnlDetails.Enabled = true;
                }
                else
                {
                    e.Row = 0;
                    FPreviouslySelectedDetailRow = null;
                    pnlDetails.Enabled = false;
                }
            }
        }

        FCurrentRow = e.Row;

        //Event chain tidy-up
        FDetailGridRowsChangedState = 0;
        FNewFocusEvent = false;
    }

The above event ensures the correlation between the FCurrentRow variable and the current row, especially during sorting etc., and it also ensures, on a delete, that the record at the same index position (as determined by sort order) or 1 above is always chosen.

Adding Rows

Where the form templates contain code for adding records to the grid, changes have had to be made to control event firing. Here is an example:

    private bool FNewRecordUnsavedInFocus = false;
	
	/// automatically generated, create a new record of {#DETAILTABLE} and display on the edit screen
    /// we create the table locally, no dataset
    public bool CreateNew{#DETAILTABLE}()
    {
        if(ValidateAllData(true, true))
        {    
            {#DETAILTABLE}Row NewRow = FMainDS.{#DETAILTABLE}.NewRowTyped();
            {#INITNEWROWMANUAL}
            FMainDS.{#DETAILTABLE}.Rows.Add(NewRow);
            
            FPetraUtilsObject.SetChangedFlag();

			grdDetails.DataSource = null;
            grdDetails.DataSource = new DevAge.ComponentModel.BoundDataView(FMainDS.{#DETAILTABLE}.DefaultView);
            
			SelectDetailRowByDataTableIndex(FMainDS.{#DETAILTABLE}.Rows.Count - 1);
            InvokeFocusedRowChanged(grdDetails.SelectedRowIndex());

            //Must be set after the FocusRowChanged event is called as it sets this flag to false
            FNewRecordUnsavedInFocus = true;

            FPreviouslySelectedDetailRow = GetSelectedDetailRow();
            ShowDetails(FPreviouslySelectedDetailRow);
			
            Control[] pnl = this.Controls.Find("pnlDetails", true);
            if (pnl.Length > 0)
            {
	            //Look for Key & Description fields
	            bool keyFieldFound = false;
	            foreach (Control detailsCtrl in pnl[0].Controls)
	            {
	                if (!keyFieldFound && (detailsCtrl is TextBox || detailsCtrl is ComboBox))
	                {
	                    keyFieldFound = true;
	                    detailsCtrl.Focus();
	                }
	
	                if (detailsCtrl is TextBox && detailsCtrl.Name.Contains("Descr") && detailsCtrl.Text == string.Empty)
	                {
	                    detailsCtrl.Text = "PLEASE ENTER DESCRIPTION";
	                    break;
	                }
	            }

		    GetDetailsFromControls(FPreviouslySelectedDetailRow);
            }
			
            return true;
        }
        else
        {
            return false;
        }
    }

You will notice that the grid's DataSource needed to be set to Null before being reset. This ensured removal of focus from a cell on the previous row. The code also invokes the FocusedRowChanged event as well as sending focus to the new row irrespective of sorting and then gives focus to the key value field and populates the description field if it exists.

Also in another template method: SelectDetailRowByDataTableIndex(), the last line is changed that calls a new signature method in the wrapper that selects the specified row but without firing any events. The enumerator allows you to specify the event you would like to fire.

grdDetails.SelectRowInGrid(RowNumberGrid, TSgrdDataGrid.TInvokeGridFocusEventEnum.NoFocusEvent);

Deleting Rows

The code for deleting rows is now in the templates:

   private void Delete{#DETAILTABLE}()
    {
		bool allowDeletion = true;
		bool deletionPerformed = false;
		string deletionQuestion = Catalog.GetString("Are you sure you want to delete the current row?");
		string completionMessage = string.Empty;
		
		if (FPreviouslySelectedDetailRow == null)
		{
			return;
		}

		int rowIndexToDelete = grdDetails.SelectedRowIndex();
		{#DETAILTABLETYPE}Row rowToDelete = GetSelectedDetailRow();
		
		{#PREDELETEMANUAL}
		
		if(allowDeletion)
		{
        	if ((MessageBox.Show(deletionQuestion,
					 Catalog.GetString("Confirm Delete"),
                     MessageBoxButtons.YesNo,
                     MessageBoxIcon.Question) == System.Windows.Forms.DialogResult.Yes))
			{
{#IFDEF DELETEROWMANUAL}
			    {#DELETEROWMANUAL}
{#ENDIF DELETEROWMANUAL}
{#IFNDEF DELETEROWMANUAL}				
			    rowToDelete.Delete();
			    deletionPerformed = true;
{#ENDIFN DELETEROWMANUAL}				
			
			    FPetraUtilsObject.SetChangedFlag();
			    //Select and call the event that doesn't occur automatically
			    InvokeFocusedRowChanged(rowIndexToDelete);
			}
		}

{#IFDEF POSTDELETEMANUAL}
		{#POSTDELETEMANUAL}
{#ENDIF POSTDELETEMANUAL}
{#IFNDEF POSTDELETEMANUAL}
		if(deletionPerformed && completionMessage.Length > 0)
		{
			MessageBox.Show(completionMessage,
					 Catalog.GetString("Deletion Completed"));
		}
{#ENDIFN POSTDELETEMANUAL}

    }

The autogenerated Delete{#DETAILTABLE} procedure can call up to 3 optional manual code methods that control the deletion process (see code below for example with description of arguments etc.):

/// <summary>
/// Performs checks to determine whether a deletion of the current
///  row is permissable
/// </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(ref 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(ref PInternationalPostalTypeRow ARowToDelete, out string ACompletionMessage)
{
	bool deletionSuccessful = false;
	
	try
	{
		//Must be set the message parameters before the delete is performed if reading 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(ref 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);
	}
	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.

Saving Rows

The main issue with saving was ensuring that the sorting was correct after changing the key field. To do this the following code was added to the save event in the template:

//The sorting will be affected when a new row is saved, so need to reselect row
if (FNewRecordUnsavedInFocus)
{
	SelectDetailRowByDataTableIndex(FMainDS.{#DETAILTABLE}.Rows.Count - 1);
	InvokeFocusedRowChanged(grdDetails.SelectedRowIndex());
}

Even though the FocusRowChanged event should not be needed, it is used to display the record (which may have moved due to sorting) and keep the FCurrent variable up to date.

Grid Testing

Testing needs to be setup where we can test the grid on all its basic functions in forms derived from each of the templates.

Currently, all code generated from the templates compiles and a number of basic maintain screens have been tested for correct behaviour, but a smaller stand-alone application will also be needed to test the behaviour in isolation.