1 files changed, 121 insertions, 0 deletions
diff --git a/docs/sizing-test.txt b/docs/sizing-test.txt
new file mode 100644
index 000000000..6954612d4
--- /dev/null
+++ b/docs/sizing-test.txt
@@ -0,0 +1,121 @@
+This is a list of things to check when testing window size/pos functions.
+===
+
+gtk_widget_set_size_request():
+ - causes the widget to request the given size
+ - for toplevel windows, changes the default-requested size if 
+   no default size is set and gtk_window_resize() has not been called
+ - passing -1 for either width or height reverts to "natural" request
+   in that dimension
+ - passing 0 is allowed, and results in requisition of 1x1 
+   (0x0 is a permitted requisition, but equivalent to 1x1, 
+   we use 1x1 for implementation convenience)
+ - causes notifies on width_request, height_request properties
+
+gtk_window_resize():
+ - causes a configure request in all cases if the window is mapped, 
+   unless the new size is the same as the old size
+ - overrides the default size on map if the window is unmapped
+ - allows size of 0, equivalent to 1
+ - clamped to geometry hints
+
+gtk_window_set_default_size():
+ - has no effect after the window has been mapped the first time, 
+   unless the window has been unrealized in which case it should 
+   have an effect
+ - allows size of 0, equivalent to 1
+ - allows size of -1 to unset the default size
+ - clamped to geometry hints
+ - gtk_window_resize() overrides it
+ - causes notifies on default_width, default_height properties
+
+gtk_window_get_default_size():
+ - returns the values last passed to set_default_size(), including 
+   -1. If set_default_size() has not been called, returns -1.
+
+gtk_window_move():
+ - always causes a configure request if the window is mapped, 
+   unless the last configure request we sent was for the same
+   position being moved to
+ - position may be negative to move windows offscreen
+ - if GTK_WIN_POS_CENTER_ALWAYS (or other future position 
+   constraints we may add) is in effect, the move
+   request is clamped to obey the constraints. thus
+   calling gtk_window_move() on a CENTER_ALWAYS window 
+   may trigger the window to bounce back to center if it 
+   wasn't there
+ - overrides all GTK_WIN_POS_ except CENTER_ALWAYS
+
+gtk_window_get_size():
+ - obtains the client-side known size of widget->window, 
+   as last received from a configure event
+ - prior to mapping, returns the default size we will request
+ - between realization and mapping, computes default size 
+   rather than looking at widget->window up-to-date size, 
+   so the size will be correct after force-realizing a window
+
+gtk_window_get_position():
+ - obtains the point to be passed to gtk_window_move() in order
+   to keep the window in its current position
+ - round-trips to the server to get the position; this is suboptimal
+   from both a race condition and speed standpoint but required to get
+   window frame size
+ - if the window is unmapped, returns the default position we will 
+   request
+
+gtk_window_set_position():
+ - not the inverse of get_position(), sadly
+ - modifies the default positioning of the window
+ - if set to CENTER_ALWAYS and the window is mapped, results in a
+   configure request moving the window to the center, unless the 
+   window was already centered
+ - ignored if gtk_window_move() called, with the exception 
+   of CENTER_ALWAYS
+
+gtk_window_parse_geometry():
+ - parses a standard X geometry string
+ - toggles on one or both of GDK_HINT_USER_SIZE, GDK_HINT_USER_POS
+ - "xprop" shows user size/position are set on the window
+ - calls gtk_window_set_default_size() to set the window size
+ - calls gtk_window_move() to set the window position
+ - calls gtk_window_set_gravity() to set the window gravity
+
+gtk_window_reshow_with_initial_size():
+ - for use by GUI builders; unrealizes and re-shows the window, 
+   using default size (and also position, but position 
+   is reset on any hide anyway)
+ - window should be positioned and sized as it was on initial map,
+   barring odd window managers
+
+gtk_window_set_geometry_hints():
+ - if a hint is set with this function, we do not override it
+   in other parts of the code
+
+General behavior
+===
+
+ - no infinite loops or nasty fighting-the-user flicker during 
+   operations such as moving/resizing a window
+
+Properties
+===
+
+GtkWindow::default_width, GtkWindow::default_height:
+ - default_width is -1 if unset, or >= 0 if 
+   a default width is set
+ - default_height is -1 if unset, or >= 0 if
+   a default height is set
+
+GtkWindow::allow_grow, GtkWindow::resizable:
+ - equivalent properties; changing one notifies on the other
+ - if FALSE, we set the min size to the max size in the geometry 
+   hints. 
+ - If the app programmer has called gtk_window_set_geometry_hints()
+   however and set min or max size, we don't replace the hint they
+   set.
+
+GtkWidget::width_request, GtkWidget::height_request:
+ - if -1, default requisition of widget is used
+ - otherwise, override default requisition
+
+