Graphics.UI.Gtk.Gdk.DrawWindow

gtk-0.12.4: Binding to the Gtk+ graphical user interface library.

Portability | portable (depends on GHC)
Stability | provisional
Maintainer | gtk2hs-users@lists.sourceforge.net
Safe Haskell | None

Graphics.UI.Gtk.Gdk.DrawWindow

Contents

- Class Hierarchy
- Types
- Methods

Description

A `DrawWindow` is a rectangular region on the screen.

Synopsis

- data DrawWindow
- class DrawableClass o => DrawWindowClass o
- castToDrawWindow :: GObjectClass obj => obj -> DrawWindow
- gTypeDrawWindow :: GType
- data WindowState
  - = WindowStateWithdrawn
  - | WindowStateIconified
  - | WindowStateMaximized
  - | WindowStateSticky
  - | WindowStateFullscreen
  - | WindowStateAbove
  - | WindowStateBelow
- data NativeWindowId
- toNativeWindowId :: Integral a => a -> NativeWindowId
- fromNativeWindowId :: Integral a => NativeWindowId -> a
- drawWindowGetState :: DrawWindowClass self => self -> IO [WindowState]
- drawWindowScroll :: DrawWindowClass self => self -> Int -> Int -> IO ()
- drawWindowClear :: DrawWindowClass self => self -> IO ()
- drawWindowClearArea :: DrawWindowClass self => self -> Int -> Int -> Int -> Int -> IO ()
- drawWindowClearAreaExpose :: DrawWindowClass self => self -> Int -> Int -> Int -> Int -> IO ()
- drawWindowRaise :: DrawWindowClass self => self -> IO ()
- drawWindowLower :: DrawWindowClass self => self -> IO ()
- drawWindowBeginPaintRect :: DrawWindowClass self => self -> Rectangle -> IO ()
- drawWindowBeginPaintRegion :: DrawWindowClass self => self -> Region -> IO ()
- drawWindowEndPaint :: DrawWindowClass self => self -> IO ()
- drawWindowInvalidateRect :: DrawWindowClass self => self -> Rectangle -> Bool -> IO ()
- drawWindowInvalidateRegion :: DrawWindowClass self => self -> Region -> Bool -> IO ()
- drawWindowGetUpdateArea :: DrawWindowClass self => self -> IO (Maybe Region)
- drawWindowFreezeUpdates :: DrawWindowClass self => self -> IO ()
- drawWindowThawUpdates :: DrawWindowClass self => self -> IO ()
- drawWindowProcessUpdates :: DrawWindowClass self => self -> Bool -> IO ()
- drawWindowSetAcceptFocus :: DrawWindowClass self => self -> Bool -> IO ()
- drawWindowShapeCombineMask :: DrawWindowClass self => self -> Maybe Pixmap -> Int -> Int -> IO ()
- drawWindowShapeCombineRegion :: DrawWindowClass self => self -> Maybe Region -> Int -> Int -> IO ()
- drawWindowSetChildShapes :: DrawWindowClass self => self -> IO ()
- drawWindowMergeChildShapes :: DrawWindowClass self => self -> IO ()
- drawWindowGetPointer :: DrawWindowClass self => self -> IO (Maybe (Bool, Int, Int, [Modifier]))
- drawWindowGetPointerPos :: DrawWindowClass self => self -> IO (Maybe DrawWindow, Int, Int, [Modifier])
- drawWindowGetOrigin :: DrawWindow -> IO (Int, Int)
- drawWindowSetCursor :: DrawWindow -> Maybe Cursor -> IO ()
- drawWindowForeignNew :: NativeWindowId -> IO (Maybe DrawWindow)
- drawWindowGetDefaultRootWindow :: IO DrawWindow

# Class Hierarchy

     | GObject
     | +----Drawable
     | +----DrawWindow

# Types

data DrawWindow

Instances

Eq DrawWindow |
Ord DrawWindow |
GObjectClass DrawWindow |
DrawWindowClass DrawWindow |
DrawableClass DrawWindow |

class DrawableClass o => DrawWindowClass o

Instances

DrawWindowClass DrawWindow |

castToDrawWindow :: GObjectClass obj => obj -> DrawWindow

gTypeDrawWindow :: GType

data WindowState

The state a `DrawWindow` is in.

Constructors

WindowStateWithdrawn |
WindowStateIconified |
WindowStateMaximized |
WindowStateSticky |
WindowStateFullscreen |
WindowStateAbove |
WindowStateBelow |

