* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
/**
* @Short_Description: An interface for scrollable widgets
* @Title: GtkScrollable
*
- * #GtkScrollable is interface that is implemented by widgets with native
+ * #GtkScrollable is an interface that is implemented by widgets with native
* scrolling ability.
*
- * To implement this interface, all one needs to do is to override
+ * To implement this interface you should override the
* #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties.
*
* <refsect2>
* <title>Creating a scrollable widget</title>
* <para>
- * There are some common things all scrollable widgets will need to do.
+ * All scrollable widgets should do the following.
*
* <orderedlist>
* <listitem>
* <para>
- * When parent sets adjustments, widget needs to populate adjustment's
+ * When a parent widget sets the scrollable child widget's adjustments, the widget should populate the adjustments'
* #GtkAdjustment:lower, #GtkAdjustment:upper,
* #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and
- * #GtkAdjustment:page-size properties and connect to
+ * #GtkAdjustment:page-size properties and connect to the
* #GtkAdjustment::value-changed signal.
* </para>
* </listitem>
* <listitem>
* <para>
- * When parent allocates space to child, scrollable widget needs to update
- * properties listed under 1 with new values.
+ * Because its preferred size is the size for a fully expanded widget,
+ * the scrollable widget must be able to cope with underallocations.
+ * This means that it must accept any value passed to its
+ * #GtkWidgetClass.size_allocate() function.
* </para>
* </listitem>
* <listitem>
* <para>
- * When any of the adjustments emits #GtkAdjustment::value-changed signal,
- * scrollable widget needs to scroll it's contents.
+ * When the parent allocates space to the scrollable child widget, the widget should update
+ * the adjustments' properties with new values.
+ * </para>
+ * </listitem>
+ * <listitem>
+ * <para>
+ * When any of the adjustments emits the #GtkAdjustment::value-changed signal,
+ * the scrollable widget should scroll its contents.
* </para>
* </listitem>
* </orderedlist>
#include "config.h"
#include "gtkscrollable.h"
+
+#include "gtkadjustment.h"
#include "gtkprivate.h"
+#include "gtktypebuiltins.h"
#include "gtkintl.h"
G_DEFINE_INTERFACE (GtkScrollable, gtk_scrollable, G_TYPE_OBJECT)
/**
* GtkScrollable:hadjustment:
*
- * Horizontal #GtkAdjustment of scrollable widget. This adjustment is
- * shared between scrollable widget and it's parent.
+ * Horizontal #GtkAdjustment of the scrollable widget. This adjustment is
+ * shared between the scrollable widget and its parent.
*
* Since: 3.0
*/
pspec = g_param_spec_object ("hadjustment",
P_("Horizontal adjustment"),
P_("Horizontal adjustment that is shared "
- "between scrollable widget and it's "
+ "between the scrollable widget and its "
"controller"),
GTK_TYPE_ADJUSTMENT,
GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
/**
* GtkScrollable:vadjustment:
*
- * Verical #GtkAdjustment of scrollable widget. This adjustment is shared
- * between scrollable widget and it's parent.
+ * Verical #GtkAdjustment of the scrollable widget. This adjustment is shared
+ * between the scrollable widget and its parent.
*
* Since: 3.0
*/
pspec = g_param_spec_object ("vadjustment",
P_("Vertical adjustment"),
P_("Vertical adjustment that is shared "
- "between scrollable widget and it's "
+ "between the scrollable widget and its "
"controller"),
GTK_TYPE_ADJUSTMENT,
GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
g_object_interface_install_property (iface, pspec);
-
/**
- * GtkScrollable:min-display-width:
+ * GtkScrollable:hscroll-policy:
*
- * Minimum width to display in the parent scrolled window, this
- * can be greater or less than the scrollable widget's real minimum
- * width.
+ * Determines whether horizontal scrolling should start once the scrollable
+ * widget is allocated less than its minimum width or less than its natural width.
*
* Since: 3.0
*/
- pspec = g_param_spec_int ("min-display-width",
- P_("Minimum Display Width"),
- P_("Minimum width to display in the parent scrolled window"),
- -1, G_MAXINT, -1,
- GTK_PARAM_READWRITE);
+ pspec = g_param_spec_enum ("hscroll-policy",
+ P_("Horizontal Scrollable Policy"),
+ P_("How the size of the content should be determined"),
+ GTK_TYPE_SCROLLABLE_POLICY,
+ GTK_SCROLL_MINIMUM,
+ GTK_PARAM_READWRITE);
g_object_interface_install_property (iface, pspec);
-
/**
- * GtkScrollable:min-display-height:
+ * GtkScrollable:vscroll-policy:
*
- * Minimum height to display in the parent scrolled window, this
- * can be greater or less than the scrollable widget's real minimum
- * height.
+ * Determines whether vertical scrolling should start once the scrollable
+ * widget is allocated less than its minimum height or less than its natural height.
*
* Since: 3.0
*/
- pspec = g_param_spec_int ("min-display-height",
- P_("Minimum Display Height"),
- P_("Minimum height to display in the parent scrolled window"),
- -1, G_MAXINT, -1,
- GTK_PARAM_READWRITE);
+ pspec = g_param_spec_enum ("vscroll-policy",
+ P_("Vertical Scrollable Policy"),
+ P_("How the size of the content should be determined"),
+ GTK_TYPE_SCROLLABLE_POLICY,
+ GTK_SCROLL_MINIMUM,
+ GTK_PARAM_READWRITE);
g_object_interface_install_property (iface, pspec);
-
}
/**
* gtk_scrollable_get_hadjustment:
* @scrollable: a #GtkScrollable
*
- * Retrieves the #GtkAdjustment, used for horizontal scrolling.
+ * Retrieves the #GtkAdjustment used for horizontal scrolling.
*
* Return value: (transfer none): horizontal #GtkAdjustment.
*
* gtk_scrollable_get_vadjustment:
* @scrollable: a #GtkScrollable
*
- * Retrieves the #GtkAdjustment, used for vertical scrolling.
+ * Retrieves the #GtkAdjustment used for vertical scrolling.
*
* Return value: (transfer none): vertical #GtkAdjustment.
*
/**
- * gtk_scrollable_get_min_display_width:
+ * gtk_scrollable_get_hscroll_policy:
* @scrollable: a #GtkScrollable
*
- * Retrieves the minimum width of content to display in the
- * parent scrolled window.
+ * Gets the horizontal #GtkScrollablePolicy.
*
- * Return value: The minimum display width.
+ * Return value: The horizontal #GtkScrollablePolicy.
*
* Since: 3.0
**/
-gint
-gtk_scrollable_get_min_display_width (GtkScrollable *scrollable)
+GtkScrollablePolicy
+gtk_scrollable_get_hscroll_policy (GtkScrollable *scrollable)
{
- gint width;
+ GtkScrollablePolicy policy;
- g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
+ g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
- g_object_get (scrollable, "min-display-width", &width, NULL);
+ g_object_get (scrollable, "hscroll-policy", &policy, NULL);
- return width;
+ return policy;
}
/**
- * gtk_scrollable_set_min_display_width:
+ * gtk_scrollable_set_hscroll_policy:
* @scrollable: a #GtkScrollable
- * @width: the minimum width of scrollable content to display
+ * @policy: the horizontal #GtkScrollablePolicy
*
- * Sets the minimum width of content to display in the parent scrolled window,
- * this can be greater or less than the scrollable widget's real minimum
- * width.
+ * Sets the #GtkScrollablePolicy to determine whether
+ * horizontal scrolling should start below the minimum width or
+ * below the natural width.
*
* Since: 3.0
**/
void
-gtk_scrollable_set_min_display_width (GtkScrollable *scrollable,
- gint width)
+gtk_scrollable_set_hscroll_policy (GtkScrollable *scrollable,
+ GtkScrollablePolicy policy)
{
g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
- g_object_set (scrollable, "min-display-width", width, NULL);
+ g_object_set (scrollable, "hscroll-policy", policy, NULL);
}
/**
- * gtk_scrollable_get_min_display_height:
+ * gtk_scrollable_get_vscroll_policy:
* @scrollable: a #GtkScrollable
*
- * Retrieves the minimum height of content to display in the
- * parent scrolled window.
+ * Gets the vertical #GtkScrollablePolicy.
*
- * Return value: The minimum display height.
+ * Return value: The vertical #GtkScrollablePolicy.
*
* Since: 3.0
**/
-gint
-gtk_scrollable_get_min_display_height (GtkScrollable *scrollable)
+GtkScrollablePolicy
+gtk_scrollable_get_vscroll_policy (GtkScrollable *scrollable)
{
- gint height;
+ GtkScrollablePolicy policy;
- g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
+ g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
- g_object_get (scrollable, "min-display-height", &height, NULL);
+ g_object_get (scrollable, "vscroll-policy", &policy, NULL);
- return height;
+ return policy;
}
/**
- * gtk_scrollable_set_min_display_height:
+ * gtk_scrollable_set_vscroll_policy:
* @scrollable: a #GtkScrollable
- * @height: the minimum height of scrollable content to display
+ * @policy: the vertical #GtkScrollablePolicy
*
- * Sets the minimum height of content to display in the parent scrolled window,
- * this can be greater or less than the scrollable widget's real minimum
- * height.
+ * Sets the #GtkScrollablePolicy to determine whether
+ * vertical scrolling should start below the minimum height or
+ * below the natural height.
*
* Since: 3.0
**/
void
-gtk_scrollable_set_min_display_height (GtkScrollable *scrollable,
- gint height)
+gtk_scrollable_set_vscroll_policy (GtkScrollable *scrollable,
+ GtkScrollablePolicy policy)
{
g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
- g_object_set (scrollable, "min-display-height", height, NULL);
+ g_object_set (scrollable, "vscroll-policy", policy, NULL);
}
projects / ~andy / gtk / blobdiff