NativeWindow

The included first draft is compilable, but is quite far from the intended final version.

It's hopefully sufficient for providing a correct overview of what these classes are to become like.

A few TODOs in the GameWindow class are from the version in the trunk, but the numerous new ones in both classes are notifications for unresolved details, and all should be resolved in a way that is acceptable for as many users of the library as possible, before inclusion in the official version. The possible changes not marked in the source will be included in following posts.

Notes for this version:

• The reason for the current name of NativeWindow (NativeWindow0) is to ease integration of the class into the sources gotten from CVS. Platform specific code refers to Forms.NativeWindow and this intermediate workaround spares everyone from patching those classes too.
• The first short test already revealed the appearance of an exception when the GameWindow is closed using the native close button (in short, X), but the main priority for now was to present the code for review, that issue should be fixed soon after some control flow examination.

(Sources removed due to the addition of newer versions.)

The two most important pending details not immediately visible in the sources (unlike typos right after posting):

1. The purpose and usage of protected virtual On* methods:
   For historical reasons (because samles and documentation say so) the On* methods are invoked along with rising the corresponding events instead of the events being raised by them. Problems with this approach:
   • The library is intended to follow the .NET design guidelines, and they declare the purpose of On* methods as being the place the corresponding events are raised (allowing filtering or argument manipulation, for example).
   • The order in which a given event is raised and its matching On* method is invoked isn't consistent in the current implementation of GameWindow. This would obviously be resolved by the events being raised inside the On* methods.
   • The current implementation of GameWindow relies on some calls to On*Internal methods (which serve as invokers of both events and On* methods), which may not be worked around without adding some NativeWindow internals that are for GameWindow only. Simply calling the non-internal On* method wouldn't rise the corresponding event.

   What the foreseeable effects of the change would be, depending on their current usage:

   • For those who rely only on the On* methods, by overriding them:
     No noticeable change in behavior is expected, but the actual difference would be that the corresponding event doesn't get raised. (Absolutely minimal difference in performance difference, because either no handler, or an empty nameless method is attached to them.)

   • For those relying only on the raised event by adding handlers:
     No noticeable change in behavior is expected, because if not overridden, the On* the on method raises the event.
   • For those relying on both features:
     It's expected the events won't be raised due to their invocation being overridden with application logic. The solution would be to either call the base method as the first or last action in the overriding method or to consistently rely on only one of these features.
2. Untimely raise of events ([Enable|Disable]Events):
   GameWindow attached its internal event handlers (to propagate them to the above mentioned On* methods and events visible on GameWindow) to its INativeWindow at the end of its construction, but because of the new model involving inheritance, the events exposed by GameWindow actually belong to the base NativeWindow class, and normally would get connected to their handlers before the derived constructor even starts.

   This could easily cause crashed if the operating system sends a window event and for example logic involving OpenGL operations has been placed into the On* method the event is propagated to.

   My solution proposal is the addition of the protected EnableEvents and DisableEvents to NativeWindow which would allow both the delaying, both the stopping of propagation of events arriving from the underlying system. (If the discussed change in the previous point was accepted, it would allow manual event raising by calling On* methods under all circumstances (unless specifically overridden not to do so).)

   In case early event calls would cause no problems for an application it would be kind of uncomfortable and easy to forget to actually call EnableEvents, for this reason my proposal is the addition of a boolean parameter to NativeWindow constructors that allows events being enabled without any further actions being required.

A very small update of the 1st draft is included because the NativeWindow constructor didn't include the consideration of the mentioned parameter.

(Sources removed due to their addition to the repository.)

NativeWindow0->NativeWindow renaming patch.
(Has been applied to the branch.)

Committed NativeWindow0 -> NativeWindow patch.

I am running some tests to determine whether events are likely to cause issues for inheriting classes.

Edit: I haven't encountered any adverse side-effects by enabling events inside the NativeWindow constructor. As far as I can tell, events are only generated when INativeWindow.ProcessEvents is called. This method is not called by a the NativeWindow constructor, so no events will be generated unexpectedly.

Will have to verify this holds for all platforms, however.

Comments:

• If we can guarantee that events are only raised inside INativeWindow.ProcessEvents, there will not be a need to add the Events property (needs review). I agree we should make a strong guarantee for event generation (e.g. no events in constructor), but I think the global event toggle should be avoided if possible.
• INativeWindow.Dispose() may be called *after* the window has been closed. Calling WindowState = WindowState.Normal will cause problems in that case. A call to RestoreResolution() should suffice.
• OnLoad/OnUnload should become protected, even if this breaks compatibility. Better leave that to a separate patch, however, as it requires wide changes to Examples project.
• Good catch on isExiting = true.
• Rendering after context becomes invalid: GameWindow used to throw a GameWindowExitException to ensure this never happened. This was bad design for many reasons.

  One potential solution is to make GameWindow.Exit()/Close() work asynchronously. Both could simply set isExiting to true and the actual base.Close() could be moved right after the main loop (inside the run method).

  This still leaves a potential issue of calling Dispose() while the main loop is running, however. Unless we can find a reliable solution for shutting down the main loop, maybe we'll have to reintroduce the internal GameWindowExitException.

• The run method needs a general cleanup, but it's best to leave it mostly unchanged for the purposes of this issue (i.e. no changes to actual logic, if possible).

I'll be without internet access until Monday, so I won't be able to review/commit patches for a few days.