MWindow functions that define graphical content inside the window.
The painting functions are normally used inside OnPaint (see Paint) to define the entire visual appearance of the window, although they can be used outside of OnPaint as well. Recognizing these functions is easy - they all contain the word "draw" or "fill" in their names, and they are the only MWindow functions with such distinction.
All the painting functions are subject to a coordinate and dimension transformation, defined by MWindow::setDrawTransform. By default, all the coordinates are relative to the top-left corner of the window (regardless of the MWindow::RTL property) and all the sizes are in physical pixels. However, a transform can change the origin point and scaling factors. See MWindow::setDrawTransform and MTransform for more information.
Only the painting functions that are used inside OnPaint have a "permanent" effect - the results of painting outside of OnPaint are erased the next time the window is repainted, which can happen at any moment for various reasons, some of which are beyond the app's control. Therefore, it is not recommended to use the painting functions outside of OnPaint, except for the MWindow::calcDrawTextSize revealer.
During OnPaint, pixels inside the window can be invalid or valid (see MWindow::repaint). The painting functions affect only the invalid pixels (whose content is undefined - that is why they need to be repainted). The content of the valid pixels remains unchanged even if a drawing function is used on it. Outside of OnPaint all pixels are affected by the painting functions.
Regardless of whether the functions are used inside or outside OnPaint, they do not affect anything outside of the window's canvas, i.e. they are clipped by the window's boundaries and by all the windows, whose rectangles intersect with this window (e.g. children or siblings with higher z-order). The only exception is the screen window, whose painting functions draw directly on the screen, on top of all the windows.
These are all the painting functions in MWindow:
Drawing (outline painting):
- MWindow::setDrawSettings - configuration (color, thickness, and style)
- MWindow::drawRect - rectangular outline
- MWindow::drawArc - elliptical arc
- MWindow::drawPoly - straight lines, connected by Bezier curves
Filled shape painting:
- MWindow::setFillSettings - configuration (linear gradient colors)
- MWindow::fillRect - rectangular shape
- MWindow::fillArc - filled pie-slice
- MWindow::fillPoly - filled area inside the shape, defined by point pairs (same as in drawPoly)
- MWindow::setDrawTextSettings - configuration (font and color for text drawing)
- MWindow::drawText - draw text
- MWindow::calcDrawTextSize - calculate the size of the text if it would be drawn
- MWindow::drawImage - draw bitmap, optionally scaled and/or rotated
- MWindow::setDrawTransform - affects coordinates and dimensions
- MWindow::OnPaint - fills the entire window with the solid and opaque color (as specified by the latest MWindow::setFillSettings)
Also, the following properties affect the graphical content, even though they are not painting functions themselves and should not be used during OnPaint:
- MWindow::BackColor - default filling color
- MWindow::ForeColor - default color for lines, curves, and text
- MWindow::Font - default font for text drawing
- MWindow::HighQuality - affects the visual quality of outlines, shape edges, text glyphs, and bitmap interpolation
The painting functions do not affect the window right away, but are kept in an internal buffer until it is flushed. In other words, a painted shape does not appear on the screen after calling a painting function. The graphic content appears all at once when the paint buffer is flushed. This buffering is needed to prevent the annoying flickering effect, which occurs if different shapes are painted on top of each other (which is practically unavoidable in most situations).
The flushing occurs automatically after each message processing and also before mcPaint processing (so during Paint the buffer is flushed before and after the handler). Also, all the buffers (for all windows) are flushed before suspending the main thread as a result of MApp::sleep. This actually means that the graphics can be flushed manually by calling MApp::sleep(0), but that is rarely necessary. The flushing before sleep is useful for animated graphics, where sleep is used for properly timing the animation.
- Read more about using MWindow::setDrawTransform in Drawing transformation
- For technical reasons, the painting functions may produce slightly different outputs on different platforms. The differences should be small and in most cases unnoticeable, but it is important to remember that shifts of a pixel (or even more) here and there are possible, so the graphic content should not be regarded as a perfectly fixed picture. In particular, a pixel by pixel comparison of the MWindow::getImage result with some pre-existing image may produce different results in different systems. See Remarks sections of each painting function for details on this matter
- MWindow::repaint affects the graphical content, but is not considered a painting function and should not be used during OnPaint, because it triggers the Paint message
Let us know
Please Contact us to report any errors on this page, or to suggest any improvements.