gdk:window-begin-paint-region (window region)

window -- a gdk:window object
region -- a cairo:region-t instance you intend to draw to

Indicates that you are beginning the process of redrawing region. A backing store (offscreen buffer) large enough to contain region will be created. The backing store will be initialized with the background color or background surface for window. Then, all drawing operations performed on window will be diverted to the backing store. When you call the gdk:window-end-paint function, the backing store will be copied to window, making it visible onscreen. Only the part of window contained in region will be modified; that is, drawing operations are clipped to region.

The net result of all this is to remove flicker, because the user sees the finished product appear all at once when you call the gdk:window-end-paint function. If you draw to window directly without calling the gdk:window-begin-paint-region function, the user may see flicker as individual drawing operations are performed in sequence. The clipping and background-initializing features of the gdk:window-begin-paint-region function are conveniences for the programmer, so you can avoid doing that work yourself.

When using GTK, the widget system automatically places calls to the gdk:window-begin-paint-region and gdk:window-end-paint functions around emissions of the "expose-event" signal. That is, if you are writing an expose event handler, you can assume that the exposed area in the gdk:event-expose event has already been cleared to the window background, is already set as the clip region, and already has a backing store. Therefore in most cases, application code need not call the gdk:window-begin-paint-region function. You can disable the automatic calls around expose events on a widget-by-widget basis by calling the gtk:widget-double-buffered function.

If you call this function multiple times before calling the matching gdk:window-end-paint function, the backing stores are pushed onto a stack. The gdk:window-end-paint function copies the topmost backing store onscreen, subtracts the topmost region from all other regions in the stack, and pops the stack. All drawing operations affect only the topmost backing store in the stack. One matching call to the gdk:window-end-paint function is required for each call to the gdk:window-begin-paint-region function. The gdk:window-begin-paint-region function has been deprecated since version 3.22 and should not be used in newly written code. Use the gdk:window-begin-draw-frame function instead.