New Changes to Auto-Generated Code 20 Sep 2012

alanjfpaterson

I have made changes to six of the templates that are used to generate the -generated.cs files. These templates are:

controlMaintainTable
controlMaintainCacheableTable
windowEdit
windowMaintainTable
windowMaintainCacheableTable
windowEditWebConnectorMasterDetail
[/list:u]

These tables have been modified because they are the ones that have a details panel.

I have made quite substantial changes to the two event handlers that deal with the grid (FocusedRowLeaving and FocusedRowChanged). I believe the duplicate event detection is improved. I have also changed the code that acts upon these events. FocusedRowLeaving now ONLY deals with validation (on non-duplicate events) and FocusedRowChanged now ONLY deals with showing the current details in the details panel. With this new code the events are entirely managed within the generated code file. It is never necessary to 'invoke' an event manually. There are no longer form-level variables that you need to know about as a manual code author. Even the variable that we had before named FCurrentRow has gone. FPreviouslySelectedDetailRow is still there but this is automatically handled by the call to show the details in the details panel. It should never really be necessary for you to set FPreviouslySelectedDetailRow as a manual code author, as you will see in a moment.

This has meant that I have been able to simplify the code in places and I have added a couple of new methods/over-rides to make life easier for the manual code author.
All the most commonly used generated code methods now have full intellisense comments, so now you get help when using them in manual code. Please have a look at these comments as you browse the new generated code for the screens that you are familiar with.

Here is a description of the most common methods you will need to use.

Methods for Showing Details
The basic method to ShowDetails(YourTypedRow ARow) is unchanged. This shows the details for a specified row. Please note that it contains enough smart logic to enable/disable the panel depending on whether ARow is NULL or if the data is in DetailProtectMode.

I have added a new overload, which is simply ShowDetails(). This shows the details for the currently highlighted row. It turns out that this is the commonest way of wanting the details to be shown. Internally this is just the following.
```
    private void ShowDetails()
    {
        ShowDetails(GetSelectedDetailRow());
    }
```
(ShowDetails() is just easier to write and remember!!)

Remember: ShowDetails methods work equally well when the current row is null or the grid has no row data.
The two ShowDetails methods set up the FPreviouslySelectedDetailRow variable. So once you have shown the details for a row you are free to use it as a means of accessing column data.

Row Selection Methods
There are two main row selection methods – again, one old and one new.
```
private void SelectDetailRowByDataTableIndex(Int32 ARowNumberInTable, bool AAndShowDetails = false)
```
This is the method that we have had all along. Typically it is used to select the row that has just been created using the New button. But now it has an optional parameter that defaults to false (to keep existing behaviour). When the additional parameter is true the method calls ShowDetails() so that the details panel is automatically updated to reflect the newly selected data.

The new method is:
```
    private void SelectRowInGrid(int ARowIndex, bool AAndShowDetails = false)
    {
        grdDetails.SelectRowInGrid(ARowIndex, TSgrdDataGrid.TInvokeGridFocusEventEnum.NoFocusEvent);
        if (AAndShowDetails) ShowDetails();
    }
```
This new method is another convenience. It wraps up the call that Chris Thomas wrote in the grid wrapper to select a row in the grid without causing any events. It means that as an author you no longer need to remember that some methods are associated with the grid object while others are internal to the generated code.

You will see that this method has the same optional parameter that means that you can select a row AND show its details all in one line.

You need to understand that this method is particularly powerful because the row index that you supply does not even have to be within the range 1..DataRowCount. If the grid has no rows, no row is highlighted. If the specified row index is less than 1, the first row is highlighted. If the row index is more than DataRowCount, the last row is highlighted. So you can appreciate that this is a useful method even when deleting rows. Simply call the method passing the index of the deleted row and the relevant row will be selected, the correct details will be shown for that row and FPreviouslySelectedDetailRow will automatically be updated!

If you are writing manual code that needs to select a specific row, you will almost always find that
SelectRowInGrid(rowIndex, true)
is all you need.