Instances

Bounded WindowState |
Enum WindowState | These are hints for the window manager that indicate what type of function the window has. The window manager can use this when determining decoration and behaviour of the window. The hint must be set before mapping the window. See the extended window manager hints specification for more details about window types.
Eq WindowState |
Show WindowState |
Flags WindowState |

data NativeWindowId

The identifer of a window of the underlying windowing system.

Instances

Eq NativeWindowId |
Show NativeWindowId |

toNativeWindowId :: Integral a => a -> NativeWindowId

fromNativeWindowId :: Integral a => NativeWindowId -> a

# Methods

drawWindowGetState

Arguments

:: DrawWindowClass self |
=> self |
-> IO [WindowState] | returns `DrawWindow` flags

Gets the bitwise OR of the currently active drawWindow state flags, from the `WindowState` enumeration.

drawWindowScroll

Arguments

:: DrawWindowClass self |
=> self |
-> Int | `dx` - Amount to scroll in the X direction
-> Int | `dy` - Amount to scroll in the Y direction
-> IO () |

Scroll the contents of `DrawWindow`.

- Scroll both, pixels and children, by the given amount. `DrawWindow` itself does not move. Portions of the window that the scroll operation brings inm from offscreen areas are invalidated. The invalidated region may be bigger than what would strictly be necessary. (For X11, a minimum area will be invalidated if the window has no subwindows, or if the edges of the window's parent do not extend beyond the edges of the drawWindow. In other cases, a multi-step process is used to scroll the window which may produce temporary visual artifacts and unnecessary invalidations.)

drawWindowClear :: DrawWindowClass self => self -> IO ()

Clears an entire `DrawWindow` to the background color or background pixmap.

drawWindowClearArea

Arguments

:: DrawWindowClass self |
=> self |
-> Int | `x` - x coordinate of rectangle to clear
-> Int | `y` - y coordinate of rectangle to clear
-> Int | `width` - width of rectangle to clear
-> Int | `height` - height of rectangle to clear
-> IO () |

Clears an area of `DrawWindow` to the background color or background pixmap.

drawWindowClearAreaExpose

Arguments

:: DrawWindowClass self |
=> self |
-> Int | `x` - x coordinate of rectangle to clear
-> Int | `y` - y coordinate of rectangle to clear
-> Int | `width` - width of rectangle to clear
-> Int | `height` - height of rectangle to clear
-> IO () |

Like `drawWindowClearArea`, but also generates an expose event for the cleared area.

drawWindowRaise :: DrawWindowClass self => self -> IO ()

Raises `DrawWindow` to the top of the Z-order (stacking order), so that other drawWindows with the same parent drawWindow appear below `DrawWindow`. This is true whether or not the drawWindows are visible.

If `DrawWindow` is a toplevel, the window manager may choose to deny the request to move the drawWindow in the Z-order, `drawWindowRaise` only requests the restack, does not guarantee it.

drawWindowLower :: DrawWindowClass self => self -> IO ()

Lowers `DrawWindow` to the bottom of the Z-order (stacking order), so that other windows with the same parent window appear above `DrawWindow`. This is true whether or not the other windows are visible.

If `DrawWindow` is a toplevel, the window manager may choose to deny the request to move the drawWindow in the Z-order, `drawWindowLower` only requests the restack, does not guarantee it.

Note that a widget is raised automatically when it is mapped, thus you need to call `drawWindowLower` after `widgetShow` if the window should not appear above other windows.

drawWindowBeginPaintRect

Arguments

:: DrawWindowClass self |
=> self |
-> Rectangle | `rectangle` - rectangle you intend to draw to
-> IO () |

A convenience wrapper around `drawWindowBeginPaintRegion` which creates a rectangular region for you.

- See `drawWindowBeginPaintRegion` for details.

drawWindowBeginPaintRegion

Arguments

:: DrawWindowClass self |
=> self |
-> Region | `region` - region you intend to draw to
-> IO () |

Indicate 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 pixmap for `DrawWindow`. Then, all drawing operations performed on `DrawWindow` will be diverted to the backing store. When you call `drawWindowEndPaint`, the backing store will be copied to `DrawWindow`, making it visible onscreen. Only the part of `DrawWindow` 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 `drawWindowEndPaint`. If you draw to `DrawWindow` directly without calling `drawWindowBeginPaintRegion`, the user may see flicker as individual drawing operations are performed in sequence. The clipping and background-initializing features of `drawWindowBeginPaintRegion` are conveniences for the programmer, so you can avoid doing that work yourself.

When using GTK+, the widget system automatically places calls to `drawWindowBeginPaintRegion` and `drawWindowEndPaint` around emissions of the `expose_event` signal. That is, if you're writing an expose event handler, you can assume that the exposed area in `eventRegion` 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 `drawWindowBeginPaintRegion`. (You can disable the automatic calls around expose events on a widget-by-widget basis by calling `widgetSetDoubleBuffered`.)

If you call this function multiple times before calling the matching `drawWindowEndPaint`, the backing stores are pushed onto a stack. `drawWindowEndPaint` 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 `drawWindowEndPaint` is required for each call to `drawWindowBeginPaintRegion`.

drawWindowEndPaint :: DrawWindowClass self => self -> IO ()

Signal that drawing has finished.

- Indicates that the backing store created by the most recent call to `drawWindowBeginPaintRegion` should be copied onscreen and deleted, leaving the next-most-recent backing store or no backing store at all as the active paint region. See `drawWindowBeginPaintRegion` for full details. It is an error to call this function without a matching `drawWindowBeginPaintRegion` first.

drawWindowInvalidateRect

Arguments

:: DrawWindowClass self |
=> self |
-> Rectangle | `rect` - rectangle to invalidate
-> Bool | `invalidateChildren` - whether to also invalidate child drawWindows
-> IO () |

A convenience wrapper around `drawWindowInvalidateRegion` which invalidates a rectangular region. See `drawWindowInvalidateRegion` for details.

drawWindowInvalidateRegion

Arguments

:: DrawWindowClass self |
=> self |
-> Region | `region` - a Region
-> Bool | `invalidateChildren` - `True` to also invalidate child drawWindows
-> IO () |

Adds `region` to the update area for `DrawWindow`. The update area is the region that needs to be redrawn, or "dirty region.". During the next idle period of the main look, an expose even for this region will be created. An application would normally redraw the contents of `DrawWindow` in response to those expose events.

The `invalidateChildren` parameter controls whether the region of each child drawWindow that intersects `region` will also be invalidated. If `False`, then the update area for child drawWindows will remain unaffected.

drawWindowGetUpdateArea

Arguments

:: DrawWindowClass self |
=> self |
-> IO (Maybe Region) | returns the update area for `DrawWindow`

Ask for the dirty region of this window.

- Transfers ownership of the update area from `DrawWindow` to the caller of the function. That is, after calling this function, `DrawWindow` will no longer have an invalid/dirty region; the update area is removed from `DrawWindow` and handed to you. If this window has no update area, `drawWindowGetUpdateArea` returns `Nothing`.

drawWindowFreezeUpdates :: DrawWindowClass self => self -> IO ()

Temporarily freezes a drawWindow such that it won't receive expose events. * The drawWindow will begin receiving expose events again when `drawWindowThawUpdates` is called. If `drawWindowFreezeUpdates` has been called more than once, `drawWindowThawUpdates` must be called an equal number of times to begin processing exposes.

drawWindowThawUpdates :: DrawWindowClass self => self -> IO ()

Thaws a drawWindow frozen with `drawWindowFreezeUpdates`.

drawWindowProcessUpdates

Arguments

:: DrawWindowClass self |
=> self |
-> Bool | `updateChildren` - whether to also process updates for child drawWindows
-> IO () |

Sends one or more expose events to `DrawWindow`.

- The areas in each expose event will cover the entire update area for the window (see `drawWindowInvalidateRegion` for details). Normally Gtk calls `drawWindowProcessUpdates` on your behalf, so there's no need to call this function unless you want to force expose events to be delivered immediately and synchronously (vs. the usual case, where Gtk delivers them in an idle handler). Occasionally this is useful to produce nicer scrolling behavior, for example.

drawWindowSetAcceptFocus

Arguments

:: DrawWindowClass self |
=> self |
-> Bool | `acceptFocus` - `True` if the drawWindow should receive input focus
-> IO () |

Setting `acceptFocus` to `False` hints the desktop environment that the window doesn't want to receive input focus.

On X, it is the responsibility of the drawWindow manager to interpret this hint. ICCCM-compliant drawWindow manager usually respect it.

- Available since Gdk version 2.4

drawWindowShapeCombineMask

Arguments

:: DrawWindowClass self |
=> self |
-> Maybe Pixmap | `mask` - region of drawWindow to be non-transparent
-> Int | `offsetX` - X position of `shapeRegion` in `DrawWindow` coordinates
-> Int | `offsetY` - Y position of `shapeRegion` in `DrawWindow` coordinates
-> IO () |

Applies a shape mask to window. Pixels in window corresponding to set bits in the mask will be visible; pixels in window corresponding to unset bits in the mask will be transparent. This gives a non-rectangular window.

- If `mask` is `Nothing`, the shape mask will be unset, and the x/y parameters are not used. The `mask` must be a bitmap, that is, a `Pixmap` of depth one.
- On the X11 platform, this uses an X server extension which is widely available on most common platforms, but not available on very old X servers, and occasionally the implementation will be buggy. On servers without the shape extension, this function will do nothing. On the Win32 platform the functionality is always present.
- This function works on both toplevel and child windows.

drawWindowShapeCombineRegion

Arguments

:: DrawWindowClass self |
=> self |
-> Maybe Region | `shapeRegion` - region of drawWindow to be non-transparent
-> Int | `offsetX` - X position of `shapeRegion` in `DrawWindow` coordinates
-> Int | `offsetY` - Y position of `shapeRegion` in `DrawWindow` coordinates
-> IO () |

Makes pixels in `DrawWindow` outside `shapeRegion` transparent.

- Makes pixels in `DrawWindow` outside `shapeRegion` transparent, so that the window may be nonrectangular.

If `shapeRegion` is `Nothing`, the shape will be unset, so the whole `DrawWindow` will be opaque again. The parameters `offsetX` and `offsetY` are ignored if `shapeRegion` is `Nothing`.

On the X11 platform, this uses an X server extension which is widely available on most common platforms, but not available on very old X servers, and occasionally the implementation will be buggy. On servers without the shape extension, this function will do nothing.

This function works on both toplevel and child drawWindows.

drawWindowSetChildShapes :: DrawWindowClass self => self -> IO ()

Sets the shape mask of `DrawWindow` to the union of shape masks for all children of `DrawWindow`, ignoring the shape mask of `DrawWindow` itself. Contrast with `drawWindowMergeChildShapes` which includes the shape mask of `DrawWindow` in the masks to be merged.

drawWindowMergeChildShapes :: DrawWindowClass self => self -> IO ()

Merges the shape masks for any child drawWindows into the shape mask for `DrawWindow`. i.e. the union of all masks for `DrawWindow` and its children will become the new mask for `DrawWindow`. See `drawWindowShapeCombineMask`.

This function is distinct from `drawWindowSetChildShapes` because it includes `DrawWindow`'s shape mask in the set of shapes to be merged.

drawWindowGetPointer :: DrawWindowClass self => self -> IO (Maybe (Bool, Int, Int, [Modifier]))

drawWindowGetPointerPos :: DrawWindowClass self => self -> IO (Maybe DrawWindow, Int, Int, [Modifier])

Obtains the current pointer position and modifier state.

- The position is given in coordinates relative to the given window.
- The return value is `(Just win, x, y, mod)` where `win` is the window over which the mouse currently resides and `mod` denotes the keyboard modifiers currently being depressed.
- The return value is `Nothing` for the window if the mouse cursor is not over a known window.

drawWindowGetOrigin

Arguments

:: DrawWindow |
-> IO (Int, Int) |
    (x, y)

Obtains the position of a window in screen coordinates.

You can use this to help convert a position between screen coordinates and local `DrawWindow` relative coordinates.

drawWindowSetCursor :: DrawWindow -> Maybe Cursor -> IO ()

Sets the mouse pointer for a `DrawWindow`.

Use `cursorNewForDisplay` or `cursorNewFromPixmap` to create the cursor. To make the cursor invisible, use `BlankCursor`. Passing `Nothing` means that the `DrawWindow` will use the cursor of its parent `DrawWindow`. Most `DrawWindow` should use this default.

drawWindowForeignNew :: NativeWindowId -> IO (Maybe DrawWindow)

Get the handle to an exising window of the windowing system. The passed-in handle is a reference to a native window, that is, an Xlib XID for X windows and a HWND for Win32.

drawWindowGetDefaultRootWindow

Arguments

:: IO DrawWindow | returns the default root window

Obtains the root window (parent all other windows are inside) for the default display and screen.