forked from AuroraMiddleware/gtk
docs: Update gtk_window_get_size()
The main corpus of the documentation for gtk_window_get_size() is still full of X11-isms, so we should port it to something that is more backend-agnostic. Additionally, having some examples would be nice for application authors looking at a way to appropriately use this function.
This commit is contained in:
Emmanuele Bassi
parent
b40469638b
commit
08e443e0db
121
gtk/gtkwindow.c
121
gtk/gtkwindow.c
@ -5400,63 +5400,82 @@ gtk_window_resize_to_geometry (GtkWindow *window,
|
||||
/**
|
||||
* gtk_window_get_size:
|
||||
* @window: a #GtkWindow
|
||||
* @width: (out) (allow-none): return location for width, or %NULL
|
||||
* @height: (out) (allow-none): return location for height, or %NULL
|
||||
* @width: (out) (nullable): return location for width, or %NULL
|
||||
* @height: (out) (nullable): return location for height, or %NULL
|
||||
*
|
||||
* Obtains the current size of @window. If @window is not onscreen,
|
||||
* it returns the size GTK+ will suggest to the
|
||||
* [window manager][gtk-X11-arch]
|
||||
* for the initial window
|
||||
* size (but this is not reliably the same as the size the window
|
||||
* manager will actually select). The size obtained by
|
||||
* gtk_window_get_size() is the last size received in a
|
||||
* #GdkEventConfigure, that is, GTK+ uses its locally-stored size,
|
||||
* rather than querying the X server for the size. As a result, if you
|
||||
* call gtk_window_resize() then immediately call
|
||||
* gtk_window_get_size(), the size won’t have taken effect yet. After
|
||||
* the window manager processes the resize request, GTK+ receives
|
||||
* notification that the size has changed via a configure event, and
|
||||
* the size of the window gets updated.
|
||||
* Obtains the current size of @window.
|
||||
*
|
||||
* Note 1: Nearly any use of this function creates a race condition,
|
||||
* because the size of the window may change between the time that you
|
||||
* get the size and the time that you perform some action assuming
|
||||
* that size is the current size. To avoid race conditions, connect to
|
||||
* “configure-event” on the window and adjust your size-dependent
|
||||
* state to match the size delivered in the #GdkEventConfigure.
|
||||
* If @window is not visible on screen, this function return the size GTK+
|
||||
* will suggest to the [window manager][gtk-X11-arch] for the initial window
|
||||
* size (but this is not reliably the same as the size the window manager
|
||||
* will actually select). See: gtk_window_set_default_size().
|
||||
*
|
||||
* Note 2: The returned size does not include the
|
||||
* size of the window manager decorations (aka the window frame or
|
||||
* border). Those are not drawn by GTK+ and GTK+ has no reliable
|
||||
* method of determining their size.
|
||||
* Depending on the windowing system and the window manager constraints,
|
||||
* the size returned by this function may not match the size set using
|
||||
* gtk_window_resize(); additionally, since gtk_window_resize() may be
|
||||
* implemented as an asynchronous operation, GTK+ cannot guarantee in any
|
||||
* way that this code:
|
||||
*
|
||||
* Note 3: If you are getting a window size in order to position
|
||||
* the window onscreen, there may be a better way. The preferred
|
||||
* way is to simply set the window’s semantic type with
|
||||
* gtk_window_set_type_hint(), which allows the window manager to
|
||||
* e.g. center dialogs. Also, if you set the transient parent of
|
||||
* dialogs with gtk_window_set_transient_for() window managers
|
||||
* will often center the dialog over its parent window. It's
|
||||
* much preferred to let the window manager handle these
|
||||
* things rather than doing it yourself, because all apps will
|
||||
* behave consistently and according to user prefs if the window
|
||||
* manager handles it. Also, the window manager can take the size
|
||||
* of the window decorations/border into account, while your
|
||||
* application cannot.
|
||||
* |[<!-- language="C" -->
|
||||
* // width and height are set elsewhere
|
||||
* gtk_window_resize (window, width, height);
|
||||
*
|
||||
* Note 4: When using client side decorations, GTK+ will do its best to
|
||||
* adjust the returned values to match the logical size of the window
|
||||
* excluding the widgets added for client side decorations, but there
|
||||
* is no garantee that the result will be totally accurate because
|
||||
* these widgets depend on the theme and may not be realized or
|
||||
* visible at the time gtk_window_get_size() is invoked.
|
||||
* int new_width, new_height;
|
||||
* gtk_window_get_size (window, &new_width, &new_height);
|
||||
* ]|
|
||||
*
|
||||
* In any case, if you insist on application-specified window
|
||||
* positioning, there’s still a better way than
|
||||
* doing it yourself - gtk_window_set_position() will frequently
|
||||
* handle the details for you.
|
||||
*
|
||||
**/
|
||||
* will result in `new_width` and `new_height` matching `width` and
|
||||
* `height`, respectively.
|
||||
*
|
||||
* This function will return the logical size of the #GtkWindow,
|
||||
* excluding the widgets used in client side decorations; there is,
|
||||
* however, no guarantee that the result will be completely accurate
|
||||
* because client side decoration may include widgets that depend on
|
||||
* the user preferences and that may not be visibile at the time you
|
||||
* call this function.
|
||||
*
|
||||
* The dimensions returned by this function are suitable for being
|
||||
* stored across sessions; use gtk_window_set_default_size() to
|
||||
* restore them when before showing the window.
|
||||
*
|
||||
* To avoid potential race conditions, you should only call this
|
||||
* function in response to a size change notification, for instance
|
||||
* inside a handler for the #GtkWidget::size-allocate signal, or
|
||||
* inside a handler for the #GtkWidget::configure-event signal:
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* static void
|
||||
* on_size_allocate (GtkWidget *widget, GtkAllocation *allocation)
|
||||
* {
|
||||
* int new_width, new_height;
|
||||
*
|
||||
* gtk_window_get_size (GTK_WINDOW (widget), &new_width, &new_height);
|
||||
*
|
||||
* ...
|
||||
* }
|
||||
* ]|
|
||||
*
|
||||
* Note that, if you connect to the #GtkWidget::size-allocate signal,
|
||||
* you should not use the dimensions of the #GtkAllocation passed to
|
||||
* the signal handler, as the allocation may contain client side
|
||||
* decorations added by GTK+, depending on the windowing system in
|
||||
* use.
|
||||
*
|
||||
* If you are getting a window size in order to position the window
|
||||
* on the screen, you should, instead, simply set the window’s semantic
|
||||
* type with gtk_window_set_type_hint(), which allows the window manager
|
||||
* to e.g. center dialogs. Also, if you set the transient parent of
|
||||
* dialogs with gtk_window_set_transient_for() window managers will
|
||||
* often center the dialog over its parent window. It's much preferred
|
||||
* to let the window manager handle these cases rather than doing it
|
||||
* yourself, because all apps will behave consistently and according to
|
||||
* user or system preferences, if the window manager handles it. Also,
|
||||
* the window manager can take into account the size of the window
|
||||
* decorations and border that it may add, and of which GTK+ has no
|
||||
* knowledge. Additionally, positioning windows in global screen coordinates
|
||||
* may not be allowed by the windowing system. For more information,
|
||||
* see: gtk_window_set_position().
|
||||
*/
|
||||
void
|
||||
gtk_window_get_size (GtkWindow *window,
|
||||
gint *width,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user