[Kde-games-devel] SVG and MainWindow resize handling

[Ian Wadham]

Hi everybody,

After much discussion with Luciano and a lot of encouragement
from him, I have worked out a new way to handle resize events
when the main window starts up, such that the SVG graphics is
loaded, scaled, rendered and painted just once.  It is currently
implemented in the trunk code of KGoldrunner.  I would
appreciate any comments and feedback.

There can be 3 resize events during startup:
  1. A resize covering central widget, status bar, toolbar(s) and
      title bar.
  2. A resize to add in the menu bar.
  3. An extra resize if the window was previously maximized
      or full-screen [1].

At present, IIRC, games are ignoring 1 by testing for resize
pending status, acting on 2 and probably acting on 3 also.

This approach will fail if the window is of ordinary size and
has no menu bar, because 1 will be ignored and there will
be no 2.  It can happen if the user has a Macintosh style
desktop, in which the app that has the focus has its menu
bar placed at the top of the desktop area.  Luciano discovered
this during our final release phase, but we decided to turn a
blind eye to it, because "[KDE]macStyle=true" in "kdeglobals"
config file is not yet supported fully in KDE 4.

The new method has no artificial time delays and the main window
appears instantly (though a bit empty until the SVG catches up).
All cases of 1, 2 or 3 resize events are handled correctly (even
macStyle=true cases).  How it works is ... 

1. There is a slot that is an extension of the main-widget's
    constructor (e.g. KGoldrunner::KGoldrunner_2).

2. The event queue is scanned twice, once before and once
    after the execution of the constructor extension.  All the
    initial resize events occur during one of these two scans.

3. The Main Window's show() is delayed until some time in
    the execution of the constructor extension, which avoids
    ugly transient displays, among other things.

4. So the order of execution in a typical SVG-based KDE app is:
        - Normal KDE programming for actions, etc.
        - Call setupGUI()
        - Queued call to the constructor extension
        - Exit from constructor (Note: No show() yet)
        - Scan 1 of event-queue (incl. 1st resize event)
        - Enter constructor extension
        - Do show() for the main window
        - Queued call to the app's first graphics method
        - Exit from constructor extension
        - Scan 2 of event queue (incl. 2nd and 3rd resize, if any)
        - Enter app's first graphics method
        - Load SVG file, scale and render SVG, draw pixmaps
        - Draw the scaled contents of the central widget
        - Exit from app's first graphics method
        - Scan 3 of event queue (incl. central widget paint event)

5. A flag in the app's graphics methods prevents processing of
    any central-widget resize events that come in before the SVG
    is processed, so the SVG is processed just once during startup.
    After that, resize events (caused by the end-user [2]) are processed
    and lead to the SVG being re-scaled, re-rendered and re-drawn.

In KGoldrunner, the app's first graphics method is KGrGame::initGame().
At the moment it just runs the first KGrCanvas::changeTheme() and then
calls KGrGame::newGame() to draw the last level played.  It could of
course paint something else in the main window while we are waiting
for the SVG operations to complete.

I think the approach can be used in any KDE 4 game and probably in
other apps that require substantial graphics processing during startup.
I think it will also work if the main window library code gets changed,
though I see no signs of that happening in the TechBase TODO lists.
Any comments or feedback?

All the best, Ian W.

[1] There is a bug in full screen mode.  If you close the app, it comes
back next time in Maximized mode, not full screen.

[2] IMHO resize events caused by the end-user dragging the window
frame should come in with spontaneous() = true, but they don't.