Finally it is worth mentioning that SelectRowInGrid is inexpensive in computing terms – it simply highlights the specified row. In contrast SelectDetailRowByDataTableIndex() does potentially involve looping through all the records in the grid.

Getting the Selected Row
These methods have not changed.

GetSelectedDetailRow() returns the selected row as a reference to a typed data row in the grid. This call is a call to the grid object and is not expensive in terms of computation.

GetDetailGridRowDataTableIndex() returns the index in the data table for the data in the current grid row. This method is more expensive in terms of computation because it goes round a loop.

More About Events
The FocusedRow Events are triggered by the user as he interacts with the GUI. Cursor keys trigger events as does an initial load of data into the grid. These events are entirely transparent to the manual code author, so it should never be necessary to invoke these events or access the form-level variables that they use.

As I have just explained, none of the SelectRow… methods cause events to be fired. So this results in a good separation between the code that runs in the auto-generated section and the code that runs in the manual section.

If you look at the event code you will see that we detect duplicate row leaving events AND duplicate row changed events. While duplicate leaving events only ever give rise to one changed event, it is possible to get a changed event without a leaving event. This happens each time you tab round the controls past the grid. So the current code automatically disregards these duplicate changed events.

Although these grid events are managed to occur singly, the data validation event is fired many times as the user tabs from control to control. This is, of course, by design.

