diff options
Diffstat (limited to 'gdk')
| -rw-r--r-- | gdk/gdkdraw.c | 51 | ||||
| -rw-r--r-- | gdk/gdkevents.c | 9 | ||||
| -rw-r--r-- | gdk/gdkimage.c | 15 | ||||
| -rw-r--r-- | gdk/gdkimage.h | 2 | ||||
| -rw-r--r-- | gdk/gdkkeys.c | 10 | ||||
| -rw-r--r-- | gdk/gdkpango.c | 12 | ||||
| -rw-r--r-- | gdk/gdkrgb.c | 18 | ||||
| -rw-r--r-- | gdk/gdkwindow.c | 255 | ||||
| -rw-r--r-- | gdk/x11/gdkcolor-x11.c | 19 | ||||
| -rw-r--r-- | gdk/x11/gdkcursor-x11.c | 21 | ||||
| -rw-r--r-- | gdk/x11/gdkevents-x11.c | 18 | ||||
| -rw-r--r-- | gdk/x11/gdkkeys-x11.c | 7 | ||||
| -rw-r--r-- | gdk/x11/gdkpango-x11.c | 13 | ||||
| -rw-r--r-- | gdk/x11/gdkpixmap-x11.c | 10 | ||||
| -rw-r--r-- | gdk/x11/gdkvisual-x11.c | 103 | ||||
| -rw-r--r-- | gdk/x11/gdkwindow-x11.c | 599 | ||||
| -rw-r--r-- | gdk/x11/gdkx.h | 4 |
17 files changed, 1131 insertions, 35 deletions
diff --git a/gdk/gdkdraw.c b/gdk/gdkdraw.c index b4de48a2f..e2d50121b 100644 --- a/gdk/gdkdraw.c +++ b/gdk/gdkdraw.c @@ -133,6 +133,10 @@ gdk_drawable_get_data (GdkDrawable *drawable, * Fills *@width and *@height with the size of @drawable. * @width or @height can be %NULL if you only want the other one. * + * On the X11 platform, if @drawable is a #GdkWindow, the returned + * size is the size reported in the most-recently-processed configure + * event, rather than the current size on the X server. + * **/ void gdk_drawable_get_size (GdkDrawable *drawable, @@ -423,6 +427,34 @@ gdk_draw_text_wc (GdkDrawable *drawable, GDK_DRAWABLE_GET_CLASS (drawable)->draw_text_wc (drawable, font, gc, x, y, text, text_length); } +/** + * gdk_draw_drawable: + * @drawable: a #GdkDrawable + * @gc: a #GdkGC sharing the drawable's visual and colormap + * @src: another #GdkDrawable + * @xsrc: X position in @src of rectangle to draw + * @ysrc: Y position in @src of rectangle to draw + * @xdest: X position in @drawable where the rectangle should be drawn + * @ydest: Y position in @drawable where the rectangle should be drawn + * @width: width of rectangle to draw, or -1 for entire @src width + * @height: height of rectangle to draw, or -1 for entire @src height + * + * Copies the @width x @height region of @src at coordinates (@xsrc, + * @ysrc) to coordinates (@xdest, @ydest) in @drawable. + * @width and/or @height may be given as -1, in which case the entire + * @src drawable will be copied. + * + * Most fields in @gc are not used for this operation, but notably the + * clip mask or clip region will be honored. + * + * The source and destination drawables must have the same visual and + * colormap, or errors will result. (On X11, failure to match + * visual/colormap results in a BadMatch error from the X server.) + * A common cause of this problem is an attempt to draw a bitmap to + * a color drawable. The way to draw a bitmap is to set the + * bitmap as a clip mask on your #GdkGC, then use gdk_draw_rectangle() + * to draw a rectangle clipped to the bitmap. + **/ void gdk_draw_drawable (GdkDrawable *drawable, GdkGC *gc, @@ -550,6 +582,25 @@ gdk_draw_lines (GdkDrawable *drawable, GDK_DRAWABLE_GET_CLASS (drawable)->draw_lines (drawable, gc, points, npoints); } +/** + * gdk_draw_glyphs: + * @drawable: a #GdkDrawable + * @gc: a #GdkGC + * @font: font to be used + * @x: X coordinate of baseline origin + * @y: Y coordinate of baseline origin + * @glyphs: glyphs to render + * + * This is a low-level function; 99% of text rendering should be done + * using gdk_draw_layout() instead. + * + * A glyph is a character in a font. This function draws a sequence of + * glyphs. To obtain a sequence of glyphs you have to understand a + * lot about internationalized text handling, which you don't want to + * understand; thus, use gdk_draw_layout() instead of this function, + * gdk_draw_layout() handles the details. + * + **/ void gdk_draw_glyphs (GdkDrawable *drawable, GdkGC *gc, diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c index 4aa9614e3..3547ad456 100644 --- a/gdk/gdkevents.c +++ b/gdk/gdkevents.c @@ -987,6 +987,15 @@ gdk_synthesize_window_state (GdkWindow *window, } } +/** + * gdk_set_double_click_time: + * @msec: double click time in milliseconds (thousandths of a second) + * + * Sets the double click time (two clicks within this time interval + * count as a double click and result in a #GDK_2BUTTON_PRESS event). + * Applications should NOT set this, it is a global user-configured setting. + * + **/ void gdk_set_double_click_time (guint msec) { diff --git a/gdk/gdkimage.c b/gdk/gdkimage.c index 2606f48a1..76ecc7eec 100644 --- a/gdk/gdkimage.c +++ b/gdk/gdkimage.c @@ -30,12 +30,27 @@ #include "gdkimage.h" #include "gdkprivate.h" +/** + * gdk_image_ref: + * @image: a #GdkImage + * + * Deprecated function; use g_object_ref() instead. + * + * Return value: the image + **/ GdkImage * gdk_image_ref (GdkImage *image) { return (GdkImage *) g_object_ref (G_OBJECT (image)); } +/** + * gdk_image_unref: + * @image: a #GdkImage + * + * Deprecated function; use g_object_unref() instead. + * + **/ void gdk_image_unref (GdkImage *image) { diff --git a/gdk/gdkimage.h b/gdk/gdkimage.h index 81e4679dd..3862b0fa6 100644 --- a/gdk/gdkimage.h +++ b/gdk/gdkimage.h @@ -72,8 +72,10 @@ GdkImage* gdk_image_get (GdkDrawable *drawable, gint width, gint height); +#ifndef GDK_DISABLE_DEPRECATED GdkImage * gdk_image_ref (GdkImage *image); void gdk_image_unref (GdkImage *image); +#endif void gdk_image_put_pixel (GdkImage *image, gint x, diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c index 86c13ccc3..ac66af1e2 100644 --- a/gdk/gdkkeys.c +++ b/gdk/gdkkeys.c @@ -98,6 +98,16 @@ gdk_keymap_class_init (GdkKeymapClass *klass) /* compatibility function from X11R6.3, since XConvertCase is not * supplied by X11R5. */ +/** + * gdk_keyval_convert_case: + * @symbol: a keyval + * @lower: return location for lowercase version of @symbol + * @upper: return location for uppercase version of @symbol + * + * Obtains the upper- and lower-case versions of the keyval @symbol. + * Examples of keyvals are #GDK_a, #GDK_Enter, #GDK_F1, etc. + * + **/ void gdk_keyval_convert_case (guint symbol, guint *lower, diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c index 5c355b343..1040068a4 100644 --- a/gdk/gdkpango.c +++ b/gdk/gdkpango.c @@ -126,6 +126,18 @@ gdk_pango_free_gc (PangoContext *context, gdk_gc_unref (gc); } +/** + * gdk_pango_context_set_colormap: + * @context: a #PangoContext + * @colormap: a #GdkColormap + * + * Sets the colormap to be used for drawing with @context. + * If you obtained your context from gtk_widget_get_pango_context() or + * gtk_widget_create_pango_context(), the colormap will already be set + * to the colormap for the widget, so you shouldn't need this + * function. + * + **/ void gdk_pango_context_set_colormap (PangoContext *context, GdkColormap *colormap) diff --git a/gdk/gdkrgb.c b/gdk/gdkrgb.c index 4c178b217..d7ce391cd 100644 --- a/gdk/gdkrgb.c +++ b/gdk/gdkrgb.c @@ -3342,6 +3342,24 @@ gdk_draw_rgb_32_image (GdkDrawable *drawable, image_info->conv_32_d, NULL, 0, 0); } +/** + * gdk_draw_rgb_32_image_dithalign: + * @drawable: a #GdkDrawable + * @gc: a #GdkGC + * @x: X coordinate on @drawable where image should go + * @y: Y coordinate on @drawable where image should go + * @width: width of area of image to draw + * @height: height of area of image to draw + * @dith: dithering mode + * @buf: RGB image data + * @rowstride: rowstride of RGB image data + * @xdith: X dither offset + * @ydith: Y dither offset + * + * Like gdk_draw_rgb_32_image(), but allows you to specify the dither + * offsets. See gdk_draw_rgb_image_dithalign() for more details. + * + **/ void gdk_draw_rgb_32_image_dithalign (GdkDrawable *drawable, GdkGC *gc, diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c index 7bb66ba54..68f540bdc 100644 --- a/gdk/gdkwindow.c +++ b/gdk/gdkwindow.c @@ -383,6 +383,18 @@ _gdk_window_destroy (GdkWindow *window, _gdk_window_destroy_hierarchy (window, FALSE, foreign_destroy); } +/** + * gdk_window_destroy: + * @window: a #GdkWindow + * + * Destroys @window (destroys the server-side resource associated with @window). + * Memory allocated for @window may not be freed until all references + * to @window are dropped. All children of @window are also destroyed. + * + * There's normally no need to use this function, window are automatically + * destroyed when their reference count reaches 0. + * + **/ void gdk_window_destroy (GdkWindow *window) { @@ -390,6 +402,20 @@ gdk_window_destroy (GdkWindow *window) gdk_drawable_unref (window); } +/** + * gdk_window_set_user_data: + * @window: a #GdkWindow + * @user_data: user data + * + * For most purposes this function is deprecated in favor of + * g_object_set_data(). However, for historical reasons GTK+ stores + * the #GtkWidget that owns a #GdkWindow as user data on the + * #GdkWindow. So, custom widget implementations should use + * this function for that. If GTK+ receives an event for a #GdkWindow, + * and the user data for the window is non-%NULL, GTK+ will assume the + * user data is a #GtkWidget, and forward the event to that widget. + * + **/ void gdk_window_set_user_data (GdkWindow *window, gpointer user_data) @@ -399,6 +425,15 @@ gdk_window_set_user_data (GdkWindow *window, ((GdkWindowObject*)window)->user_data = user_data; } +/** + * gdk_window_get_user_data: + * @window: a #GdkWindow + * @data: return location for user data + * + * Retrieves the user data for @window, which is normally the widget + * that @window belongs to. See gdk_window_set_user_data(). + * + **/ void gdk_window_get_user_data (GdkWindow *window, gpointer *data) @@ -408,6 +443,14 @@ gdk_window_get_user_data (GdkWindow *window, *data = ((GdkWindowObject*)window)->user_data; } +/** + * gdk_window_get_window_type: + * @window: a #GdkWindow + * + * Gets the type of the window. See #GdkWindowType. + * + * Return value: type of window + **/ GdkWindowType gdk_window_get_window_type (GdkWindow *window) { @@ -416,6 +459,20 @@ gdk_window_get_window_type (GdkWindow *window) return GDK_WINDOW_TYPE (window); } +/** + * gdk_window_get_position: + * @window: a #GdkWindow + * @x: X coordinate of window + * @y: Y coordinate of window + * + * Obtains the position of the window as reported in the most-recently-processed + * #GdkEventConfigure. Contrast with gdk_window_get_geometry() which + * queries the X server for the current window position, regardless of which + * events have been received or processed. + * + * The position coordinates are relative to the window's parent window. + * + **/ void gdk_window_get_position (GdkWindow *window, gint *x, @@ -433,6 +490,19 @@ gdk_window_get_position (GdkWindow *window, *y = obj->y; } +/** + * gdk_window_get_parent: + * @window: a #GdkWindow + * + * Obtains the parent of @window, as known to GDK. Does not query the + * X server; thus this returns the parent as passed to gdk_window_new(), + * not the actual parent. This should never matter unless you're using + * Xlib calls mixed with GDK calls on the X11 platform. It may also + * matter for toplevel windows, because the window manager may choose + * to reparent them. + * + * Return value: parent of @window + **/ GdkWindow* gdk_window_get_parent (GdkWindow *window) { @@ -441,6 +511,14 @@ gdk_window_get_parent (GdkWindow *window) return (GdkWindow*) ((GdkWindowObject*) window)->parent; } +/** + * gdk_window_get_toplevel: + * @window: a #GdkWindow + * + * Gets the toplevel window that's an ancestor of @window. + * + * Return value: the toplevel window containing @window + **/ GdkWindow* gdk_window_get_toplevel (GdkWindow *window) { @@ -455,6 +533,20 @@ gdk_window_get_toplevel (GdkWindow *window) return GDK_WINDOW (obj); } +/** + * gdk_window_get_children: + * @window: a #GdkWindow + * + * Gets the list of children of @window known to GDK. + * This function only returns children created via GDK, + * so for example it's useless when used with the root window; + * it only returns windows an application created itself. + * + * The returned list must be freed, but the elements in the + * list need not be. + * + * Return value: list of child windows inside @window + **/ GList* gdk_window_get_children (GdkWindow *window) { @@ -466,8 +558,17 @@ gdk_window_get_children (GdkWindow *window) return g_list_copy (GDK_WINDOW_OBJECT (window)->children); } +/** + * gdk_window_peek_children: + * @window: a #GdkWindow + * + * Like gdk_window_get_children(), but does not copy the list of + * children, so the list does not need to be freed. + * + * Return value: a reference to the list of child windows in @window + **/ GList * -gdk_window_peek_children (GdkWindow *window) +gdk_window_peek_children (GdkWindow *window) { g_return_val_if_fail (GDK_IS_WINDOW (window), NULL); @@ -477,6 +578,17 @@ gdk_window_peek_children (GdkWindow *window) return GDK_WINDOW_OBJECT (window)->children; } +/** + * gdk_window_add_filter: + * @window: a #GdkWindow + * @function: filter callback + * @data: data to pass to filter callback + * + * Adds an event filter to @window, allowing you to intercept events + * before they reach GDK. This is a low-level operation and makes it easy to break + * GDK and/or GTK+, so you have to know what you're doing. + * + **/ void gdk_window_add_filter (GdkWindow *window, GdkFilterFunc function, @@ -515,6 +627,15 @@ gdk_window_add_filter (GdkWindow *window, _gdk_default_filters = g_list_append (_gdk_default_filters, filter); } +/** + * gdk_window_remove_filter: + * @window: a #GdkWindow + * @function: previously-added filter function + * @data: user data for previously-added filter function + * + * Remove a filter previously added with gdk_window_add_filter(). + * + **/ void gdk_window_remove_filter (GdkWindow *window, GdkFilterFunc function, @@ -553,6 +674,18 @@ gdk_window_remove_filter (GdkWindow *window, } } +/** + * gdk_window_get_toplevels: + * + * Obtains a list of all toplevel windows known to GDK. + * A toplevel window is a child of the root window (see + * gdk_get_default_root_window()). + * + * The returned list should be freed with g_list_free(), but + * its elements need not be freed. + * + * Return value: list of toplevel windows, free with g_list_free() + **/ GList * gdk_window_get_toplevels (void) { @@ -569,15 +702,15 @@ gdk_window_get_toplevels (void) return new_list; } -/************************************************************* +/** * gdk_window_is_visible: - * Check if the given window is mapped. - * arguments: - * window: - * results: - * is the window mapped - *************************************************************/ - + * @window: a #GdkWindow + * + * Checks whether the window has been mapped (with gdk_window_show() or + * gdk_window_show_unraised()). + * + * Return value: %TRUE if the window is mapped + **/ gboolean gdk_window_is_visible (GdkWindow *window) { @@ -586,18 +719,19 @@ gdk_window_is_visible (GdkWindow *window) return GDK_WINDOW_IS_MAPPED (window); } -/************************************************************* +/** * gdk_window_is_viewable: - * Check if the window and all ancestors of the window - * are mapped. (This is not necessarily "viewable" in - * the X sense, since we only check as far as we have - * GDK window parents, not to the root window) - * arguments: - * window: - * results: - * is the window viewable - *************************************************************/ - + * @window: a #GdkWindow + * + * Check if the window and all ancestors of the window are + * mapped. (This is not necessarily "viewable" in the X sense, since + * we only check as far as we have GDK window parents, not to the root + * window) + * + * + * + * Return value: %TRUE if the window is viewable + **/ gboolean gdk_window_is_viewable (GdkWindow *window) { @@ -1609,6 +1743,12 @@ gdk_window_clear_backing_rect (GdkWindow *window, gdk_gc_unref (tmp_gc); } +/** + * gdk_window_clear: + * @window: a #GdkWindow + * + * Clears an entire @window to the background color or background pixmap. + **/ void gdk_window_clear (GdkWindow *window) { @@ -1623,6 +1763,17 @@ gdk_window_clear (GdkWindow *window) width, height); } +/** + * gdk_window_clear_area: + * @window: a #GdkWindow + * @x: x coordinate of rectangle to clear + * @y: y coordinate of rectangle to clear + * @width: width of rectangle to clear + * @height: height of rectangle to clear + * + * Clears an area of @window to the background color or background pixmap. + * + **/ void gdk_window_clear_area (GdkWindow *window, gint x, @@ -1641,6 +1792,21 @@ gdk_window_clear_area (GdkWindow *window, _gdk_windowing_window_clear_area (window, x, y, width, height); } +/** + * gdk_window_clear_area_e: + * @window: a #GdkWindow + * @x: x coordinate of rectangle to clear + * @y: y coordinate of rectangle to clear + * @width: width of rectangle to clear + * @height: height of rectangle to clear + * + * Like gdk_window_clear_area(), but also generates an expose event for + * the cleared area. + * + * This function has a stupid name because it dates back to the mists + * time, pre-GDK-1.0. + * + **/ void gdk_window_clear_area_e (GdkWindow *window, gint x, @@ -2155,6 +2321,16 @@ _gdk_window_clear_update_area (GdkWindow *window) } } +/** + * gdk_window_freeze_updates: + * @window: a #GdkWindow + * + * Temporarily freezes a window such that it won't receive expose + * events. The window will begin receiving expose events again when + * gdk_window_thaw_updates() is called. If gdk_window_freeze_updates() + * has been called more than once, gdk_window_thaw_updates() must be called + * an equal number of times to begin processing exposes. + **/ void gdk_window_freeze_updates (GdkWindow *window) { @@ -2166,6 +2342,12 @@ gdk_window_freeze_updates (GdkWindow *window) private->update_freeze_count++; } +/** + * gdk_window_thaw_updates: + * @window: a #GdkWindow + * + * Thaws a window frozen with gdk_window_freeze_updates(). + **/ void gdk_window_thaw_updates (GdkWindow *window) { @@ -2368,6 +2550,19 @@ gdk_set_pointer_hooks (const GdkPointerHooks *new_hooks) return (GdkPointerHooks *)result; } +/** + * gdk_window_get_pointer: + * @window: a #GdkWindow + * @x: return location for X coordinate of pointer + * @y: return location for Y coordinate of pointer + * @mask: return location for modifier mask + * + * Obtains the current pointer position and modifier state. + * The position is given in coordinates relative to @window. + * + * Return value: the window containing the pointer (as with gdk_window_at_pointer()), or %NULL + * if the window containing the pointer isn't known to GDK + **/ GdkWindow* gdk_window_get_pointer (GdkWindow *window, gint *x, @@ -2379,6 +2574,18 @@ gdk_window_get_pointer (GdkWindow *window, return current_pointer_hooks->get_pointer (window, x, y, mask); } +/** + * gdk_window_at_pointer: + * @win_x: return location for origin of the window under the pointer + * @win_y: return location for origin of the window under the pointer + * + * Obtains the window underneath the mouse pointer, returning the location + * of that window in @win_x, @win_y. Returns %NULL if the window under + * the mouse pointer is not known to GDK (for example, belongs to + * another application). + * + * Return value: window under the mouse pointer + **/ GdkWindow* gdk_window_at_pointer (gint *win_x, gint *win_y) @@ -2386,6 +2593,14 @@ gdk_window_at_pointer (gint *win_x, return current_pointer_hooks->window_at_pointer (win_x, win_y); } +/** + * gdk_get_default_root_window: + * + * Obtains the root window (parent all other windows are inside) + * for the default display and screen. + * + * Return value: the default root window + **/ GdkWindow * gdk_get_default_root_window (void) { diff --git a/gdk/x11/gdkcolor-x11.c b/gdk/x11/gdkcolor-x11.c index e6a2abae5..71ca25d33 100644 --- a/gdk/x11/gdkcolor-x11.c +++ b/gdk/x11/gdkcolor-x11.c @@ -993,6 +993,24 @@ gdk_colormap_alloc_colors (GdkColormap *colormap, return nremaining; } +/** + * gdk_colormap_query_color: + * @colormap: a #GdkColormap + * @pixel: pixel value in hardware display format + * @result: #GdkColor with red, green, blue fields initialized + * + * Locates the RGB color in @colormap corresponding to the given + * hardware pixel @pixel. @pixel must be a valid pixel in the + * colormap; it's a programmer error to call this function with a + * pixel which is not in the colormap. Hardware pixels are normally + * obtained from gdk_colormap_alloc_colors(), or from a #GdkImage. (A + * #GdkImage contains image data in hardware format, a #GdkPixbuf + * contains image data in a canonical 24-bit RGB format.) + * + * This function is rarely useful, it's used for example to + * implement the eyedropper feature in #GtkColorSelection. + * + **/ void gdk_colormap_query_color (GdkColormap *colormap, gulong pixel, @@ -1027,6 +1045,7 @@ gdk_colormap_query_color (GdkColormap *colormap, result->blue = xcolor.blue; break; case GDK_VISUAL_PSEUDO_COLOR: + g_return_if_fail (pixel < colormap->size); result->red = colormap->colors[pixel].red; result->green = colormap->colors[pixel].green; result->blue = colormap->colors[pixel].blue; diff --git a/gdk/x11/gdkcursor-x11.c b/gdk/x11/gdkcursor-x11.c index 82e6dbb46..3c024be83 100644 --- a/gdk/x11/gdkcursor-x11.c +++ b/gdk/x11/gdkcursor-x11.c @@ -32,6 +32,27 @@ #include "gdkpixmap-x11.h" #include <gdk/gdkpixmap.h> +/** + * gdk_cursor_new: + * @cursor_type: cursor to create + * + * Creates a new cursor from the set of builtin cursors. + * Some useful ones are: #GDK_RIGHT_PTR (right-facing arrow), + * #GDK_CROSSHAIR (crosshair), #GDK_IBEAM (I-beam), #GDK_WATCH (busy), + * #GDK_FLEUR (for moving objects), #GDK_HAND (a pointing hand), + * #GDK_LEFT_SIDE (resize left side), #GDK_RIGHT_SIDE (resize right side), + * #GDK_TOP_LEFT_CORNER (resize northwest corner), #GDK_TOP_RIGHT_CORNER (resize + * northeast corner), #GDK_BOTTOM_LEFT_CORNER (resize southwest corner), + * #GDK_BOTTOM_RIGHT_CORNER (resize southeast corner), + * #GDK_TOP_SIDE (resize top side), #GDK_BOTTOM (resize bottom side), + * #GDK_SB_H_DOUBLE_ARROW (move vertical splitter), + * #GDK_SB_V_DOUBLE_ARROW (move horizontal splitter). + * + * To make the cursor invisible, use gdk_cursor_new_from_pixmap() to create + * a cursor with no pixels in it. + * + * Return value: a new #GdkCursor + **/ GdkCursor* gdk_cursor_new (GdkCursorType cursor_type) { diff --git a/gdk/x11/gdkevents-x11.c b/gdk/x11/gdkevents-x11.c index 02f2a7803..67c951cac 100644 --- a/gdk/x11/gdkevents-x11.c +++ b/gdk/x11/gdkevents-x11.c @@ -1946,6 +1946,24 @@ gdk_x11_get_server_time (GdkWindow *window) } +/** + * gdk_net_wm_supports: + * @property: a property atom + * + * This function is specific to the X11 backend of GDK, and indicates + * whether the window manager supports a certain hint from the + * Extended Window Manager Hints Specification. You can find this + * specification on http://www.freedesktop.org. + * + * When using this function, keep in mind that the window manager + * can change over time; so you shouldn't use this function in + * a way that impacts persistent application state. A common bug + * is that your application can start up before the window manager + * does when the user logs in, and before the window manager starts + * gdk_net_wm_supports() will return %FALSE for every property. + * + * Return value: %TRUE if the window manager supports @property + **/ gboolean gdk_net_wm_supports (GdkAtom property) { diff --git a/gdk/x11/gdkkeys-x11.c b/gdk/x11/gdkkeys-x11.c index 620d41752..25fdd4a68 100644 --- a/gdk/x11/gdkkeys-x11.c +++ b/gdk/x11/gdkkeys-x11.c @@ -100,6 +100,13 @@ static PangoDirection current_direction; static gboolean have_direction = FALSE; static GdkKeymap *default_keymap = NULL; +/** + * gdk_keymap_get_default: + * + * Gets the #GdkKeymap for the default display. + * + * Return value: the default keymap + **/ GdkKeymap* gdk_keymap_get_default (void) { diff --git a/gdk/x11/gdkpango-x11.c b/gdk/x11/gdkpango-x11.c index 3900de59b..411bf01b2 100644 --- a/gdk/x11/gdkpango-x11.c +++ b/gdk/x11/gdkpango-x11.c @@ -27,6 +27,19 @@ #include <pango/pangoxft.h> #endif +/** + * gdk_pango_context_get: + * + * Creates a #PangoContext for the default GDK display. + * + * The context must be freed when you're finished with it. + * + * When using GTK+, normally you should use gtk_widget_get_pango_context() + * instead of this function, to get the appropriate context for + * the widget you intend to render text onto. + * + * Return value: a new #PangoContext for the default display + **/ PangoContext * gdk_pango_context_get (void) { diff --git a/gdk/x11/gdkpixmap-x11.c b/gdk/x11/gdkpixmap-x11.c index 3c69ed7aa..a231a0e79 100644 --- a/gdk/x11/gdkpixmap-x11.c +++ b/gdk/x11/gdkpixmap-x11.c @@ -284,6 +284,16 @@ gdk_pixmap_create_from_data (GdkWindow *window, return pixmap; } +/** + * gdk_pixmap_foreign_new: + * @anid: an X window ID for a pixmap + * + * Creates a #GdkPixmap for the Xlib pixmap ID @anid. + * If the Xlib pixmap is destroyed while creating + * the #GdkPixmap, this function returns %NULL. + * + * Return value: a new #GdkPixmap + **/ GdkPixmap* gdk_pixmap_foreign_new (GdkNativeWindow anid) { diff --git a/gdk/x11/gdkvisual-x11.c b/gdk/x11/gdkvisual-x11.c index 66c42ff76..32d44dfb7 100644 --- a/gdk/x11/gdkvisual-x11.c +++ b/gdk/x11/gdkvisual-x11.c @@ -310,30 +310,75 @@ _gdk_visual_init (void) g_error ("unable to find a usable visual type"); } +/** + * gdk_visual_get_best_depth: + * + * Get the best available depth for the default GDK display. "Best" + * means "largest," i.e. 32 preferred over 24 preferred over 8 bits + * per pixel. + * + * Return value: best available depth + **/ gint gdk_visual_get_best_depth (void) { return available_depths[0]; } +/** + * gdk_visual_get_best_type: + * + * Return the best available visual type (the one with the most + * colors) for the default GDK display. + * + * Return value: best visual type + **/ GdkVisualType gdk_visual_get_best_type (void) { return available_types[0]; } +/** + * gdk_visual_get_system: + * + * Get the default or system visual for the default GDK display. + * This is the visual for the root window of the display. + * The return value should not be freed. + * + * Return value: system visual + **/ GdkVisual* gdk_visual_get_system (void) { return ((GdkVisual*) system_visual); } +/** + * gdk_visual_get_best: + * + * Get the visual with the most available colors for the default + * GDK display. The return value should not be freed. + * + * Return value: best visual + **/ GdkVisual* gdk_visual_get_best (void) { return ((GdkVisual*) visuals[0]); } +/** + * gdk_visual_get_best_with_depth: + * @depth: a bit depth + * + * Get the best visual with depth @depth for the default GDK display. + * Color visuals and visuals with mutable colormaps are preferred + * over grayscale or fixed-colormap visuals. The return value should not + * be freed. %NULL may be returned if no visual supports @depth. + * + * Return value: best visual for the given depth + **/ GdkVisual* gdk_visual_get_best_with_depth (gint depth) { @@ -351,6 +396,17 @@ gdk_visual_get_best_with_depth (gint depth) return return_val; } +/** + * gdk_visual_get_best_with_type: + * @visual_type: a visual type + * + * Get the best visual of the given @visual_type for the default GDK display. + * Visuals with higher color depths are considered better. The return value + * should not be freed. %NULL may be returned if no visual has type + * @visual_type. + * + * Return value: best visual of the given type + **/ GdkVisual* gdk_visual_get_best_with_type (GdkVisualType visual_type) { @@ -368,6 +424,15 @@ gdk_visual_get_best_with_type (GdkVisualType visual_type) return return_val; } +/** + * gdk_visual_get_best_with_both: + * @depth: a bit depth + * @visual_type: a visual type + * + * Combines gdk_visual_get_best_with_depth() and gdk_visual_get_best_with_type(). + * + * Return value: best visual with both @depth and @visual_type, or %NULL if none + **/ GdkVisual* gdk_visual_get_best_with_both (gint depth, GdkVisualType visual_type) @@ -387,6 +452,19 @@ gdk_visual_get_best_with_both (gint depth, return return_val; } +/** + * gdk_query_depths: + * @depths: return location for available depths + * @count: return location for number of available depths + * + * This function returns the available bit depths for the default + * display. It's equivalent to listing the visuals + * (gdk_list_visuals()) and then looking at the depth field in each + * visual, removing duplicates. + * + * The array returned by this function should not be freed. + * + **/ void gdk_query_depths (gint **depths, gint *count) @@ -395,6 +473,19 @@ gdk_query_depths (gint **depths, *depths = available_depths; } +/** + * gdk_query_visual_types: + * @visual_types: return location for the available visual types + * @count: return location for the number of available visual types + * + * This function returns the available visual types for the default + * display. It's equivalent to listing the visuals + * (gdk_list_visuals()) and then looking at the type field in each + * visual, removing duplicates. + * + * The array returned by this function should not be freed. + * + **/ void gdk_query_visual_types (GdkVisualType **visual_types, gint *count) @@ -403,6 +494,18 @@ gdk_query_visual_types (GdkVisualType **visual_types, *visual_types = available_types; } +/** + * gdk_list_visuals: + * + * Lists the available visuals for the default display. + * A visual describes a hardware image data format. + * For example, a visual might support 24-bit color, or 8-bit color, + * and might expect pixels to be in a certain format. + * + * Call g_list_free() on the return value when you're finished with it. + * + * Return value: a list of visuals; the list must be freed, but not its contents + **/ GList* gdk_list_visuals (void) { diff --git a/gdk/x11/gdkwindow-x11.c b/gdk/x11/gdkwindow-x11.c index da6221021..94a54a4ec 100644 --- a/gdk/x11/gdkwindow-x11.c +++ b/gdk/x11/gdkwindow-x11.c @@ -300,6 +300,17 @@ _gdk_windowing_window_init (void) static GdkAtom wm_client_leader_atom = GDK_NONE; +/** + * gdk_window_new: + * @parent: a #GdkWindow + * @attributes: attributes of the new window + * @attributes_mask: mask indicating which fields in @attributes are valid + * + * Creates a new #GdkWindow using the attributes from @attributes. See + * #GdkWindowAttr and #GdkWindowAttributesType for more details. + * + * Return value: the new #GdkWindow + **/ GdkWindow* gdk_window_new (GdkWindow *parent, GdkWindowAttr *attributes, @@ -615,6 +626,15 @@ gdk_window_new (GdkWindow *parent, return window; } +/** + * gdk_window_foreign_new: + * @anid: an Xlib window ID + * + * Wraps an X window ID (from Xlib) with a #GdkWindow. + * May fail if the window has been destroyed, if so returns %NULL. + * + * Return value: the #GdkWindow wrapper for the X window + **/ GdkWindow * gdk_window_foreign_new (GdkNativeWindow anid) { @@ -866,6 +886,10 @@ show_window_internal (GdkWindow *window, * Shows a #GdkWindow onscreen, but does not modify its stacking * order. In contrast, gdk_window_show() will raise the window * to the top of the window stack. + * + * On the X11 platform, in Xlib terms, this function calls + * XMapWindow() (it also updates some internal GDK state, which means + * that you can't really use XMapWindow() directly on a GDK window). * **/ void @@ -876,6 +900,21 @@ gdk_window_show_unraised (GdkWindow *window) show_window_internal (window, FALSE); } +/** + * gdk_window_show: + * @window: a #GdkWindow + * + * Like gdk_window_show_unraised(), but also raises the window to the + * top of the window stack (moves the window to the front of the + * Z-order). + * + * This function maps a window so it's visible onscreen. Its opposite + * is gdk_window_hide(). + * + * When implementing a #GtkWidget, you should call this function on the widget's + * #GdkWindow as part of the "map" method. + * + **/ void gdk_window_show (GdkWindow *window) { @@ -884,6 +923,16 @@ gdk_window_show (GdkWindow *window) show_window_internal (window, TRUE); } +/** + * gdk_window_hide: + * @window: a #GdkWindow + * + * For toplevel windows, withdraws them, so they will no longer be + * known to the window manager; for all windows, unmaps them, so + * they won't be displayed. Normally done automatically as + * part of gtk_widget_hide(). + * + **/ void gdk_window_hide (GdkWindow *window) { @@ -925,6 +974,14 @@ gdk_window_hide (GdkWindow *window) } } +/** + * gdk_window_withdraw: + * @window: a toplevel #GdkWindow + * + * Withdraws a window (unmaps it and asks the window manager to forget about it). + * Normally done automatically by gtk_widget_hide() called on a #GtkWindow. + * + **/ void gdk_window_withdraw (GdkWindow *window) { @@ -947,6 +1004,22 @@ gdk_window_withdraw (GdkWindow *window) } } +/** + * gdk_window_move: + * @window: a #GdkWindow + * @x: X coordinate relative to window's parent + * @y: Y coordinate relative to window's parent + * + * Repositions a window relative to its parent window. + * For toplevel windows, window managers may ignore or modify the move; + * you should probably use gtk_window_move() on a #GtkWindow widget + * anyway, instead of using GDK functions. For child windows, + * the move will reliably succeed. + * + * If you're also planning to resize the window, use gdk_window_move_resize() + * to both move and resize simultaneously, for a nicer visual effect. + * + **/ void gdk_window_move (GdkWindow *window, gint x, @@ -974,6 +1047,22 @@ gdk_window_move (GdkWindow *window, } } +/** + * gdk_window_resize: + * @window: a #GdkWindow + * @width: new width of the window + * @height: new height of the window + * + * Resizes @window; for toplevel windows, asks the window manager to resize + * the window. The window manager may not allow the resize. When using GTK+, + * use gtk_window_resize() instead of this low-level GDK function. + * + * Windows may not be resized below 1x1. + * + * If you're also planning to move the window, use gdk_window_move_resize() + * to both move and resize simultaneously, for a nicer visual effect. + * + **/ void gdk_window_resize (GdkWindow *window, gint width, @@ -1010,6 +1099,20 @@ gdk_window_resize (GdkWindow *window, } } +/** + * gdk_window_move_resize: + * @window: a #GdkWindow + * @x: new X position relative to window's parent + * @y: new Y position relative to window's parent + * @width: new width + * @height: new height + * + * Equivalent to calling gdk_window_move() and gdk_window_resize(), + * except that both operations are performed at once, avoiding strange + * visual effects. (i.e. the user may be able to see the window first + * move, then resize, if youu don't use gdk_window_move_resize().) + * + **/ void gdk_window_move_resize (GdkWindow *window, gint x, @@ -1047,6 +1150,17 @@ gdk_window_move_resize (GdkWindow *window, } } +/** + * gdk_window_reparent: + * @window: a #GdkWindow + * @new_parent: new parent to move @window into + * @x: X location inside the new parent + * @y: Y location inside the new parent + * + * Reparents @window into the given @new_parent. The window being + * reparented will be unmapped as a side effect. + * + **/ void gdk_window_reparent (GdkWindow *window, GdkWindow *new_parent, @@ -1149,6 +1263,18 @@ _gdk_windowing_window_clear_area_e (GdkWindow *window, x, y, width, height, True); } + +/** + * gdk_window_raise: + * @window: a #GdkWindow + * + * Raises @window to the top of the Z-order (stacking order), so that + * other windows with the same parent window appear below @window. + * If @window is a toplevel, the window manager may choose to deny the + * request to move the window in the Z-order, gdk_window_raise() only + * requests the restack, does not guarantee it. + * + **/ void gdk_window_raise (GdkWindow *window) { @@ -1159,6 +1285,20 @@ gdk_window_raise (GdkWindow *window) XRaiseWindow (GDK_WINDOW_XDISPLAY (window), GDK_WINDOW_XID (window)); } +/** + * gdk_window_lower: + * @window: a #GdkWindow + * + * Lowers @window to the bottom of the Z-order (stacking order), so that + * other windows with the same parent window appear above @window. + * If @window is a toplevel, the window manager may choose to deny the + * request to move the window in the Z-order, gdk_window_lower() only + * requests the restack, does not guarantee it. + * + * Note that gdk_window_show() raises the window again, so don't call this + * function before gdk_window_show(). (Try gdk_window_show_unraised().) + * + **/ void gdk_window_lower (GdkWindow *window) { @@ -1169,6 +1309,16 @@ gdk_window_lower (GdkWindow *window) XLowerWindow (GDK_WINDOW_XDISPLAY (window), GDK_WINDOW_XID (window)); } +/** + * gdk_window_focus: + * @window: a #GdkWindow + * @timestamp: timestamp of the event triggering the window focus + * + * Sets keyboard focus to @window. If @window is not onscreen this + * will not work. In most cases, gtk_window_present() should be used on + * a #GtkWindow, rather than calling this function. + * + **/ void gdk_window_focus (GdkWindow *window, guint32 timestamp) @@ -1212,6 +1362,25 @@ gdk_window_focus (GdkWindow *window, } } +/** + * gdk_window_set_hints: + * @window: a #GdkWindow + * @x: ignored field, does not matter + * @y: ignored field, does not matter + * @min_width: minimum width hint + * @min_height: minimum height hint + * @max_width: max width hint + * @max_height: max height hint + * @flags: logical OR of GDK_HINT_POS, GDK_HINT_MIN_SIZE, and/or GDK_HINT_MAX_SIZE + * + * This function is broken and useless and you should ignore it. + * If using GTK+, use functions such as gtk_window_resize(), gtk_window_set_size_request(), + * gtk_window_move(), gtk_window_parse_geometry(), and gtk_window_set_geometry_hints(), + * depending on what you're trying to do. + * + * If using GDK directly, use gdk_window_set_geometry_hints(). + * + **/ void gdk_window_set_hints (GdkWindow *window, gint x, @@ -1604,12 +1773,25 @@ set_text_property (GdkWindow *window, } } +/** + * gdk_window_set_title: + * @window: a #GdkWindow + * @title: title of @window + * + * Sets the title of a toplevel window, to be displayed in the titlebar. + * If you haven't explicitly set the icon name for the window + * (using gdk_window_set_icon_name()), the icon name will be set to + * @title as well. @title must be in UTF-8 encoding (as with all + * user-readable strings in GDK/GTK+). @title may not be %NULL. + * + **/ void gdk_window_set_title (GdkWindow *window, const gchar *title) { g_return_if_fail (window != NULL); g_return_if_fail (GDK_IS_WINDOW (window)); + g_return_if_fail (title != NULL); if (GDK_WINDOW_DESTROYED (window)) return; @@ -1634,6 +1816,25 @@ gdk_window_set_title (GdkWindow *window, } } +/** + * gdk_window_set_role: + * @window: a #GdkWindow + * @role: a string indicating its role + * + * When using GTK+, typically you should use gtk_window_set_role() instead + * of this low-level function. + * + * The window manager and session manager use a window's role to + * distinguish it from other kinds of window in the same application. + * When an application is restarted after being saved in a previous + * session, all windows with the same title and role are treated as + * interchangeable. So if you have two windows with the same title + * that should be distinguished for session management purposes, you + * should set the role on those windows. It doesn't matter what string + * you use for the role, as long as you have a different role for each + * non-interchangeable kind of window. + * + **/ void gdk_window_set_role (GdkWindow *window, const gchar *role) @@ -1653,6 +1854,20 @@ gdk_window_set_role (GdkWindow *window, } } +/** + * gdk_window_set_transient_for: + * @window: a toplevel #GdkWindow + * @parent: another toplevel #GdkWindow + * + * Indicates to the window manager that @window is a transient dialog + * associated with the application window @parent. This allows the + * window manager to do things like center @window on @parent and + * keep @window above @parent. + * + * See gtk_window_set_transient_for() if you're using #GtkWindow or + * #GtkDialog. + * + **/ void gdk_window_set_transient_for (GdkWindow *window, GdkWindow *parent) @@ -1672,6 +1887,22 @@ gdk_window_set_transient_for (GdkWindow *window, GDK_WINDOW_XID (parent)); } +/** + * gdk_window_set_background: + * @window: a #GdkWindow + * @color: an allocated #GdkColor + * + * Sets the background color of @window. (However, when using GTK+, + * set the background of a widget with gtk_widget_modify_bg() - if + * you're an application - or gtk_style_set_background() - if you're + * implementing a custom widget.) + * + * The @color must be allocated; gdk_rgb_find_color() is the best way + * to allocate a color. + * + * See also gdk_window_set_back_pixmap(). + * + **/ void gdk_window_set_background (GdkWindow *window, GdkColor *color) @@ -1696,6 +1927,30 @@ gdk_window_set_background (GdkWindow *window, } } +/** + * gdk_window_set_back_pixmap: + * @window: a #GdkWindow + * @pixmap: a #GdkPixmap, or %NULL + * @parent_relative: whether the tiling origin is at the origin of @window's parent + * + * Sets the background pixmap of @window. May also be used to set a background of + * "None" on @window, by setting a background pixmap of %NULL. + * A background pixmap will be tiled, positioning the first tile at the origin of + * @window, or if @parent_relative is %TRUE, the tiling will be done based on the + * origin of the parent window (useful to align tiles in a parent with tiles + * in a child). + * + * A background pixmap of %NULL means that the window will have no + * background. A window with no background will never have its + * background filled by the windowing system, instead the window will + * contain whatever pixels were already in the corresponding area of + * the display. + * + * The windowing system will normally fill a window with its background + * when the window is obscured then exposed, and when you call + * gdk_window_clear(). + * + **/ void gdk_window_set_back_pixmap (GdkWindow *window, GdkPixmap *pixmap, @@ -1738,6 +1993,19 @@ gdk_window_set_back_pixmap (GdkWindow *window, GDK_WINDOW_XID (window), xpixmap); } +/** + * gdk_window_set_cursor: + * @window: a #GdkWindow + * @cursor: a cursor + * + * Sets the mouse pointer for a #GdkWindow. Use gdk_cursor_new() or + * gdk_cursor_new_from_pixmap() to create the cursor. + * To make the cursor invisible, use gdk_cursor_new_from_pixmap() to create + * a cursor with no pixels in it. Passing %NULL for the @cursor argument + * to gdk_window_set_cursor() means that @window will use the cursor of + * its parent window. Most windows should use this default. + * + **/ void gdk_window_set_cursor (GdkWindow *window, GdkCursor *cursor) @@ -1761,6 +2029,30 @@ gdk_window_set_cursor (GdkWindow *window, xcursor); } +/** + * gdk_window_get_geometry: + * @window: a #GdkWindow + * @x: return location for X coordinate of window (relative to its parent) + * @y: return location for Y coordinate of window (relative to its parent) + * @width: return location for width of window + * @height: return location for height of window + * @depth: return location for bit depth of window + * + * Any of the return location arguments to this function may be %NULL, + * if you aren't interested in getting the value of that field. + * + * The X and Y coordinates returned are relative to the parent window + * of @window, which for toplevels usually means relative to the + * window decorations (titlebar, etc.) rather than relative to the + * root window (screen-size background window). + * + * On the X11 platform, the geometry is obtained from the X server, + * so reflects the latest position of @window; this may be out-of-sync + * with the position of @window delivered in the most-recently-processed + * #GdkEventConfigure. gdk_window_get_position() in contrast gets the + * position from the most recent configure event. + * + **/ void gdk_window_get_geometry (GdkWindow *window, gint *x, @@ -2102,6 +2394,14 @@ _gdk_windowing_window_at_pointer (gint *win_x, return window; } +/** + * gdk_window_get_events: + * @window: a #GdkWindow + * + * Gets the event mask for @window. See gdk_window_set_events(). + * + * Return value: event mask for @window + **/ GdkEventMask gdk_window_get_events (GdkWindow *window) { @@ -2131,6 +2431,17 @@ gdk_window_get_events (GdkWindow *window) } } +/** + * gdk_window_set_events: + * @window: a #GdkWindow + * @event_mask: event mask for @window + * + * The event mask for a window determines which events will be reported + * for that window. For example, an event mask including #GDK_BUTTON_PRESS_MASK + * means the window should report button press events. The event mask + * is the bitwise OR of values from the #GdkEventMask enumeration. + * + **/ void gdk_window_set_events (GdkWindow *window, GdkEventMask event_mask) @@ -2226,6 +2537,28 @@ gdk_window_have_shape_ext (void) * If not available, shaped windows will look * ugly, but programs still work. Stefan Wille */ +/** + * gdk_window_shape_combine_mask: + * @window: a #GdkWindow + * @mask: shape mask + * @x: X position of shape mask with respect to @window + * @y: Y position of shape mask with respect to @window + * + * 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 %NULL, the shape mask will be unset, and the @x/@y + * parameters are not used. + * + * 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. + * + **/ void gdk_window_shape_combine_mask (GdkWindow *window, GdkBitmap *mask, @@ -2272,6 +2605,28 @@ gdk_window_shape_combine_mask (GdkWindow *window, #endif /* HAVE_SHAPE_EXT */ } +/** + * gdk_window_shape_combine_region: + * @window: a #GdkWindow + * @shape_region: region of window to be non-transparent + * @offset_x: X position of @shape_region in @window coordinates + * @offset_y: Y position of @shape_region in @window coordinates + * + * Makes pixels in @window outside @shape_region be transparent, + * so that the window may be nonrectangular. See also + * gdk_window_shape_combine_mask() to use a bitmap as the mask. + * + * If @shape_region is %NULL, the shape will be unset, so the whole + * window will be opaque again. @offset_x and @offset_y are ignored + * if @shape_region is %NULL. + * + * 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. + * + **/ void gdk_window_shape_combine_region (GdkWindow *window, GdkRegion *shape_region, @@ -2324,6 +2679,21 @@ gdk_window_shape_combine_region (GdkWindow *window, } +/** + * gdk_window_set_override_redirect: + * @window: a #GdkWindow + * @override_redirect: %TRUE if window should be override redirect + * + * An override redirect window is not under the control of the window manager. + * This means it won't have a titlebar, won't be minimizable, etc. - it will + * be entirely under the control of the application. The window manager + * can't see the override redirect window at all. + * + * Override redirect should only be used for short-lived temporary + * windows, such as popup menus. #GtkMenu uses an override redirect + * window in its implementation, for example. + * + **/ void gdk_window_set_override_redirect (GdkWindow *window, gboolean override_redirect) @@ -2449,6 +2819,20 @@ gdk_window_set_icon_list (GdkWindow *window, } } +/** + * gdk_window_set_icon: + * @window: a #GdkWindow + * @icon_window: a #GdkWindow to use for the icon, or %NULL to unset + * @pixmap: a #GdkPixmap to use as the icon, or %NULL to unset + * @mask: a 1-bit pixmap (#GdkBitmap) to use as mask for @pixmap, or %NULL to have none + * + * Sets the icon of @window as a pixmap or window. If using GTK+, investigate + * gtk_window_set_default_icon_list() first, and then gtk_window_set_icon_list() + * and gtk_window_set_icon(). If those don't meet your needs, look at + * gdk_window_set_icon_list(). Only if all those are too high-level do you + * want to fall back to gdk_window_set_icon(). + * + **/ void gdk_window_set_icon (GdkWindow *window, GdkWindow *icon_window, @@ -2498,6 +2882,17 @@ gdk_window_icon_name_set (GdkWindow *window) g_quark_from_static_string ("gdk-icon-name-set"))); } +/** + * gdk_window_set_icon_name: + * @window: a #GdkWindow + * @name: name of window while iconified (minimized) + * + * Windows may have a name used while minimized, distinct from the + * name they display in their titlebar. Most of the time this is a bad + * idea from a user interface standpoint. But you can set such a name + * with this function, if you like. + * + **/ void gdk_window_set_icon_name (GdkWindow *window, const gchar *name) @@ -2520,6 +2915,15 @@ gdk_window_set_icon_name (GdkWindow *window, set_text_property (window, gdk_atom_intern ("WM_ICON_NAME", FALSE), name); } +/** + * gdk_window_iconify: + * @window: a #GdkWindow + * + * Asks to iconify (minimize) @window. The window manager may choose + * to ignore the request, but normally will honor it. Using + * gtk_window_iconify() is preferred, if you have a #GtkWindow widget. + * + **/ void gdk_window_iconify (GdkWindow *window) { @@ -2550,6 +2954,17 @@ gdk_window_iconify (GdkWindow *window) } } +/** + * gdk_window_deiconify: + * @window: a #GdkWindow + * + * Attempt to deiconify (unminimize) @window. On X11 the window manager may + * choose to ignore the request to deiconify. When using GTK+, + * use gtk_window_deiconify() instead of the #GdkWindow variant. Or better yet, + * you probably want to use gtk_window_present(), which raises the window, focuses it, + * unminimizes it, and puts it on the current desktop. + * + **/ void gdk_window_deiconify (GdkWindow *window) { @@ -2579,6 +2994,21 @@ gdk_window_deiconify (GdkWindow *window) } } +/** + * gdk_window_stick: + * @window: a toplevel #GdkWindow + * + * "Pins" a window such that it's on all workspaces and does not scroll + * with viewports, for window managers that have scrollable viewports. + * (When using #GtkWindow, gtk_window_stick() may be more useful.) + * + * On the X11 platform, this function depends on window manager + * support, so may have no effect with many window managers. However, + * GDK will do the best it can to convince the window manager to stick + * the window. For window managers that don't support this operation, + * there's nothing you can do to force it to happen. + * + **/ void gdk_window_stick (GdkWindow *window) { @@ -2624,6 +3054,14 @@ gdk_window_stick (GdkWindow *window) } } +/** + * gdk_window_unstick: + * @window: a toplevel #GdkWindow + * + * Reverse operation for gdk_window_stick(); see gdk_window_stick(), + * and gtk_window_unstick(). + * + **/ void gdk_window_unstick (GdkWindow *window) { @@ -2684,6 +3122,19 @@ gdk_window_unstick (GdkWindow *window) } } +/** + * gdk_window_maximize: + * @window: a #GdkWindow + * + * Asks the window manager to maximize @window, if the window manager supports + * this operation. Not all window managers support this, and some deliberately + * ignore it or don't have a concept of "maximized"; so you can't rely on the + * maximization actually happening. But it will happen with most standard + * window managers, and GDK makes a best effort to get it to happen. + * + * If the window was already maximized, then this function does nothing. + * + **/ void gdk_window_maximize (GdkWindow *window) { @@ -2702,6 +3153,19 @@ gdk_window_maximize (GdkWindow *window) GDK_WINDOW_STATE_MAXIMIZED); } +/** + * gdk_window_unmaximize: + * @window: a #GdkWindow + * + * Asks the window manager to unmaximize @window, if the window manager supports + * this operation. Not all window managers support this, and some deliberately + * ignore it or don't have a concept of "maximized"; so you can't rely on the + * unmaximization actually happening. But it will happen with most standard + * window managers, and GDK makes a best effort to get it to happen. + * + * If the window wasn't maximized, then this function does nothing. + * + **/ void gdk_window_unmaximize (GdkWindow *window) { @@ -2720,6 +3184,25 @@ gdk_window_unmaximize (GdkWindow *window) 0); } +/** + * gdk_window_set_group: + * @window: a #GdkWindow + * @leader: group leader window + * + * Sets the group leader window for @window. By default, + * GDK sets the group leader for all toplevel windows + * to a global window implicitly created by GDK. With this function + * you can override this default. + * + * The group leader window allows the window manager to distinguish + * all windows that belong to a single application. It may for example + * allow users to minimize/unminimize all windows belonging to an + * application at once. You should only set a non-default group window + * if your application pretends to be multiple applications. + * The group leader window may not be changed after a window has been + * mapped (with gdk_window_show() for example). + * + **/ void gdk_window_set_group (GdkWindow *window, GdkWindow *leader) @@ -2822,6 +3305,27 @@ gdk_window_set_mwm_hints (GdkWindow *window, XFree (hints); } +/** + * gdk_window_set_decorations: + * @window: a #GdkWindow + * @decorations: decoration hint mask + * + * "Decorations" are the features the window manager adds to a toplevel #GdkWindow. + * This function sets the traditional Motif window manager hints that tell the + * window manager which decorations you would like your window to have. + * Usually you should use gtk_window_set_decorated() on a #GtkWindow instead of + * using the GDK function directly. + * + * The @decorations argument is the logical OR of the fields in + * the #GdkWMDecoration enumeration. If #GDK_DECOR_ALL is included in the + * mask, the other bits indicate which decorations should be turned off. + * If #GDK_DECOR_ALL is not included, then the other bits indicate + * which decorations should be turned on. + * + * Most window managers honor a decorations hint of 0 to disable all decorations, + * but very few honor all possible combinations of bits. + * + **/ void gdk_window_set_decorations (GdkWindow *window, GdkWMDecoration decorations) @@ -2868,6 +3372,24 @@ gdk_window_get_decorations(GdkWindow *window, return result; } +/** + * gdk_window_set_functions: + * @window: a #GdkWindow + * @functions: bitmask of operations to allow on @window + * + * This function isn't really good for much. It sets the traditional + * Motif window manager hint for which operations the window manager + * should allow on a toplevel window. However, few window managers do + * anything reliable or interesting with this hint. Many ignore it + * entirely. + * + * The @functions argument is the logical OR of values from the + * #GdkWMFunction enumeration. If the bitmask includes #GDK_FUNC_ALL, + * then the other bits indicate which functions to disable; if + * it doesn't include #GDK_FUNC_ALL, it indicates which functions to + * enable. + * + **/ void gdk_window_set_functions (GdkWindow *window, GdkWMFunction functions) @@ -3199,6 +3721,15 @@ gdk_propagate_shapes (Display *disp, #endif /* HAVE_SHAPE_EXT */ +/** + * gdk_window_set_child_shapes: + * @window: a #GdkWindow + * + * Sets the shape mask of @window to the union of shape masks + * for all children of @window, ignoring the shape mask of @window + * itself. Contrast with gdk_window_merge_child_shapes() which includes + * the shape mask of @window in the masks to be merged. + **/ void gdk_window_set_child_shapes (GdkWindow *window) { @@ -3213,6 +3744,20 @@ gdk_window_set_child_shapes (GdkWindow *window) #endif } +/** + * gdk_window_merge_child_shapes: + * @window: a #GdkWindow + * + * Merges the shape masks for any child windows into the + * shape mask for @window. i.e. the union of all masks + * for @window and its children will become the new mask + * for @window. See gdk_window_shape_combine_mask(). + * + * This function is distinct from gdk_window_set_child_shapes() + * because it includes @window's shape mask in the set of shapes to + * be merged. + * + **/ void gdk_window_merge_child_shapes (GdkWindow *window) { @@ -3318,18 +3863,18 @@ gdk_window_set_static_win_gravity (GdkWindow *window, gboolean on) CWWinGravity, &xattributes); } -/************************************************************* +/** * gdk_window_set_static_gravities: - * Set the bit gravity of the given window to static, - * and flag it so all children get static subwindow - * gravity. - * arguments: - * window: window for which to set static gravity - * use_static: Whether to turn static gravity on or off. - * results: - * Does the XServer support static gravity? - *************************************************************/ - + * @window: a #GdkWindow + * @use_static: %TRUE to turn on static gravity + * + * Set the bit gravity of the given window to static, and flag it so + * all children get static subwindow gravity. This is used if you are + * implementing scary features that involve deep knowledge of the + * windowing system. Don't worry about it unless you have to. + * + * Return value: %TRUE if the server supports static gravity + **/ gboolean gdk_window_set_static_gravities (GdkWindow *window, gboolean use_static) @@ -3870,6 +4415,22 @@ emulate_move_drag (GdkWindow *window, create_moveresize_window (timestamp); } +/** + * gdk_window_begin_resize_drag: + * @window: a #GdkWindow + * @button: the button being used to drag + * @root_x: root window X coordinate of mouse click that began the drag + * @root_y: root window Y coordinate of mouse click that began the drag + * @timestamp: timestamp of mouse click that began the drag (use gdk_event_get_time()) + * + * Begins a window resize operation (for a toplevel window). + * You might use this function to implement a "window resize grip," for + * example; in fact #GtkStatusbar uses it. The function works best + * with window managers that support the Extended Window Manager Hints spec + * (see http://www.freedesktop.org), but has a fallback implementation + * for other window managers. + * + **/ void gdk_window_begin_resize_drag (GdkWindow *window, GdkWindowEdge edge, @@ -3890,6 +4451,22 @@ gdk_window_begin_resize_drag (GdkWindow *window, emulate_resize_drag (window, edge, button, root_x, root_y, timestamp); } +/** + * gdk_window_begin_move_drag: + * @window: a #GdkWindow + * @button: the button being used to drag + * @root_x: root window X coordinate of mouse click that began the drag + * @root_y: root window Y coordinate of mouse click that began the drag + * @timestamp: timestamp of mouse click that began the drag + * + * Begins a window move operation (for a toplevel window). You might + * use this function to implement a "window move grip," for + * example. The function works best with window managers that support + * the Extended Window Manager Hints spec (see + * http://www.freedesktop.org), but has a fallback implementation for + * other window managers. + * + **/ void gdk_window_begin_move_drag (GdkWindow *window, gint button, diff --git a/gdk/x11/gdkx.h b/gdk/x11/gdkx.h index 2f61dfdc3..1e69a50b3 100644 --- a/gdk/x11/gdkx.h +++ b/gdk/x11/gdkx.h @@ -99,10 +99,6 @@ GdkVisual* gdkx_visual_get (VisualID xvisualid); /* XXX: Do not use this function until it is fixed. An X Colormap * is useless unless we also have the visual. */ GdkColormap* gdkx_colormap_get (Colormap xcolormap); -/* Utility function in gdk.c - not sure where it belongs, but it's - needed in more than one place, so make it public */ -Window gdk_get_client_window (Display *dpy, - Window win); /* Functions to create pixmaps and windows from their X equivalents */ GdkPixmap *gdk_pixmap_foreign_new (GdkNativeWindow anid); |