docs/sizing-test.txt

   1 This is a list of things to check when testing window size/pos functions.
   2 ===
   3
   4 gtk_widget_set_size_request():
   5  - causes the widget to request the given size
   6  - for toplevel windows, changes the default-requested size if
   7    no default size is set and gtk_window_resize() has not been called
   8  - passing -1 for either width or height reverts to "natural" request
   9    in that dimension
  10  - passing 0 is allowed, and results in requisition of 1x1
  11    (0x0 is a permitted requisition, but equivalent to 1x1,
  12    we use 1x1 for implementation convenience)
  13  - causes notifies on width_request, height_request properties
  14
  15 gtk_window_resize():
  16  - causes a configure request in all cases if the window is mapped,
  17    unless the new size is the same as the old size
  18  - overrides the default size on map if the window is unmapped
  19  - allows size of 0, equivalent to 1
  20  - clamped to geometry hints
  21
  22 gtk_window_set_default_size():
  23  - has no effect after the window has been mapped the first time,
  24    unless the window has been unrealized in which case it should
  25    have an effect
  26  - allows size of 0, equivalent to 1
  27  - allows size of -1 to unset the default size
  28  - clamped to geometry hints
  29  - gtk_window_resize() overrides it
  30  - causes notifies on default_width, default_height properties
  31
  32 gtk_window_get_default_size():
  33  - returns the values last passed to set_default_size(), including
  34    -1. If set_default_size() has not been called, returns -1.
  35
  36 gtk_window_move():
  37  - always causes a configure request if the window is mapped,
  38    unless the last configure request we sent was for the same
  39    position being moved to
  40  - position may be negative to move windows offscreen
  41  - if GTK_WIN_POS_CENTER_ALWAYS (or other future position
  42    constraints we may add) is in effect, the move
  43    request is clamped to obey the constraints. thus
  44    calling gtk_window_move() on a CENTER_ALWAYS window
  45    may trigger the window to bounce back to center if it
  46    wasn't there
  47  - overrides all GTK_WIN_POS_ except CENTER_ALWAYS
  48
  49 gtk_window_get_size():
  50  - obtains the client-side known size of widget->window,
  51    as last received from a configure event
  52  - prior to mapping, returns the default size we will request
  53  - between realization and mapping, computes default size
  54    rather than looking at widget->window up-to-date size,
  55    so the size will be correct after force-realizing a window
  56
  57 gtk_window_get_position():
  58  - obtains the point to be passed to gtk_window_move() in order
  59    to keep the window in its current position
  60  - round-trips to the server to get the position; this is suboptimal
  61    from both a race condition and speed standpoint but required to get
  62    window frame size
  63  - if the window is unmapped, returns the default position we will
  64    request
  65
  66 gtk_window_set_position():
  67  - not the inverse of get_position(), sadly
  68  - modifies the default positioning of the window
  69  - if set to CENTER_ALWAYS and the window is mapped, results in a
  70    configure request moving the window to the center, unless the
  71    window was already centered
  72  - ignored if gtk_window_move() called, with the exception
  73    of CENTER_ALWAYS
  74
  75 gtk_window_parse_geometry():
  76  - parses a standard X geometry string
  77  - toggles on one or both of GDK_HINT_USER_SIZE, GDK_HINT_USER_POS
  78  - "xprop" shows user size/position are set on the window
  79  - calls gtk_window_set_default_size() to set the window size
  80  - calls gtk_window_move() to set the window position
  81  - calls gtk_window_set_gravity() to set the window gravity
  82
  83 gtk_window_reshow_with_initial_size():
  84  - for use by GUI builders; unrealizes and re-shows the window,
  85    using default size (and also position, but position
  86    is reset on any hide anyway)
  87  - window should be positioned and sized as it was on initial map,
  88    barring odd window managers
  89
  90 gtk_window_set_geometry_hints():
  91  - if a hint is set with this function, we do not override it
  92    in other parts of the code
  93
  94 General behavior
  95 ===
  96
  97  - no infinite loops or nasty fighting-the-user flicker during
  98    operations such as moving/resizing a window
  99
 100 Properties
 101 ===
 102
 103 GtkWindow::default_width, GtkWindow::default_height:
 104  - default_width is -1 if unset, or >= 0 if
 105    a default width is set
 106  - default_height is -1 if unset, or >= 0 if
 107    a default height is set
 108
 109 GtkWindow::allow_grow, GtkWindow::resizable:
 110  - equivalent properties; changing one notifies on the other
 111  - if FALSE, we set the min size to the max size in the geometry
 112    hints.
 113  - If the app programmer has called gtk_window_set_geometry_hints()
 114    however and set min or max size, we don't replace the hint they
 115    set.
 116
 117 GtkWidget::width_request, GtkWidget::height_request:
 118  - if -1, default requisition of widget is used
 119  - otherwise, override default requisition
 120
 121