More About Template Changes
This comment is particularly for Christian! If you look at the differences in the templates, please do not be alarmed at the way the ValidateAllData section seems to have changed. There is actually very little difference to the output. I have slightly re-arranged the nesting of multiple {IFDEF’s with a view to the changes that will come later to do with exception handling of duplicate records. So actually there should really only be one additional line in the generated c# code that ensures that the correct row is still highlighted after validating on a sorted grid. I thought that, since we were going to give our code a very thorough testing before this release, it would be an opportunity to slip this change in. Then in the future I can add the exception handling very easily, rather than have to make these re-arrangements to the template at that time.

I hope that is ok.

And, yes, my famous ’10 lines’ of code that handles the tracking of the highlighted row after validation has collapsed to just one line, by using the new methods for selecting a row in the grid.

These Screens Have Had Their Manual Code Files Modified
The following screens have all had MANUAL.CS files modified by me because of the changes to method calls in the generated code. I suggest that you look at the changes that have been made using Diff in the Bazaar Log, and then confirm that the screens still behave correctly.

In Finance:
- UC_GLBatches
  UC_GLJournals
  UC_GLTransactions
  UC_GiftBatches
  UC_GiftTransactions
  UC_RecurringGiftBatches
  UC_RecurringGiftTransactions
  SetupCorporateExchangeRate
  SetupDailyExchangeRate (I will be changing this one anyway, hopefully soon)
  [/list:u]
  (Sorry Chris that you have the most to check – but at least it is all code that you have recently worked on so it shouldn’t take too long for you to confirm it is ok)
  
  In MCommon
  - InternationalPostalType (I have extensively tested this as my testbed)
    LocatdataFieldOrderSetup (This also is one of mine and the changes have been checked)
    [/list:u]
    
    In Partner:
    - UC_ContactAttributeDetail
      UC_Applications
      UC_IndividualData_PersonalDocuments
      [/list:u]
      
      You will notice that I also changed one other detail relating to the three DeleteRow... methods. Previously they were called by passing the typed data row parameter by reference. I do not believe this is correct. The row object is already a reference object type so we are quite free to access the column details data in both read and write mode, even when the row object is passed by value. Passing by reference would enable us to change the row that is pointed to, or create a new one and pass it back to the caller, but this would never have been the intention on a row that we are about to delete! So it might be that the only difference in the manual code file is that the DeleteRow method prototype has changed - in which case you have nothing to worry about.
      
      Apart from this change and the ones that I have made to get the code to compile, no other changes have been necessary and so I imagine that all the other manual code works just the same as ever. That is not to say though that the manual code in other files could not be simplified by using the new methods available to the manual code author.
      
      General Testing – Finding Good Examples
      You may notice that the ValidateAllData section of the code has some quirky comments like
      // :WE:ucvalidation
      I put these in to help me see which OpenPetra screens contained which features for which templates. So :WE: stands for windowEdit, :WMCT: stands for windowMaintainCacheableTable and so on.
      
      If you use the development environment ‘Find In Files’ feature to find all instances of :WE: for example, this will show you all the screens that are derived from the windowEdit template and indeed, which features those screens implement (like manual validation, user control validation etc.) This is a nice way of establishing which screens are the good ones to test a particular feature implementation.
      - controlMaintainTable :CMT:
        controlMaintainCacheableTable :CMCT:
        windowEdit :WE:
        windowMaintainTable :WMT:
        windowMaintainCacheableTable :WMCT:
        windowEditWebConnectorMasterDetail :WEWCMD:
        [/list:u]

alanjfpaterson

More Changes on 27 Sep 2012
The changes that I committed last week still turned out to have bugs in them. I have re-worked the code and I believe it is considerably better for a number of technical reasons. Plus I have tried to hammer it to death on several screens and haven’t been able to break it.

The code that I committed before to handle duplicate event detection has worked well without any need to change it. However the problem has been the sequencing of the events themselves. The previous code handled row selection using a mixture of calls, some of which fired off events while others intentionally selected a row without causing any events. This turned out to be a bad design; one might say unexpectedly so. However one of the features of the base grid class seems to be that if you select a row without events, you may not get the next Row Leaving event that you are dependent upon. It made no difference if events were disabled using the -= and += syntax or by means changing the grid Focus Style property. The end result was the same.

We have no choice – we are totally dependent on getting Row Leaving events for validation.

So I have ended up by

Never turning off events anywhere.
Carefully managing the sequence in which events are fired and nested inside one another.
[/list:u]

Needless to say, validation is the biggest headache because on sorted grids validation can cause rows to move, which results in Row Leaving events which result in validation. Potentially this can result in an endless loop (stack overflow), which is why past programmers have resorted to turning off events when performing certain operations. But the current code does not do this. Instead the variable FPrevRowChangedRow is critical in ensuring that we only select a grid row (with consequent events) at the correct time.

So how will this affect your code? The two methods: SelectRowInGrid and SelectDetailRowByDataTableIndex are the ones that you will use (as with the previous check-in). However they now just take the one parameter – the row to select. The previous second parameter that gave you the option of whether to show the details as well no longer applies. Because selecting a row always potentially fires off events that cannot be stopped, you no longer have the choice to not show details. But that is all right because you always will want the details to match the selected row anyway!

Please note that making either of these calls will do all of the following (simply because the necessary events all get fired in the correct order)
- Check that the panel has rows. If not, no row is selected and the panel is disabled.
  Check that the specified row is within the bounds of the available grid rows. If not the first or last row is selected instead.
  Highlight the specified row.
  Show the details for the data associated with that row, even if the row holds different data from what it held previously (as in re-filtering).
  Update the reference pointed to by FPreviouslySelectedRow
  Enable the panel unless it is in detail protect mode
  [/list:u]
  As you can see, this one line does a lot of stuff behind the scenes! If you are going over old manual code, please just use this one line. You should be able to remove any lines that enable the panel or set up FPreviouslySelectedRow and so on.
  
  As I have said, this work turned out to be in two very distinct parts: the detection of duplicate events was the easier part. Firing the events in the right order was the more difficult part. I found that if I got that wrong a number of strange side effects occurred, like needing two clicks on a control to operate it, or not being able to tab all around the controls because the validation code would keep handling the focus.
  
  I have left some Console.WriteLines in the code (all commented out). I will remove them when we are happy with the code as it is, but they are useful in seeing the train of events.
  
  Finally, due to the SelectRow… calls now having only one parameter I had to revisit all the same manual code files that I edited before (Partner and Finance). That is why when you get this code you will see changes in those files. Apart from that any changes you made to your manual code should still be fine. And please make sure that you remove any FPrevRowChangedRow=-1 lines that you added in the previous testing. Those lines would now be a BAD thing!