From ee58c6c37d31ee8fc4c233751024b3992d42bd5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20Jard=C3=B3n?= Date: Mon, 11 Oct 2010 02:01:14 +0200 Subject: [PATCH] docs: Move documentation to inline comments: GtkScrolledWindow --- docs/reference/gtk/tmpl/.gitignore | 1 + .../reference/gtk/tmpl/gtkscrolledwindow.sgml | 282 ------------------ gtk/gtkscrolledwindow.c | 54 ++++ 3 files changed, 55 insertions(+), 282 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkscrolledwindow.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 24fa3ad14d..f08a09ebef 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -34,6 +34,7 @@ gtkrecentchooserwidget.sgml gtkrecentmanager.sgml gtkscale.sgml gtkscalebutton.sgml +gtkscrolledwindow.sgml gtkseparator.sgml gtkseparatormenuitem.sgml gtkseparatortoolitem.sgml diff --git a/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml b/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml deleted file mode 100644 index a35292772b..0000000000 --- a/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml +++ /dev/null @@ -1,282 +0,0 @@ - -GtkScrolledWindow - - -Adds scrollbars to its child widget - - - -#GtkScrolledWindow is a #GtkBin subclass: it's a container -the accepts a single child widget. #GtkScrolledWindow adds scrollbars -to the child widget and optionally draws a beveled frame around the -child widget. - - - -The scrolled window can work in two ways. Some widgets have native -scrolling support; these widgets have "slots" for #GtkAdjustment -objects. -The scrolled window installs #GtkAdjustment objects in -the child window's slots using the set_scroll_adjustments_signal, -found in #GtkWidgetClass. (Conceptually, these widgets implement a -"Scrollable" interface; because GTK+ 1.2 lacked interface support in -the object system, this interface is hackily implemented as a signal -in #GtkWidgetClass. The GTK+ 2.0 object system would allow a clean -implementation, but it wasn't worth breaking the -API.) -Widgets with native scroll support include #GtkTreeView, #GtkTextView, -and #GtkLayout. - - - -For widgets that lack native scrolling support, the #GtkViewport -widget acts as an adaptor class, implementing scrollability for child -widgets that lack their own scrolling capabilities. Use #GtkViewport -to scroll child widgets such as #GtkTable, #GtkBox, and so on. - - - -If a widget has native scrolling abilities, it can be added to the -#GtkScrolledWindow with gtk_container_add(). If a widget does not, you -must first add the widget to a #GtkViewport, then add the #GtkViewport -to the scrolled window. The convenience function -gtk_scrolled_window_add_with_viewport() does exactly this, so you can -ignore the presence of the viewport. - - - -The position of the scrollbars is controlled by the scroll -adjustments. See #GtkAdjustment for the fields in an adjustment - for -#GtkScrollbar, used by #GtkScrolledWindow, the "value" field -represents the position of the scrollbar, which must be between the -"lower" field and "upper - page_size." The "page_size" field -represents the size of the visible scrollable area. The -"step_increment" and "page_increment" fields are used when the user -asks to step down (using the small stepper arrows) or page down (using -for example the PageDown key). - - - -If a #GtkScrolledWindow doesn't behave quite as you would like, or -doesn't have exactly the right layout, it's very possible to set up -your own scrolling with #GtkScrollbar and for example a #GtkTable. - - - - -#GtkViewport, #GtkAdjustment, #GtkWidgetClass - - - - - - - - - - -There are no public fields in the #GtkScrolledWindow struct; it should -only be accessed using the functions below. - - - - - - - - -@scrolledwindow: -@arg1: - - - - - - -@scrolledwindow: -@arg1: -@arg2: -@Returns: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@hadjustment: -@vadjustment: -@Returns: - - - - - - - -@scrolled_window: -@Returns: - - - - - - - -@scrolled_window: -@Returns: - - - - - - - -@scrolled_window: -@Returns: - - - - - - - -@scrolled_window: -@Returns: - - - - - - - -@scrolled_window: -@hscrollbar_policy: -@vscrollbar_policy: - - - - - - - -@scrolled_window: -@child: - - - - - - - -@scrolled_window: -@window_placement: - - - - - - - -@scrolled_window: - - - - - - - -@scrolled_window: -@type: - - - - - - - -@scrolled_window: -@hadjustment: - - - - - - - -@scrolled_window: -@vadjustment: - - - - - - - -@scrolled_window: -@Returns: - - - - - - - -@scrolled_window: -@hscrollbar_policy: -@vscrollbar_policy: - - - - - - - -@scrolled_window: -@Returns: - - diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c index 68254280e1..f61425839d 100644 --- a/gtk/gtkscrolledwindow.c +++ b/gtk/gtkscrolledwindow.c @@ -35,6 +35,60 @@ #include "gtkprivate.h" #include "gtkintl.h" + +/** + * SECTION:gtkscrolledwindow + * @Short_description: Adds scrollbars to its child widget + * @Title: GtkScrolledWindow + * @See_also: #GtkViewport, #GtkAdjustment, #GtkWidgetClass + * + * #GtkScrolledWindow is a #GtkBin subclass: it's a container + * the accepts a single child widget. #GtkScrolledWindow adds scrollbars + * to the child widget and optionally draws a beveled frame around the + * child widget. + * + * The scrolled window can work in two ways. Some widgets have native + * scrolling support; these widgets have "slots" for #GtkAdjustment + * objects. + * The scrolled window installs #GtkAdjustment objects in + * the child window's slots using the set_scroll_adjustments_signal, + * found in #GtkWidgetClass. (Conceptually, these widgets implement a + * "Scrollable" interface; because GTK+ 1.2 lacked interface support in + * the object system, this interface is hackily implemented as a signal + * in #GtkWidgetClass. The GTK+ 2.0 object system would allow a clean + * implementation, but it wasn't worth breaking the + * API.) + * Widgets with native scroll support include #GtkTreeView, #GtkTextView, + * and #GtkLayout. + * + * For widgets that lack native scrolling support, the #GtkViewport + * widget acts as an adaptor class, implementing scrollability for child + * widgets that lack their own scrolling capabilities. Use #GtkViewport + * to scroll child widgets such as #GtkTable, #GtkBox, and so on. + * + * If a widget has native scrolling abilities, it can be added to the + * #GtkScrolledWindow with gtk_container_add(). If a widget does not, you + * must first add the widget to a #GtkViewport, then add the #GtkViewport + * to the scrolled window. The convenience function + * gtk_scrolled_window_add_with_viewport() does exactly this, so you can + * ignore the presence of the viewport. + * + * The position of the scrollbars is controlled by the scroll + * adjustments. See #GtkAdjustment for the fields in an adjustment - for + * #GtkScrollbar, used by #GtkScrolledWindow, the "value" field + * represents the position of the scrollbar, which must be between the + * "lower" field and "upper - page_size." The "page_size" field + * represents the size of the visible scrollable area. The + * "step_increment" and "page_increment" fields are used when the user + * asks to step down (using the small stepper arrows) or page down (using + * for example the PageDown key). + * + * If a #GtkScrolledWindow doesn't behave quite as you would like, or + * doesn't have exactly the right layout, it's very possible to set up + * your own scrolling with #GtkScrollbar and for example a #GtkTable. + */ + + /* scrolled window policy and size requisition handling: * * gtk size requisition works as follows: