libs/gtkmm2/gtk/gtkmm/container.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_CONTAINER_H
   4 #define _GTKMM_CONTAINER_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* Copyright (C) 1998-2002 The gtkmm Development Team
  11  *
  12  * This library is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Library General Public
  14  * License as published by the Free Software Foundation; either
  15  * version 2 of the License, or (at your option) any later version.
  16  *
  17  * This library is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with this library; if not, write to the Free
  24  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25  */
  26
  27 #include <glibmm/listhandle.h>
  28 #include <gtkmm/widget.h>
  29
  30
  31 /** @defgroup Containers Container Widgets
  32  * These widgets can be used to group other widgets together.
  33  */
  34
  35 /* we'll include gtkfeatures because we dont want to include the whole
  36    gtk/gtk.h - this file is used by almost ALL our widgets, so dependencies
  37    in minimum - adding things here will increase compile times ALOT */
  38
  39
  40 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  41 typedef struct _GtkContainer GtkContainer;
  42 typedef struct _GtkContainerClass GtkContainerClass;
  43 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  44
  45
  46 namespace Gtk
  47 { class Container_Class; } // namespace Gtk
  48 namespace Gtk
  49 {
  50
  51 class Adjustment;
  52 class Label;
  53
  54 /** Abstract container class
  55  *
  56  * This is the abstract container from which all gtk+ widgets which hold
  57  * other items derive from.  It mainly houses virtual functions
  58  * used for inserting and removing children.  Containers in gtk+
  59  * may hold one item or many items depending on the implementation.
  60  *
  61  * This interface is used for all single item holding containers.
  62  * Multi-item containers provide their own unique interface as their
  63  * items are generally more complex.  The methods of the derived
  64  * classes should be prefered over these.
  65  *
  66  * @ingroup Widgets
  67  */
  68
  69 class Container : public Widget
  70 {
  71   public:
  72 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  73   typedef Container CppObjectType;
  74   typedef Container_Class CppClassType;
  75   typedef GtkContainer BaseObjectType;
  76   typedef GtkContainerClass BaseClassType;
  77 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  78
  79   virtual ~Container();
  80
  81 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  82
  83 private:
  84   friend class Container_Class;
  85   static CppClassType container_class_;
  86
  87   // noncopyable
  88   Container(const Container&);
  89   Container& operator=(const Container&);
  90
  91 protected:
  92   explicit Container(const Glib::ConstructParams& construct_params);
  93   explicit Container(GtkContainer* castitem);
  94
  95 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  96
  97 public:
  98 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  99   static GType get_type()      G_GNUC_CONST;
 100   static GType get_base_type() G_GNUC_CONST;
 101 #endif
 102
 103   ///Provides access to the underlying C GtkObject.
 104   GtkContainer*       gobj()       { return reinterpret_cast<GtkContainer*>(gobject_); }
 105
 106   ///Provides access to the underlying C GtkObject.
 107   const GtkContainer* gobj() const { return reinterpret_cast<GtkContainer*>(gobject_); }
 108
 109
 110 public:
 111   //C++ methods used to invoke GTK+ virtual functions:
 112
 113 protected:
 114   //GTK+ Virtual Functions (override these to change behaviour):
 115
 116   //Default Signal Handlers::
 117   virtual void on_add(Widget* widget);
 118   virtual void on_remove(Widget* widget);
 119   virtual void on_check_resize();
 120   virtual void on_set_focus_child(Widget* widget);
 121
 122
 123 private:
 124
 125
 126 public:
 127
 128 /* Application-level methods */
 129
 130
 131   /** Sets the border width of the container.
 132    *
 133    * The border width of a container is the amount of space to leave
 134    * around the outside of the container. The only exception to this is
 135    * Gtk::Window; because toplevel windows can't leave space outside,
 136    * they leave the space inside. The border is added on all sides of
 137    * the container. To add space to only one side, one approach is to
 138    * create a Gtk::Alignment widget, call Gtk::Widget::set_usize() to give
 139    * it a size, and place it on the side of the container as a spacer.
 140    * @param border_width Amount of blank space to leave <em>outside</em> the container.
 141    * Valid values are in the range 0-65535 pixels.
 142    */
 143   void set_border_width(guint border_width);
 144
 145
 146   /** Retrieves the border width of the container. See
 147    * set_border_width().
 148    * @return The current border width.
 149    */
 150   guint get_border_width() const;
 151
 152   //This is virtual so that we can override it in Gtk::ScrolledWindow:
 153  virtual void add(Widget& widget);
 154
 155
 156   /** Removes @a widget  from @a container . @a widget  must be inside @a container .
 157    * Note that @a container  will own a reference to @a widget , and that this
 158    * may be the last reference held; so removing a widget from its
 159    * container can destroy that widget. If you want to use @a widget
 160    * again, you need to add a reference to it while it's not inside
 161    * a container, using Glib::object_ref(). If you don't want to use @a widget
 162    * again it's usually more efficient to simply destroy it directly
 163    * using Gtk::Widget::destroy() since this will remove it from the
 164    * container and help break any circular reference count cycles.
 165    * @param widget A current child of @a container .
 166    */
 167
 168   void remove(Widget& widget);
 169
 170
 171   /** Sets the resize mode for the container.
 172    *
 173    * The resize mode of a container determines whether a resize request
 174    * will be passed to the container's parent, queued for later execution
 175    * or executed immediately.
 176    * @param resize_mode The new resize mode.
 177    */
 178   void set_resize_mode(ResizeMode resize_mode);
 179
 180
 181   /** Returns the resize mode for the container. See
 182    * set_resize_mode().
 183    * @return The current resize mode.
 184    */
 185   ResizeMode get_resize_mode() const;
 186
 187   /// Request that contained widgets check their size
 188
 189   void check_resize();
 190
 191   /** For instance,
 192    * void on_foreach(Gtk::Widget* widget);
 193    */
 194   typedef sigc::slot<void, Widget&> ForeachSlot;
 195
 196   /** Operate on contained items
 197    * This is largely an internal used mainly for things like
 198    * creating duplicates of internal lists and other such
 199    * operations.  The result is lossy as it only gets the
 200    * the main child and not its external pieces.
 201    *
 202    * For example notebook pages contain a page, a label, and
 203    * a menu item.  But this only operates on the pages.
 204    */
 205   void foreach(const ForeachSlot& slot);
 206
 207   /// (internal) Operate on contained items (see foreach())
 208   //_WRAP_METHOD(void foreach_(GtkCallback callback,gpointer data),gtk_container_foreach)
 209
 210   /// (internal) Operate on contained items (see foreach())
 211   //_WRAP_METHOD(void foreach_full_(GtkCallback callback,GtkCallbackMarshal marshal, gpointer data,GtkDestroyNotify notify),gtk_container_foreach_full)
 212
 213
 214   /** Returns the the container's non-internal children. See
 215    * forall() for details on what constitutes an "internal" child.
 216    * @return A newly-allocated list of the container's non-internal children.
 217    */
 218   Glib::ListHandle<Widget*> get_children();
 219
 220   /** Returns the the container's non-internal children. See
 221    * forall() for details on what constitutes an "internal" child.
 222    * @return A newly-allocated list of the container's non-internal children.
 223    */
 224   Glib::ListHandle<const Widget*> get_children() const;
 225
 226
 227   /** When a container receives an expose event, it must send synthetic
 228    * expose events to all children that don't have their own Gdk::Windows.
 229    * This function provides a convenient way of doing this. A container,
 230    * when it receives an expose event, calls propagate_expose()
 231    * once for each child, passing in the event the container received.
 232    *
 233    * propagate_expose() takes care of deciding whether
 234    * an expose event needs to be sent to the child, intersecting
 235    * the event's area with the child area, and sending the event.
 236    *
 237    * In most cases, a container can simply either simply inherit the
 238    * ::expose implementation from Gtk::Container, or, do some drawing
 239    * and then chain to the ::expose implementation from Gtk::Container.
 240    * @param child A child of @a container .
 241    * @param event A expose event sent to container.
 242    */
 243   void propagate_expose(Widget& child, GdkEventExpose* event);
 244
 245
 246   /** Sets a focus chain, overriding the one computed automatically by GTK+.
 247    *
 248    * In principle each widget in the chain should be a descendant of the
 249    * container, but this is not enforced by this method, since it's allowed
 250    * to set the focus chain before you pack the widgets, or have a widget
 251    * in the chain that isn't always packed. The necessary checks are done
 252    * when the focus chain is actually traversed.
 253    * @param focusable_widgets The new focus chain.
 254    */
 255   void set_focus_chain(const Glib::ListHandle<Widget*>& focusable_widgets);
 256
 257   // gtk_container_get_focus_chain() has been split up into two
 258   // functions in order to make implicit container conversion possible.
 259   bool has_focus_chain() const;
 260   Glib::ListHandle<Widget*> get_focus_chain();
 261   Glib::ListHandle<const Widget*> get_focus_chain() const;
 262
 263
 264   /** Removes a focus chain explicitly set with set_focus_chain().
 265    */
 266   void unset_focus_chain();
 267
 268
 269 /* Widget-level methods */
 270
 271
 272   /** Sets the @a reallocate_redraws  flag of the container to the given value.
 273    *
 274    * Containers requesting reallocation redraws get automatically
 275    * redrawn if any of their children changed allocation.
 276    * @param needs_redraws The new value for the container's @a reallocate_redraws  flag.
 277    */
 278   void set_reallocate_redraws(bool needs_redraws = true);
 279
 280   /// Sets the focus on a child
 281
 282   void set_focus_child(Widget& widget);
 283
 284
 285   /** Hooks up an adjustment to focus handling in a container, so when a child of the
 286    * container is focused, the adjustment is scrolled to show that widget. This function
 287    * sets the vertical alignment. See Gtk::ScrolledWindow::get_vadjustment() for a typical
 288    * way of obtaining the adjustment and set_focus_hadjustment() for setting
 289    * the horizontal adjustment.
 290    *
 291    * The adjustments have to be in pixel units and in the same coordinate system as the
 292    * allocation for immediate children of the container.
 293    * @param adjustment An adjustment which should be adjusted when the focus is moved among the
 294    * descendents of @a container .
 295    */
 296   void set_focus_vadjustment(Adjustment& adjustment);
 297
 298
 299   /** Retrieves the vertical focus adjustment for the container. See
 300    * set_focus_vadjustment().
 301    * @return The vertical focus adjustment, or <tt>0</tt> if
 302    * none has been set.
 303    */
 304   Adjustment* get_focus_vadjustment();
 305
 306   /** Retrieves the vertical focus adjustment for the container. See
 307    * set_focus_vadjustment().
 308    * @return The vertical focus adjustment, or <tt>0</tt> if
 309    * none has been set.
 310    */
 311   const Adjustment* get_focus_vadjustment() const;
 312
 313
 314   /** Hooks up an adjustment to focus handling in a container, so when a child of the
 315    * container is focused, the adjustment is scrolled to show that widget. This function
 316    * sets the horizontal alignment. See Gtk::ScrolledWindow::get_hadjustment() for a typical
 317    * way of obtaining the adjustment and set_focus_vadjustment() for setting
 318    * the vertical adjustment.
 319    *
 320    * The adjustments have to be in pixel units and in the same coordinate system as the
 321    * allocation for immediate children of the container.
 322    * @param adjustment An adjustment which should be adjusted when the focus is moved among the
 323    * descendents of @a container .
 324    */
 325   void set_focus_hadjustment(Adjustment& adjustment);
 326
 327
 328   /** Retrieves the horizontal focus adjustment for the container. See
 329    * set_focus_hadjustment().
 330    * @return The horizontal focus adjustment, or <tt>0</tt> if
 331    * none has been set.
 332    */
 333   Adjustment* get_focus_hadjustment();
 334
 335   /** Retrieves the horizontal focus adjustment for the container. See
 336    * set_focus_hadjustment().
 337    * @return The horizontal focus adjustment, or <tt>0</tt> if
 338    * none has been set.
 339    */
 340   const Adjustment* get_focus_hadjustment() const;
 341
 342
 343   void resize_children();
 344
 345
 346   /** Returns the type of the children supported by the container.
 347    *
 348    * Note that this may return G::TYPE_NONE to indicate that no more
 349    * children can be added, e.g. for a Gtk::Paned which already has two
 350    * children.
 351    * @return A G::Type.
 352    */
 353   GType child_type() const;
 354
 355   // Ignore functions such as gtk_container_class_install_child_property(),  which I think are for themes, like the GtkWidget style properties.
 356
 357
 358   Glib::SignalProxy1< void,Widget* > signal_add();
 359
 360
 361   Glib::SignalProxy1< void,Widget* > signal_remove();
 362
 363
 364   Glib::SignalProxy0< void > signal_check_resize();
 365
 366
 367   Glib::SignalProxy1< void,Widget* > signal_set_focus_child();
 368
 369
 370   void show_all_children(bool recursive = true);
 371
 372 protected:
 373   Container();
 374
 375     virtual GtkType child_type_vfunc() const;
 376     virtual void forall_vfunc(gboolean include_internals, GtkCallback callback, gpointer callback_data);
 377   //TODO: What is this?
 378     virtual char* composite_name_vfunc(GtkWidget* child);
 379     virtual void set_child_property_vfunc(GtkWidget* child, guint property_id, const GValue* value, GParamSpec* pspec);
 380     virtual void get_child_property_vfunc(GtkWidget* child, guint property_id, GValue* value, GParamSpec* pspec) const;
 381
 382   /** The width of the empty border outside the containers children.
 383    *
 384    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 385    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 386    * the value of the property changes.
 387    */
 388   Glib::PropertyProxy<guint> property_border_width() ;
 389
 390 /** The width of the empty border outside the containers children.
 391    *
 392    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 393    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 394    * the value of the property changes.
 395    */
 396   Glib::PropertyProxy_ReadOnly<guint> property_border_width() const;
 397
 398   /** Specify how resize events are handled.
 399    *
 400    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 401    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 402    * the value of the property changes.
 403    */
 404   Glib::PropertyProxy<ResizeMode> property_resize_mode() ;
 405
 406 /** Specify how resize events are handled.
 407    *
 408    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 409    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 410    * the value of the property changes.
 411    */
 412   Glib::PropertyProxy_ReadOnly<ResizeMode> property_resize_mode() const;
 413
 414   /** Can be used to add a new child to the container.
 415    *
 416    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 417    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 418    * the value of the property changes.
 419    */
 420   Glib::PropertyProxy_WriteOnly<Widget*> property_child() ;
 421
 422 /** Can be used to add a new child to the container.
 423    *
 424    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 425    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 426    * the value of the property changes.
 427    */
 428   Glib::PropertyProxy_ReadOnly<Widget*> property_child() const;
 429
 430
 431 };
 432
 433 } // namespace Gtk
 434
 435
 436 namespace Glib
 437 {
 438   /** @relates Gtk::Container
 439    * @param object The C instance
 440    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 441    * @result A C++ instance that wraps this C instance.
 442    */
 443   Gtk::Container* wrap(GtkContainer* object, bool take_copy = false);
 444 }
 445 #endif /* _GTKMM_CONTAINER_H */
 446