Reference » Messages » Paint

Paint (message)

Description

Informs the window that its graphical content needs to be repainted right now.

Details

Paint is the only "request message" among the standard messages. When a window receives this message, it should repaint its graphical content (in part or in whole, see below) inside the OnPaint handler (or inside functions called during OnPaint).

This message can be received at any time and for a variety of reasons. In general, the message is received by a window if part of it just became visible on the screen after being obscured or clipped by other windows or by the screen boundary. If the window's size changes, it is repainted as well. A Paint message may be generated even if no new parts are exposed during the resizing or moving. Finally, the message can be generated programmatically, using MWindow::repaint or MWindow::getImage.

It is not recommended to do anything during OnPaint other than drawing the graphical content. In fact, Elgrint forbids the creation of new windows during the Paint message (exception 2001 is generated). Window properties can be changed during OnPaint, but really shouldn't be (exception 3001 is generated in such cases). GenException (which eventually creates a message box by default) can be used, but MApp::messageBox function returns without opening a dialog box - instead the report is delayed, and the message box is opened after the Paint message is handled.

The Paint message is the only "natural" time to paint in the window. Although painting can be done anytime, the drawing made outside of the OnPaint handler is "unstable" - it may disappear the next time the Paint message is received, which can happen at any moment, as described above.

During OnPaint, each pixels in the window is either "valid" or "invalid". Only the invalid pixels can be changed during OnPaint (outside of OnPaint there is no such limitation). This limitation is needed for performance, to prevent redundant painting (which is costly) on the parts that do not need to be painted. This masking is supported automatically, but it is usually a good idea not to draw on the valid pixels at all, to increase the performance even further. The MWindow::digClipRect function returns the smallest rectangle, which encompasses all the invalid pixels in the window. Thus, it is recommended to limit the drawing to this rectangle (unless doing this would be more difficult and costly than simply drawing everything). Pixels can be invalidated manually using MWindow::repaint, but only outside of OnPaint. MWindow::repaint cannot be used during OnPaint.

It is generally not necessary to paint every invalid pixel, because Elgrint automatically resets all invalid pixels to the current MWindow::BackColor before the painting process starts. In fact, OnPaint may be completely empty - the window will be simply filled with the background color (alpha channel is ignored in this case, because the background must be opaque).

There are other functions and properties relevant to the Paint message processing (see MWindow and Painting functions).

Remarks

Example

Let us know

Please Contact us to report any errors on this page, or to suggest any improvements.

Miranor Home | About Miranor | About Elgrint | Create account | Login | Account settings | Contact Us | Privacy Policy | Site map

© Copyright 2014 by Miranor. All rights reserved. By using this site you agree to the Terms of Use.

Page last updated on August 10th, 2014.