libs/gtkmm2/gtk/src/box.hg

   1 /* $Id: box.hg,v 1.10 2006/01/28 18:49:13 jjongsma Exp $ */
   2
   3 /* Copyright (C) 1998-2002 The gtkmm Development Team
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the Free
  17  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  */
  19
  20 _DEFS(gtkmm,gtk)
  21 _PINCLUDE(gtkmm/private/container_p.h)
  22
  23 #include <gtkmm/container.h>
  24 #include <glibmm/helperlist.h>
  25 #include <gtk/gtkbox.h>  /* For _GtkBoxChild */
  26
  27
  28 namespace Gtk
  29 {
  30
  31 /** Packing options for adding child widgets to a Box with pack_start() and pack_end().
  32  * @ingroup gtkmmEnums
  33  */
  34 enum PackOptions
  35 {
  36   PACK_SHRINK, /**< Space is contracted to the child widget size. */
  37   PACK_EXPAND_PADDING, /**< Space is expanded, with extra space filled with padding. */
  38   PACK_EXPAND_WIDGET /**< Space is expanded, with extra space filled by increasing the child widget size. */
  39 };
  40
  41 class Box;
  42
  43 namespace Box_Helpers
  44 {
  45
  46 //This may not have any data or virtual functions. See below.
  47 class Child : protected _GtkBoxChild
  48 {
  49 private:
  50   Child& operator=(const Child&); //Not implemented.
  51   Child(const Child&); //Not implemented.
  52
  53 public:
  54   /// Provides access to the underlying C GObject.
  55   inline _GtkBoxChild* gobj() { return this; }
  56   /// Provides access to the underlying C GObject.
  57   inline const _GtkBoxChild* gobj() const { return this; }
  58
  59   Widget* get_widget() const;
  60
  61   inline guint16 get_padding() const   { return (gobj()->padding); }
  62   inline bool get_expand() const       { return (gobj()->expand); }
  63   inline bool get_fill() const         { return (gobj()->fill); }
  64   inline bool get_pack() const         { return (gobj()->pack); }
  65
  66   void set_options(PackOptions options, guint padding = 0);
  67   void set_options(bool expand, bool fill, guint padding = 0);
  68
  69   void set_pack(PackType pack);
  70
  71 protected:
  72   inline GtkBox* parent()
  73     { return (GtkBox*) (gobj()->widget->parent); }
  74
  75   void redraw();
  76
  77 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  78   friend class Dummy_; // silence the compiler (Child has only private ctors)
  79 #endif
  80 };
  81
  82 class Element
  83 {
  84 public:
  85  Element(Widget& widget,
  86           PackOptions options = PACK_EXPAND_WIDGET,
  87           guint padding = 0,
  88           PackType pack = PACK_START)
  89       : widget_(&widget), options_(options),
  90         padding_(padding), pack_(pack)
  91     {}
  92
  93   Widget* widget_;
  94   PackOptions options_;
  95   guint padding_;
  96   PackType pack_;
  97 };
  98
  99 typedef Element StartElem;
 100
 101 struct EndElem : public Element
 102 {
 103   EndElem(Widget& widget,
 104           PackOptions options = PACK_EXPAND_WIDGET,
 105           guint padding = 0)
 106       : Element (widget, options, padding, PACK_END)
 107     {}
 108 };
 109
 110 #m4 include(list.m4)
 111   GP_LIST(BoxList,Box,GtkBox,Child,children)
 112   //The standard iterator, instead of List_Cpp_Iterator,
 113   //only works because Child is derived from _GtkBoxChild.
 114
 115   GP_LIST_FIND(get_widget)
 116   GP_LIST_CONTAINER_REMOVE(get_widget)
 117         // Non-standard
 118         void reorder(iterator loc,iterator pos);
 119   GP_LIST_END()
 120
 121 } /* namespace Box_Helpers */
 122
 123
 124 /** A base class for box containers
 125  *
 126  * Abstract base class for horizontal and vertical boxes, which organize a
 127  * variable number of widgets into a rectangular area.  This is an abstract
 128  * class and it defers choice of which way the widgets are packed to the screen
 129  * to the derived classes.  It provides a common interface for inserting
 130  * widgets to a box indepenently of how it is shown in the screen.
 131  *
 132  * Gtk::Box uses a notion of packing. Packing refers to adding widgets with
 133  * reference to a particular position in a Gtk::Container. There are two
 134  * reference positions: the start and the end of the box. For a VBox, the start
 135  * is defined as the top of the box and the end is defined as the bottom.  For
 136  * a HBox the start is defined as the left side and the end is defined as the
 137  * right side.  Use repeated calls to pack_start() to pack widgets into a
 138  * Gtk::Box from start to end. Use pack_end() to add widgets from end to start.
 139  * You may intersperse these calls and add widgets from both ends of the same
 140  * Gtk::Box. The last widget added with pack_start() will be placed just before
 141  * the last widget added with pack_end()
 142  *
 143  * Because Gtk::Box is a Gtk::Container, you may also use Gtk::Container::add()
 144  * to insert widgets, and they will be packed as if with pack_start(). Use
 145  * Gtk::Container::remove() to remove widgets.
 146  *
 147  * Use set_homogeneous() to specify whether or not all children of the Gtk::Box
 148  * occupy the same amount of space.  Use set_spacing() to determine the minimum
 149  * space placed between all children in the Gtk::Box.  Use reorder_child() to
 150  * move a child widget to a different place in the box.  Use
 151  * set_child_packing() to reset the pack options and padding attributes of any
 152  * Gtk::Box child. Use query_child_packing() to query these fields.
 153  */
 154 class Box : public Container
 155 {
 156   _CLASS_GTKOBJECT(Box,GtkBox,GTK_BOX,Gtk::Container,GtkContainer)
 157   _IGNORE(gtk_box_pack_end_defaults, gtk_box_set_child_packing, gtk_box_pack_start_defaults, gtk_box_query_child_packing)
 158 public:
 159   typedef Box_Helpers::BoxList BoxList;
 160
 161 protected:
 162   _CTOR_DEFAULT
 163 public:
 164
 165   _WRAP_METHOD(void pack_start(Widget& child, bool expand, bool fill, guint padding = 0), gtk_box_pack_start)
 166
 167   /** Left side insert a widget to a box.
 168    * @param child A Widget to be added to box.
 169    * @param options Controls how the widget expands to fill space, and how the space around them is used.
 170    * @param padding Padding that is added on either side of the widget. This is different to spacing set when the box is created (or with set_spacing()) - spacing is added between objects, and padding is added on either side of an object.
 171    */
 172   void pack_start(Widget& child, PackOptions options = PACK_EXPAND_WIDGET, guint padding = 0);
 173
 174   _WRAP_METHOD(void pack_end(Widget& child, bool expand, bool fill, guint padding = 0), gtk_box_pack_end)
 175
 176   /** Right side insert a widget to a box.
 177    * @param child A Widget to be added to box.
 178    * @param options Controls how the widget expands to fill space, and how the space around them is used.
 179    * @param padding Padding that is added on either side of the widget. This is different to spacing set when the box is created (or with set_spacing()) - spacing is added between objects, and padding is added on either side of an object.
 180    */
 181   void pack_end(Widget& child, PackOptions options = PACK_EXPAND_WIDGET, guint padding = 0);
 182
 183   _WRAP_METHOD(void set_homogeneous(bool homogeneous = true), gtk_box_set_homogeneous)
 184   _WRAP_METHOD(bool get_homogeneous() const, gtk_box_get_homogeneous)
 185
 186   _WRAP_METHOD(void set_spacing(int spacing), gtk_box_set_spacing)
 187   _WRAP_METHOD(int get_spacing() const, gtk_box_get_spacing)
 188
 189   _WRAP_METHOD(void reorder_child(Widget& child, int pos), gtk_box_reorder_child)
 190
 191   /* Get the child widgets.
 192    * @result An STL-style container of pointers to the box's child widgets.
 193    */
 194   BoxList& children();
 195
 196   /* Get the child widgets.
 197    * @result An STL-style container of pointers to the box's child widgets.
 198    */
 199   const BoxList& children() const;
 200
 201   _WRAP_PROPERTY("spacing", int)
 202   _WRAP_PROPERTY("homogeneous", bool)
 203
 204 protected:
 205 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 206   mutable BoxList children_proxy_;
 207 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 208 };
 209
 210
 211 /** Vertical Box for laying widgets in a vertical row.
 212  *
 213  * You should create these objects, but it is more confortable to pass
 214  * around pointers of Gtk::Box. All the methods that do anything are in
 215  * class Gtk::Box and this allows you to later change the direction of the
 216  * box, when there's no dependencies to HBox and VBox classes.
 217  *
 218  * @ingroup Widgets
 219  * @ingroup Containers
 220  */
 221 class VBox : public Box
 222 {
 223   _CLASS_GTKOBJECT(VBox,GtkVBox,GTK_VBOX,Gtk::Box,GtkBox)
 224 public:
 225
 226   /** Creates a new vertical box.
 227    * @param homogeneous Whether each widget in the VBox should have the same
 228    * height.  If set, a PACK_SHRINK argument to pack_start() or pack_end() is
 229    * ignored.
 230    * @param spacing Determines the space in pixels between child widgets.
 231    */
 232   _WRAP_CTOR(VBox(bool homogeneous = false, int spacing = 0), gtk_vbox_new)
 233
 234 };
 235
 236 /** Horizontal Box for laying widgets in a horizontal row.
 237  *
 238  * You should create these objects, but it is more confortable to pass
 239  * around pointers of Gtk::Box. All the methods that do anything are in
 240  * class Gtk::Box and this allows you to later change the direction of the
 241  * box, when there's no dependencies to HBox and VBox classes.
 242  *
 243  * Use the Gtk::Box packing interface to determine the arrangement, spacing,
 244  * width, and alignment of Gtk::HBox children.
 245  *
 246  * All children are allocated the same height.
 247  *
 248  * @ingroup Widgets
 249  * @ingroup Containers
 250  */
 251 class HBox : public Box
 252 {
 253   _CLASS_GTKOBJECT(HBox,GtkHBox,GTK_HBOX,Gtk::Box,GtkBox)
 254 public:
 255
 256   /** Creates a new horizontal box.
 257    * @param homogeneous Whether each widget in the HBox should have the same
 258    * width.  If set, a PACK_SHRINK argument to pack_start() or pack_end() is
 259    * ignored.
 260    * @param spacing Determines the space in pixels between child widgets.
 261    */
 262   _WRAP_CTOR(HBox(bool homogeneous = false, int spacing = 0), gtk_hbox_new)
 263
 264 };
 265
 266 } // namespace Gtk
 267