2 // Generated by gtkmmproc -- DO NOT MODIFY!
3 #ifndef _GTKMM_WIDGET_H
4 #define _GTKMM_WIDGET_H
10 /* Copyright (C) 2002, 2003 The gtkmm Development Team
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.
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.
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.
27 #include <pangomm/context.h>
28 #include <pangomm/layout.h>
29 #include <atkmm/object.h>
30 #include <atkmm/implementor.h>
31 #include <gdkmm/event.h>
32 #include <gdkmm/types.h>
33 #include <gdkmm/window.h>
34 #include <gdkmm/dragcontext.h>
35 #include <gdkmm/pixbuf.h>
36 #include <gdkmm/screen.h>
37 #include <gtkmm/enums.h>
38 #include <gdkmm/display.h>
39 //#include <gtkmm/style.h>
40 #include <gtkmm/targetlist.h>
42 #include <gtkmm/object.h>
43 #include <gtkmm/clipboard.h>
46 #ifndef DOXYGEN_SHOULD_SKIP_THIS
49 typedef struct _GtkTargetEntry GtkTargetEntry;
51 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
53 #ifndef DOXYGEN_SHOULD_SKIP_THIS
54 typedef struct _GtkWidget GtkWidget;
55 typedef struct _GtkWidgetClass GtkWidgetClass;
56 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
60 { class Widget_Class; } // namespace Gtk
65 /** @addtogroup gtkmmEnums Enums and Flags */
69 * @par Bitwise operators:
70 * <tt>%DestDefaults operator|(DestDefaults, DestDefaults)</tt><br>
71 * <tt>%DestDefaults operator&(DestDefaults, DestDefaults)</tt><br>
72 * <tt>%DestDefaults operator^(DestDefaults, DestDefaults)</tt><br>
73 * <tt>%DestDefaults operator~(DestDefaults)</tt><br>
74 * <tt>%DestDefaults& operator|=(DestDefaults&, DestDefaults)</tt><br>
75 * <tt>%DestDefaults& operator&=(DestDefaults&, DestDefaults)</tt><br>
76 * <tt>%DestDefaults& operator^=(DestDefaults&, DestDefaults)</tt><br>
80 DEST_DEFAULT_MOTION = 1 << 0,
81 DEST_DEFAULT_HIGHLIGHT = 1 << 1,
82 DEST_DEFAULT_DROP = 1 << 2,
83 DEST_DEFAULT_ALL = 0x07
86 /** @ingroup gtkmmEnums */
87 inline DestDefaults operator|(DestDefaults lhs, DestDefaults rhs)
88 { return static_cast<DestDefaults>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
90 /** @ingroup gtkmmEnums */
91 inline DestDefaults operator&(DestDefaults lhs, DestDefaults rhs)
92 { return static_cast<DestDefaults>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
94 /** @ingroup gtkmmEnums */
95 inline DestDefaults operator^(DestDefaults lhs, DestDefaults rhs)
96 { return static_cast<DestDefaults>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
98 /** @ingroup gtkmmEnums */
99 inline DestDefaults operator~(DestDefaults flags)
100 { return static_cast<DestDefaults>(~static_cast<unsigned>(flags)); }
102 /** @ingroup gtkmmEnums */
103 inline DestDefaults& operator|=(DestDefaults& lhs, DestDefaults rhs)
104 { return (lhs = static_cast<DestDefaults>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
106 /** @ingroup gtkmmEnums */
107 inline DestDefaults& operator&=(DestDefaults& lhs, DestDefaults rhs)
108 { return (lhs = static_cast<DestDefaults>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
110 /** @ingroup gtkmmEnums */
111 inline DestDefaults& operator^=(DestDefaults& lhs, DestDefaults rhs)
112 { return (lhs = static_cast<DestDefaults>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
117 #ifndef DOXYGEN_SHOULD_SKIP_THIS
122 class Value<Gtk::DestDefaults> : public Glib::Value_Flags<Gtk::DestDefaults>
125 static GType value_type() G_GNUC_CONST;
129 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
136 * @ingroup gtkmmEnums
137 * @par Bitwise operators:
138 * <tt>%WidgetFlags operator|(WidgetFlags, WidgetFlags)</tt><br>
139 * <tt>%WidgetFlags operator&(WidgetFlags, WidgetFlags)</tt><br>
140 * <tt>%WidgetFlags operator^(WidgetFlags, WidgetFlags)</tt><br>
141 * <tt>%WidgetFlags operator~(WidgetFlags)</tt><br>
142 * <tt>%WidgetFlags& operator|=(WidgetFlags&, WidgetFlags)</tt><br>
143 * <tt>%WidgetFlags& operator&=(WidgetFlags&, WidgetFlags)</tt><br>
144 * <tt>%WidgetFlags& operator^=(WidgetFlags&, WidgetFlags)</tt><br>
154 PARENT_SENSITIVE = 1 << 10,
157 CAN_DEFAULT = 1 << 13,
158 HAS_DEFAULT = 1 << 14,
161 COMPOSITE_CHILD = 1 << 17,
162 NO_REPARENT = 1 << 18,
163 APP_PAINTABLE = 1 << 19,
164 RECEIVES_DEFAULT = 1 << 20,
165 DOUBLE_BUFFERED = 1 << 21,
166 NO_SHOW_ALL = 1 << 22
169 /** @ingroup gtkmmEnums */
170 inline WidgetFlags operator|(WidgetFlags lhs, WidgetFlags rhs)
171 { return static_cast<WidgetFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
173 /** @ingroup gtkmmEnums */
174 inline WidgetFlags operator&(WidgetFlags lhs, WidgetFlags rhs)
175 { return static_cast<WidgetFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
177 /** @ingroup gtkmmEnums */
178 inline WidgetFlags operator^(WidgetFlags lhs, WidgetFlags rhs)
179 { return static_cast<WidgetFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
181 /** @ingroup gtkmmEnums */
182 inline WidgetFlags operator~(WidgetFlags flags)
183 { return static_cast<WidgetFlags>(~static_cast<unsigned>(flags)); }
185 /** @ingroup gtkmmEnums */
186 inline WidgetFlags& operator|=(WidgetFlags& lhs, WidgetFlags rhs)
187 { return (lhs = static_cast<WidgetFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
189 /** @ingroup gtkmmEnums */
190 inline WidgetFlags& operator&=(WidgetFlags& lhs, WidgetFlags rhs)
191 { return (lhs = static_cast<WidgetFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
193 /** @ingroup gtkmmEnums */
194 inline WidgetFlags& operator^=(WidgetFlags& lhs, WidgetFlags rhs)
195 { return (lhs = static_cast<WidgetFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
200 #ifndef DOXYGEN_SHOULD_SKIP_THIS
205 class Value<Gtk::WidgetFlags> : public Glib::Value_Flags<Gtk::WidgetFlags>
208 static GType value_type() G_GNUC_CONST;
212 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
219 * @ingroup gtkmmEnums
224 WIDGET_HELP_WHATS_THIS
230 #ifndef DOXYGEN_SHOULD_SKIP_THIS
235 class Value<Gtk::WidgetHelpType> : public Glib::Value_Enum<Gtk::WidgetHelpType>
238 static GType value_type() G_GNUC_CONST;
242 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
256 typedef GtkRequisition Requisition;
258 // Gtk::Allocation is a typedef of Gdk::Rectangle because GtkAllocation is
259 // a typedef of GdkRectangle.
260 typedef Gdk::Rectangle Allocation;
263 /** @defgroup Widgets Widgets
266 /** Abstract Widget (Base class for all widgets)
268 * As the base class of all widgets this contains all of the properties
269 * and methods common to all widgets. It is an abstract class that
270 * can not be instantiated.
272 * Important part of widgets are the *_event signals and virtual methods
273 * that every widget have. Those are events coming directly from gdk and
274 * thus also from XLib. By overriding those virtual methods you can
275 * trap everything a widget can ever do.
276 * In order to capture events from a widget, the event mask must
277 * first be set with ().
279 * Only widgets with a Gdk::Window on the server side are allowed to
280 * capture events. Widgets in the Gtk::Misc group for example lack
286 public Atk::Implementor
289 #ifndef DOXYGEN_SHOULD_SKIP_THIS
290 typedef Widget CppObjectType;
291 typedef Widget_Class CppClassType;
292 typedef GtkWidget BaseObjectType;
293 typedef GtkWidgetClass BaseClassType;
294 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
298 #ifndef DOXYGEN_SHOULD_SKIP_THIS
301 friend class Widget_Class;
302 static CppClassType widget_class_;
305 Widget(const Widget&);
306 Widget& operator=(const Widget&);
309 explicit Widget(const Glib::ConstructParams& construct_params);
310 explicit Widget(GtkWidget* castitem);
312 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
315 #ifndef DOXYGEN_SHOULD_SKIP_THIS
316 static GType get_type() G_GNUC_CONST;
317 static GType get_base_type() G_GNUC_CONST;
320 ///Provides access to the underlying C GtkObject.
321 GtkWidget* gobj() { return reinterpret_cast<GtkWidget*>(gobject_); }
323 ///Provides access to the underlying C GtkObject.
324 const GtkWidget* gobj() const { return reinterpret_cast<GtkWidget*>(gobject_); }
328 //C++ methods used to invoke GTK+ virtual functions:
331 //GTK+ Virtual Functions (override these to change behaviour):
333 //Default Signal Handlers::
334 virtual void on_show();
335 virtual void on_hide();
336 virtual void on_map();
337 virtual void on_unmap();
338 virtual void on_realize();
339 virtual void on_unrealize();
340 virtual void on_size_request(Requisition* requisition);
341 virtual void on_size_allocate(Allocation& allocation);
342 virtual void on_state_changed(Gtk::StateType previous_state);
343 virtual void on_parent_changed(Widget* previous_parent);
344 virtual void on_hierarchy_changed(Widget* previous_toplevel);
345 virtual void on_style_changed(const Glib::RefPtr<Style>& previous_style);
346 virtual void on_direction_changed(TextDirection direction);
347 virtual void on_grab_notify(bool was_grabbed);
348 virtual void on_child_notify(GParamSpec* pspec);
349 virtual bool on_mnemonic_activate(bool group_cycling);
350 virtual void on_grab_focus();
351 virtual bool on_focus(DirectionType direction);
352 virtual bool on_event(GdkEvent* event);
353 virtual bool on_button_press_event(GdkEventButton* event);
354 virtual bool on_button_release_event(GdkEventButton* event);
355 virtual bool on_scroll_event(GdkEventScroll* event);
356 virtual bool on_motion_notify_event(GdkEventMotion* event);
357 virtual bool on_delete_event(GdkEventAny* event);
358 virtual bool on_expose_event(GdkEventExpose* event);
359 virtual bool on_key_press_event(GdkEventKey* event);
360 virtual bool on_key_release_event(GdkEventKey* event);
361 virtual bool on_enter_notify_event(GdkEventCrossing* event);
362 virtual bool on_leave_notify_event(GdkEventCrossing* event);
363 virtual bool on_configure_event(GdkEventConfigure* event);
364 virtual bool on_focus_in_event(GdkEventFocus* event);
365 virtual bool on_focus_out_event(GdkEventFocus* event);
366 virtual bool on_map_event(GdkEventAny* event);
367 virtual bool on_unmap_event(GdkEventAny* event);
368 virtual bool on_property_notify_event(GdkEventProperty* event);
369 virtual bool on_selection_clear_event(GdkEventSelection* event);
370 virtual bool on_selection_request_event(GdkEventSelection* event);
371 virtual bool on_selection_notify_event(GdkEventSelection* event);
372 virtual bool on_proximity_in_event(GdkEventProximity* event);
373 virtual bool on_proximity_out_event(GdkEventProximity* event);
374 virtual bool on_visibility_notify_event(GdkEventVisibility* event);
375 virtual bool on_client_event(GdkEventClient* event);
376 virtual bool on_no_expose_event(GdkEventAny* event);
377 virtual bool on_window_state_event(GdkEventWindowState* event);
378 virtual void on_selection_get(SelectionData& selection_data, guint info, guint time);
379 virtual void on_selection_received(const SelectionData& selection_data, guint time);
380 virtual void on_drag_begin(const Glib::RefPtr<Gdk::DragContext>& context);
381 virtual void on_drag_end(const Glib::RefPtr<Gdk::DragContext>& context);
382 virtual void on_drag_data_get(const Glib::RefPtr<Gdk::DragContext>& context, SelectionData& selection_data, guint info, guint time);
383 virtual void on_drag_data_delete(const Glib::RefPtr<Gdk::DragContext>& context);
384 virtual void on_drag_leave(const Glib::RefPtr<Gdk::DragContext>& context, guint time);
385 virtual bool on_drag_motion(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, guint time);
386 virtual bool on_drag_drop(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, guint time);
387 virtual void on_drag_data_received(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, const SelectionData& selection_data, guint info, guint time);
388 virtual Glib::RefPtr<Atk::Object> on_get_accessible();
389 virtual void on_screen_changed(const Glib::RefPtr<Gdk::Screen>& previous_screen);
399 /** For widgets that support scrolling, sets the scroll adjustments and
400 * returns <tt>true</tt>. For widgets that don't support scrolling, does
401 * nothing and returns <tt>false</tt>. Widgets that don't support scrolling
402 * can be scrolled by placing them in a Gtk::Viewport, which does
404 * @param hadjustment An adjustment for horizontal scrolling, or <tt>0</tt>.
405 * @param vadjustment An adjustment for vertical scrolling, or <tt>0</tt>.
406 * @return <tt>true</tt> if the widget supports scrolling.
408 bool set_scroll_adjustments(Adjustment& hadjustment, Adjustment& vadjustment);
411 /** Flags a widget to be displayed. Any widget that isn't shown will
412 * not appear on the screen. If you want to show all the widgets in a
413 * container, it's easier to call show_all() on the
414 * container, instead of individually showing the widgets.
416 * Remember that you have to show the containers containing a widget,
417 * in addition to the widget itself, before it will appear onscreen.
419 * When a toplevel container is shown, it is immediately realized and
420 * mapped; other shown widgets are realized and mapped when their
421 * toplevel container is realized and mapped.
425 /** Shows a widget. If the widget is an unmapped toplevel widget
426 * (i.e. a Gtk::Window that has not yet been shown), enter the main
427 * loop and wait for the window to actually be mapped. Be careful;
428 * because the main loop is running, anything can happen during
433 /** Reverses the effects of show(), causing the widget to be
434 * hidden (invisible to the user).
439 /** Recursively shows a widget, and any child widgets (if the widget is
445 /** Recursively hides a widget and any child widgets.
453 /** Equivalent to calling queue_draw_area() for the
454 * entire area of a widget.
458 /** Invalidates the rectangular area of @a widget defined by @a x , @a y ,
459 * @a width and @a height by calling gdk_window_invalidate_rect() on the
460 * widget's window and all its child windows. Once the main loop
461 * becomes idle (after the current batch of events has been processed,
462 * roughly), the window will receive expose events for the union of
463 * all regions that have been invalidated.
465 * Normally you would only use this function in widget
466 * implementations. You might also use it, or
467 * gdk_window_invalidate_rect() directly, to schedule a redraw of a
468 * Gtk::DrawingArea or some portion thereof.
470 * Frequently you can just call gdk_window_invalidate_rect() or
471 * gdk_window_invalidate_region() instead of this function. Those
472 * functions will invalidate only a single window, instead of the
473 * widget and all its children.
475 * The advantage of adding to the invalidated region compared to
476 * simply drawing immediately is efficiency; using an invalid region
477 * ensures that you only have to redraw one time.
478 * @param x X coordinate of upper-left corner of rectangle to redraw.
479 * @param y Y coordinate of upper-left corner of rectangle to redraw.
480 * @param width Width of region to draw.
481 * @param height Height of region to draw.
483 void queue_draw_area(int x, int y, int width, int height);
485 /** This function is only for use in widget implementations.
486 * Flags a widget to have its size renegotiated; should
487 * be called when a widget for some reason has a new size request.
488 * For example, when you change the text in a Gtk::Label, Gtk::Label
489 * queues a resize to ensure there's enough space for the new text.
493 /** This function is typically used when implementing a Gtk::Container
494 * subclass. Obtains the preferred size of a widget. The container
495 * uses this information to arrange its child widgets and decide what
496 * size allocations to give them with size_allocate().
498 * You can also call this function from an application, with some
499 * caveats. Most notably, getting a size request requires the widget
500 * to be associated with a screen, because font information may be
501 * needed. Multihead-aware applications should keep this in mind.
503 * Also remember that the size request is not necessarily the size
504 * a widget will actually be allocated.
506 * See also get_child_requisition().
507 * @result A Gtk::Requisition.
509 Requisition size_request() const;
512 //Deprecated, because the Requisition should be an output parameter. This could never have been used.
514 /** This function is typically used when implementing a Gtk::Container
515 * subclass. Obtains the preferred size of a widget. The container
516 * uses this information to arrange its child widgets and decide what
517 * size allocations to give them with size_allocate().
519 * You can also call this function from an application, with some
520 * caveats. Most notably, getting a size request requires the widget
521 * to be associated with a screen, because font information may be
522 * needed. Multihead-aware applications should keep this in mind.
524 * Also remember that the size request is not necessarily the size
525 * a widget will actually be allocated.
527 * See also get_child_requisition().
528 * @param requisition A Gtk::Requisition to be filled in.
530 void size_request(const Requisition& requisition);
533 /** This function is only used by Gtk::Container subclasses, to assign a size
534 * and position to their child widgets.
535 * @param allocation Position and size to be allocated to @a widget .
537 void size_allocate(const Allocation& allocation);
540 /** Installs an accelerator for this @a widget in @a accel_group that causes
541 * @a accel_signal to be emitted if the accelerator is activated.
542 * The @a accel_group needs to be added to the widget's toplevel via
543 * Gtk::Window::add_accel_group(), and the signal must be of type G::RUN_ACTION.
544 * Accelerators added through this function are not user changeable during
545 * runtime. If you want to support accelerators that can be changed by the
546 * user, use gtk_accel_map_add_entry() and set_accel_path() or
547 * Gtk::MenuItem::set_accel_path() instead.
548 * @param accel_signal Widget signal to emit on accelerator activation.
549 * @param accel_group Accel group for this widget, added to its toplevel.
550 * @param accel_key GDK keyval of the accelerator.
551 * @param accel_mods Modifier key combination of the accelerator.
552 * @param accel_flags Flag accelerators, e.g. Gtk::ACCEL_VISIBLE.
554 void add_accelerator(const Glib::ustring& accel_signal, const Glib::RefPtr<AccelGroup>& accel_group,
555 guint accel_key, Gdk::ModifierType accel_mods, AccelFlags accel_flags);
558 /** Removes an accelerator from @a widget , previously installed with
560 * @param accel_group Accel group for this widget.
561 * @param accel_key GDK keyval of the accelerator.
562 * @param accel_mods Modifier key combination of the accelerator.
563 * @return Whether an accelerator was installed and could be removed.
565 bool remove_accelerator(const Glib::RefPtr<AccelGroup>& accel_group,
566 guint accel_key, Gdk::ModifierType accel_mods);
568 /** Given an accelerator group, @a accel_group , and an accelerator path,
569 * @a accel_path , sets up an accelerator in @a accel_group so whenever the
570 * key binding that is defined for @a accel_path is pressed, @a widget
571 * will be activated. This removes any accelerators (for any
572 * accelerator group) installed by previous calls to
573 * set_accel_path(). Associating accelerators with
574 * paths allows them to be modified by the user and the modifications
575 * to be saved for future use. (See gtk_accel_map_save().)
577 * This function is a low level function that would most likely
578 * be used by a menu creation system like Gtk::ItemFactory. If you
579 * use Gtk::ItemFactory, setting up accelerator paths will be done
582 * Even when you you aren't using Gtk::ItemFactory, if you only want to
583 * set up accelerators on menu items Gtk::MenuItem::set_accel_path()
584 * provides a somewhat more convenient interface.
585 * @param accel_path Path used to look up the the accelerator.
586 * @param accel_group A Gtk::AccelGroup.
588 void set_accel_path(const Glib::ustring& accel_path,
589 const Glib::RefPtr<AccelGroup>& accel_group);
591 //GList* gtk_widget_list_accel_closures();
593 //TODO: Or maybe it is useless: gboolean gtk_widget_can_activate_accel(GtkWidget *widget, guint signal_id)
596 bool mnemonic_activate(bool group_cycling);
600 /** Rarely-used function. This function is used to emit
601 * the event signals on a widget (those signals should never
602 * be emitted without using this function to do so).
603 * If you want to synthesize an event though, don't use this function;
604 * instead, use gtk_main_do_event() so the event will behave as if
605 * it were in the event queue. Don't synthesize expose events; instead,
606 * use gdk_window_invalidate_rect() to invalidate a region of the
608 * @param event A Gdk::Event.
609 * @return Return from the event signal emission (<tt>true</tt> if the event was handled).
611 bool event(GdkEvent* event);
613 /** Very rarely-used function. This function is used to emit
614 * an expose event signals on a widget. This function is not
615 * normally used directly. The only time it is used is when
616 * propagating an expose event to a child NO_WINDOW widget, and
617 * that is normally done using Gtk::Container::propagate_expose().
619 * If you want to force an area of a window to be redrawn,
620 * use gdk_window_invalidate_rect() or gdk_window_invalidate_region().
621 * To cause the redraw to be done immediately, follow that call
622 * with a call to gdk_window_process_updates().
623 * @param event A expose Gdk::Event.
624 * @return Return from the event signal emission (<tt>true</tt> if the event was handled).
626 int send_expose(GdkEvent* event);
628 /** For widgets that can be "activated" (buttons, menu items, etc.)
629 * this function activates them. Activation is what happens when you
630 * press Enter on a widget during key navigation. If @a widget isn't
631 * activatable, the function returns <tt>false</tt>.
632 * @return <tt>true</tt> if the widget was activatable.
637 /** Moves a widget from one Gtk::Container to another, handling reference
638 * count issues to avoid destroying the widget.
639 * @param new_parent A Gtk::Container to move the widget into.
641 void reparent(Widget & new_parent);
643 bool intersect(const Gdk::Rectangle& area) const;
645 /** Computes the intersection of a @a widget 's area and @a area , storing
646 * the intersection in @a intersection , and returns <tt>true</tt> if there was
647 * an intersection. @a intersection may be <tt>0</tt> if you're only
648 * interested in whether there was an intersection.
649 * @param area A rectangle.
650 * @param intersection Rectangle to store intersection of @a widget and @a area .
651 * @return <tt>true</tt> if there was an intersection.
653 bool intersect(const Gdk::Rectangle& area, Gdk::Rectangle& intersection) const;
656 /** Computes the intersection of a @a widget 's area and @a region , returning
657 * the intersection. The result may be empty, use gdk_region_empty() to
659 * @param region A Gdk::Region, in the same coordinate system as
660 * @a widget ->allocation. That is, relative to @a widget ->window
661 * for NO_WINDOW widgets; relative to the parent window
662 * of @a widget ->window for widgets with their own window.
663 * @return A newly allocated region holding the intersection of @a widget
664 * and @a region . The coordinates of the return value are
665 * relative to @a widget ->window for NO_WINDOW widgets, and
666 * relative to the parent window of @a widget ->window for
667 * widgets with their own window.
669 Gdk::Region region_intersect(const Gdk::Region& region) const;
672 /** Stops emission of "child-notify" signals on @a widget . The signals are
673 * queued until thaw_child_notify() is called on @a widget .
675 * This is the analogue of Glib::object_freeze_notify() for child properties.
677 void freeze_child_notify();
679 /** Emits a "child-notify" signal for the
680 * child property @a child_property
683 * This is the analogue of Glib::object_notify() for child properties.
684 * @param child_property The name of a child property installed on the
685 * class of @a widget <!-- -->'s parent.
687 void child_notify(const Glib::ustring& child_property);
689 /** Reverts the effect of a previous call to freeze_child_notify().
690 * This causes all queued "child-notify" signals on @a widget to be emitted.
692 void thaw_child_notify();
695 /** Determines if the widget is the focus widget within its
696 * toplevel. (This does not mean that the HAS_FOCUS flag is
697 * necessarily set; HAS_FOCUS will only be set if the
698 * toplevel widget additionally has the global input focus.)
699 * @return <tt>true</tt> if the widget is the focus widget.
701 bool is_focus() const;
703 /** Causes @a widget to have the keyboard focus for the Gtk::Window it's
704 * inside. @a widget must be a focusable widget, such as a Gtk::Entry;
705 * something like Gtk::Frame won't work. (More precisely, it must have the
706 * Gtk::CAN_FOCUS flag set.)
710 /** Causes @a widget to become the default widget. @a widget must have the
711 * Gtk::CAN_DEFAULT flag set; typically you have to set this flag
712 * yourself by calling <tt>GTK_WIDGET_SET_FLAGS ( @a widget ,
713 * GTK_CAN_DEFAULT)</tt>. The default widget is activated when the user
714 * presses Enter in a window. Default widgets must be activatable,
715 * that is, activate() should affect them.
719 /** Block events to everything else than this widget and its children. This
720 * way you can get modal behaviour (usually not recommended). One practical
721 * example could be when implementing a key-binding widget that needs
722 * exclusive access to the key combination that the user presses next.
724 * Calls to add_modal_grab should be paired with calls to remove_modal_grab.
726 void add_modal_grab();
728 /** Remove the modal grab of the widget in case it was previously grabbed.
730 void remove_modal_grab();
732 /** Retrieve the widget which is currently grabbing all events.
734 static Widget* get_current_modal_grab();
737 /** Widgets can be named, which allows you to refer to them from a
738 * gtkrc file. You can apply a style to widgets with a particular name
739 * in the gtkrc file. See the documentation for gtkrc files (on the
740 * same page as the docs for Gtk::RcStyle).
742 * Note that widget names are separated by periods in paths (see
743 * path()), so names with embedded periods may cause confusion.
744 * @param name Name for the widget.
746 void set_name(const Glib::ustring& name);
749 /** Retrieves the name of a widget. See set_name() for the
750 * significance of widget names.
751 * @return Name of the widget. This string is owned by GTK+ and
752 * should not be modified or freed.
754 Glib::ustring get_name() const;
757 /** This function is for use in widget implementations. Sets the state
758 * of a widget (insensitive, prelighted, etc.) Usually you should set
759 * the state using wrapper functions such as set_sensitive().
760 * @param state New state for @a widget .
762 void set_state(Gtk::StateType state);
764 /** Sets the sensitivity of a widget. A widget is sensitive if the user
765 * can interact with it. Insensitive widgets are "grayed out" and the
766 * user can't interact with them. Insensitive widgets are known as
767 * "inactive", "disabled", or "ghosted" in some other toolkits.
768 * @param sensitive <tt>true</tt> to make the widget sensitive.
770 void set_sensitive(bool sensitive = true);
772 void set_app_paintable(bool app_paintable = true);
774 /** Widgets are double buffered by default; you can use this function
775 * to turn off the buffering. "Double buffered" simply means that
776 * gdk_window_begin_paint_region() and gdk_window_end_paint() are called
777 * automatically around expose events sent to the
778 * widget. gdk_window_begin_paint() diverts all drawing to a widget's
779 * window to an offscreen buffer, and gdk_window_end_paint() draws the
780 * buffer to the screen. The result is that users see the window
781 * update in one smooth step, and don't see individual graphics
782 * primitives being rendered.
784 * In very simple terms, double buffered widgets don't flicker,
785 * so you would only use this function to turn off double buffering
786 * if you had special needs and really knew what you were doing.
787 * @param double_buffered <tt>true</tt> to double-buffer a widget.
789 void set_double_buffered(bool double_buffered = true);
792 /** Sets whether a when a widgets size allocation changes, the entire
793 * widget is queued for drawing. By default, this setting is <tt>true</tt> and
794 * the entire widget is redrawn on every size change. If your widget
795 * leaves the upper left unchanged when made bigger, turning this
796 * setting on will improve performance.
798 * Note that for NO_WINDOW widgets setting this flag to <tt>false</tt> turns
799 * off all allocation on resizing: the widget will not even redraw if
800 * its position changes; this is to allow containers that don't draw
801 * anything to avoid excess invalidations. If you set this flag on a
802 * NO_WINDOW widget that <em>does</em> draw on @a widget ->window,
803 * you are responsible for invalidating both the old and new allocation
804 * of the widget when the widget is moved and responsible for invalidating
805 * regions newly when the widget increases size.
806 * @param redraw_on_allocate If <tt>true</tt>, the entire widget will be redrawn
807 * when it is allocated to a new size. Otherwise, only the
808 * new portion of the widget will be redrawn.
810 void set_redraw_on_allocate(bool redraw_on_allocate = true);
813 /** Sets whether @a widget should be mapped along with its when its parent
814 * is mapped and @a widget has been shown with show().
816 * The child visibility can be set for widget before it is added to
817 * a container with set_parent(), to avoid mapping
818 * children unnecessary before immediately unmapping them. However
819 * it will be reset to its default state of <tt>true</tt> when the widget
820 * is removed from a container.
822 * Note that changing the child visibility of a widget does not
823 * queue a resize on the widget. Most of the time, the size of
824 * a widget is computed from all visible children, whether or
825 * not they are mapped. If this is not the case, the container
826 * can queue a resize itself.
828 * This function is only useful for container implementations and
829 * never should be called by an application.
830 * @param is_visible If <tt>true</tt>, @a widget should be mapped along with its parent.
832 void set_child_visible(bool is_visible = true);
834 /** Gets the value set with set_child_visible().
835 * If you feel a need to use this function, your code probably
836 * needs reorganization.
838 * This function is only useful for container implementations and
839 * never should be called by an application.
840 * @return <tt>true</tt> if the widget is mapped with the parent.
842 bool get_child_visible() const;
845 /** Returns the parent container of @a widget .
846 * @return The parent container of @a widget , or <tt>0</tt>.
848 Container* get_parent();
850 /** Returns the parent container of @a widget .
851 * @return The parent container of @a widget , or <tt>0</tt>.
853 const Container* get_parent() const;
856 /** Gets @a widget 's parent window.
857 * @return The parent window of @a widget .
859 Glib::RefPtr<Gdk::Window> get_parent_window();
861 /** Gets @a widget 's parent window.
862 * @return The parent window of @a widget .
864 Glib::RefPtr<const Gdk::Window> get_parent_window() const;
866 /** Sets a non default parent window for @a widget .
867 * @param parent_window The new parent window.
869 void set_parent_window(const Glib::RefPtr<const Gdk::Window>& parent_window);
872 /** This function is used by custom widget implementations; if you're
873 * writing an app, you'd use grab_focus() to move the focus
874 * to a particular widget, and Gtk::Container::set_focus_chain() to
875 * change the focus tab order. So you may want to investigate those
878 * child_focus() is called by containers as the user moves
879 * around the window using keyboard shortcuts. @a direction indicates
880 * what kind of motion is taking place (up, down, left, right, tab
881 * forward, tab backward). child_focus() invokes the
882 * "focus" signal on Gtk::Widget; widgets override the default handler
883 * for this signal in order to implement appropriate focus behavior.
885 * The "focus" default handler for a widget should return <tt>true</tt> if
886 * moving in @a direction left the focus on a focusable location inside
887 * that widget, and <tt>false</tt> if moving in @a direction moved the focus
888 * outside the widget. If returning <tt>true</tt>, widgets normally
889 * call grab_focus() to place the focus accordingly;
890 * if returning <tt>false</tt>, they don't modify the current focus location.
892 * This function replaces gtk_container_focus() from GTK+ 1.2. It was
893 * necessary to check that the child was visible, sensitive, and
894 * focusable before calling
895 * gtk_container_focus(). child_focus() returns <tt>false</tt> if
896 * the widget is not currently in a focusable state, so there's no
897 * need for those checks.
898 * @param direction Direction of focus movement.
899 * @return <tt>true</tt> if focus ended up inside @a widget .
901 bool child_focus(DirectionType direction);
904 /** Sets the minimum size of a widget; that is, the widget's size
905 * request will be @a width by @a height . You can use this function to
906 * force a widget to be either larger or smaller than it normally
909 * In most cases, Gtk::Window::set_default_size() is a better choice for
910 * toplevel windows than this function; setting the default size will
911 * still allow users to shrink the window. Setting the size request
912 * will force them to leave the window at least as large as the size
913 * request. When dealing with window sizes,
914 * Gtk::Window::set_geometry_hints() can be a useful function as well.
916 * Note the inherent danger of setting any fixed size - themes,
917 * translations into other languages, different fonts, and user action
918 * can all change the appropriate size for a given widget. So, it's
919 * basically impossible to hardcode a size that will always be
922 * The size request of a widget is the smallest size a widget can
923 * accept while still functioning well and drawing itself correctly.
924 * However in some strange cases a widget may be allocated less than
925 * its requested size, and in many cases a widget may be allocated more
926 * space than it requested.
928 * If the size request in a given direction is -1 (unset), then
929 * the "natural" size request of the widget will be used instead.
931 * Widgets can't actually be allocated a size less than 1 by 1, but
932 * you can pass 0,0 to this function to mean "as small as possible."
933 * @param width Width @a widget should request, or -1 to unset.
934 * @param height Height @a widget should request, or -1 to unset.
936 void set_size_request(int width = -1, int height = -1);
938 /** Gets the size request that was explicitly set for the widget using
939 * set_size_request(). A value of -1 stored in @a width or
940 * @a height indicates that that dimension has not been set explicitly
941 * and the natural requisition of the widget will be used intead. See
942 * set_size_request(). To get the size a widget will
943 * actually use, call size_request() instead of
945 * @param width Return location for width, or <tt>0</tt>.
946 * @param height Return location for height, or <tt>0</tt>.
948 void get_size_request(int& width, int& height) const;
951 /** Sets the event mask (see Gdk::EventMask) for a widget. The event
952 * mask determines which events a widget will receive. Keep in mind
953 * that different widgets have different default event masks, and by
954 * changing the event mask you may disrupt a widget's functionality,
955 * so be careful. This function must be called while a widget is
956 * unrealized. Consider add_events() for widgets that are
957 * already realized, or if you want to preserve the existing event
958 * mask. This function can't be used with Gtk::NO_WINDOW widgets;
959 * to get events on those widgets, place them inside a Gtk::EventBox
960 * and receive events on the event box.
961 * @param events Event mask.
963 void set_events(Gdk::EventMask events);
965 /** Adds the events in the bitfield @a events to the event mask for
966 * @a widget . See set_events() for details.
967 * @param events An event mask, see Gdk::EventMask.
969 void add_events(Gdk::EventMask events);
971 /** Sets the extension events mask to @a mode . See Gdk::ExtensionMode
972 * and gdk_input_set_extension_events().
973 * @param mode Bitfield of extension events to receive.
975 void set_extension_events(Gdk::ExtensionMode mode);
978 /** Retrieves the extension events the widget will receive; see
979 * gdk_input_set_extension_events().
980 * @return Extension events for @a widget .
982 Gdk::ExtensionMode get_extension_events() const;
985 /** This function returns the topmost widget in the container hierarchy
986 * @a widget is a part of. If @a widget has no parent widgets, it will be
987 * returned as the topmost widget. No reference will be added to the
988 * returned widget; it should not be unreferenced.
990 * Note the difference in behavior vs. get_ancestor();
991 * <tt>gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)</tt>
993 * <tt>0</tt> if @a widget wasn't inside a toplevel window, and if the
994 * window was inside a Gtk::Window-derived widget which was in turn
995 * inside the toplevel Gtk::Window. While the second case may
996 * seem unlikely, it actually happens when a Gtk::Plug is embedded
997 * inside a Gtk::Socket within the same application.
999 * To reliably find the toplevel Gtk::Window, use
1000 * get_toplevel() and check if the T::OPLEVEL flags
1001 * is set on the result.
1003 * GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
1004 * if (GTK_WIDGET_TOPLEVEL (toplevel))
1006 * [ Perform action on toplevel. ]
1009 * @return The topmost ancestor of @a widget , or @a widget itself if there's no ancestor.
1011 Container* get_toplevel();
1013 /** This function returns the topmost widget in the container hierarchy
1014 * @a widget is a part of. If @a widget has no parent widgets, it will be
1015 * returned as the topmost widget. No reference will be added to the
1016 * returned widget; it should not be unreferenced.
1018 * Note the difference in behavior vs. get_ancestor();
1019 * <tt>gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)</tt>
1021 * <tt>0</tt> if @a widget wasn't inside a toplevel window, and if the
1022 * window was inside a Gtk::Window-derived widget which was in turn
1023 * inside the toplevel Gtk::Window. While the second case may
1024 * seem unlikely, it actually happens when a Gtk::Plug is embedded
1025 * inside a Gtk::Socket within the same application.
1027 * To reliably find the toplevel Gtk::Window, use
1028 * get_toplevel() and check if the T::OPLEVEL flags
1029 * is set on the result.
1031 * GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
1032 * if (GTK_WIDGET_TOPLEVEL (toplevel))
1034 * [ Perform action on toplevel. ]
1037 * @return The topmost ancestor of @a widget , or @a widget itself if there's no ancestor.
1039 const Container* get_toplevel() const;
1042 /** Gets the first ancestor of @a widget with type @a widget_type . For example,
1043 * <tt>gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)</tt> gets the
1044 * first Gtk::Box that's
1045 * an ancestor of @a widget . No reference will be added to the returned widget;
1046 * it should not be unreferenced. See note about checking for a toplevel
1047 * Gtk::Window in the docs for get_toplevel().
1049 * Note that unlike is_ancestor(), get_ancestor()
1050 * considers @a widget to be an ancestor of itself.
1051 * @param widget_type Ancestor type.
1052 * @return The ancestor widget, or <tt>0</tt> if not found.
1054 Widget* get_ancestor(GType widget_type);
1056 /** Gets the first ancestor of @a widget with type @a widget_type . For example,
1057 * <tt>gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)</tt> gets the
1058 * first Gtk::Box that's
1059 * an ancestor of @a widget . No reference will be added to the returned widget;
1060 * it should not be unreferenced. See note about checking for a toplevel
1061 * Gtk::Window in the docs for get_toplevel().
1063 * Note that unlike is_ancestor(), get_ancestor()
1064 * considers @a widget to be an ancestor of itself.
1065 * @param widget_type Ancestor type.
1066 * @return The ancestor widget, or <tt>0</tt> if not found.
1068 const Widget* get_ancestor(GType widget_type) const;
1071 /** Gets the colormap that will be used to render @a widget . No reference will
1072 * be added to the returned colormap; it should not be unreferenced.
1073 * @return The colormap used by @a widget .
1075 Glib::RefPtr<Gdk::Colormap> get_colormap();
1078 /** Gets the visual that will be used to render @a widget .
1079 * @return The visual for @a widget .
1081 Glib::RefPtr<Gdk::Visual> get_visual();
1084 /** Get the Gdk::Screen from the toplevel window associated with
1085 * this widget. This function can only be called after the widget
1086 * has been added to a widget hierarchy with a Gtk::Window
1089 * In general, you should only create screen specific
1090 * resources when a widget has been realized, and you should
1091 * free those resources when the widget is unrealized.
1092 * @return The Gdk::Screen for the toplevel for this widget.
1096 Glib::RefPtr<Gdk::Screen> get_screen();
1098 /** Get the Gdk::Screen from the toplevel window associated with
1099 * this widget. This function can only be called after the widget
1100 * has been added to a widget hierarchy with a Gtk::Window
1103 * In general, you should only create screen specific
1104 * resources when a widget has been realized, and you should
1105 * free those resources when the widget is unrealized.
1106 * @return The Gdk::Screen for the toplevel for this widget.
1110 Glib::RefPtr<const Gdk::Screen> get_screen() const;
1113 /** Checks whether there is a Gdk::Screen is associated with
1114 * this widget. All toplevel widgets have an associated
1115 * screen, and all widgets added into a heirarchy with a toplevel
1116 * window at the top.
1117 * @return <tt>true</tt> if there is a Gdk::Screen associcated
1122 bool has_screen() const;
1125 /** Get the Gdk::Display for the toplevel window associated with
1126 * this widget. This function can only be called after the widget
1127 * has been added to a widget hierarchy with a Gtk::Window at the top.
1129 * In general, you should only create display specific
1130 * resources when a widget has been realized, and you should
1131 * free those resources when the widget is unrealized.
1132 * @return The Gdk::Display for the toplevel for this widget.
1136 Glib::RefPtr<Gdk::Display> get_display();
1138 /** Get the Gdk::Display for the toplevel window associated with
1139 * this widget. This function can only be called after the widget
1140 * has been added to a widget hierarchy with a Gtk::Window at the top.
1142 * In general, you should only create display specific
1143 * resources when a widget has been realized, and you should
1144 * free those resources when the widget is unrealized.
1145 * @return The Gdk::Display for the toplevel for this widget.
1149 Glib::RefPtr<const Gdk::Display> get_display() const;
1152 /** Get the root window where this widget is located. This function can
1153 * only be called after the widget has been added to a widget
1154 * heirarchy with Gtk::Window at the top.
1156 * The root window is useful for such purposes as creating a popup
1157 * Gdk::Window associated with the window. In general, you should only
1158 * create display specific resources when a widget has been realized,
1159 * and you should free those resources when the widget is unrealized.
1160 * @return The Gdk::Window root window for the toplevel for this widget.
1164 Glib::RefPtr<Gdk::Window> get_root_window();
1166 /** Get the root window where this widget is located. This function can
1167 * only be called after the widget has been added to a widget
1168 * heirarchy with Gtk::Window at the top.
1170 * The root window is useful for such purposes as creating a popup
1171 * Gdk::Window associated with the window. In general, you should only
1172 * create display specific resources when a widget has been realized,
1173 * and you should free those resources when the widget is unrealized.
1174 * @return The Gdk::Window root window for the toplevel for this widget.
1178 Glib::RefPtr<const Gdk::Window> get_root_window() const;
1181 /** Gets the settings object holding the settings (global property
1182 * settings, RC file information, etc) used for this widget.
1184 * Note that this function can only be called when the Gtk::Widget
1185 * is attached to a toplevel, since the settings object is specific
1186 * to a particular Gdk::Screen.
1187 * @return The relevant Gtk::Settings object.
1189 Glib::RefPtr<Settings> get_settings();
1192 /** Returns the clipboard object for the given selection to
1193 * be used with @a widget . @a widget must have a Gdk::Display
1194 * associated with it, so must be attached to a toplevel
1196 * @param selection A Gdk::Atom which identifies the clipboard
1197 * to use. Gdk::SELECTION_CLIPBOARD gives the
1198 * default clipboard. Another common value
1199 * is Gdk::SELECTION_PRIMARY, which gives
1200 * the primary X selection.
1201 * @return The appropriate clipboard object. If no
1202 * clipboard already exists, a new one will
1203 * be created. Once a clipboard object has
1204 * been created, it is persistent for all time.
1208 Glib::RefPtr<Clipboard> get_clipboard(const Glib::ustring& selection);
1210 /** Returns the clipboard object for the given selection to
1211 * be used with @a widget . @a widget must have a Gdk::Display
1212 * associated with it, so must be attached to a toplevel
1214 * @param selection A Gdk::Atom which identifies the clipboard
1215 * to use. Gdk::SELECTION_CLIPBOARD gives the
1216 * default clipboard. Another common value
1217 * is Gdk::SELECTION_PRIMARY, which gives
1218 * the primary X selection.
1219 * @return The appropriate clipboard object. If no
1220 * clipboard already exists, a new one will
1221 * be created. Once a clipboard object has
1222 * been created, it is persistent for all time.
1226 Glib::RefPtr<const Clipboard> get_clipboard(const Glib::ustring& selection) const;
1228 //TODO: This probably needs a special conversion to do an extra ref (take_copy=true) for the returned instance:
1230 Glib::RefPtr<Atk::Object> get_accessible();
1233 /** Sets the colormap for the widget to the given value. Widget must not
1234 * have been previously realized. This probably should only be used
1235 * from an <tt>init()</tt> function (i.e. from the constructor
1237 * @param colormap A colormap.
1239 void set_colormap(const Glib::RefPtr<const Gdk::Colormap> &colormap);
1241 /** Returns the event mask for the widget (a bitfield containing flags
1242 * from the Gdk::EventMask enumeration). These are the events that the widget
1244 * @return Event mask for @a widget .
1246 Gdk::EventMask get_events() const;
1248 /** Obtains the location of the mouse pointer in widget coordinates.
1249 * Widget coordinates are a bit odd; for historical reasons, they are
1250 * defined as @a widget ->window coordinates for widgets that are not
1251 * Gtk::NO_WINDOW widgets, and are relative to @a widget ->allocation.x,
1252 * @a widget ->allocation.y for widgets that are Gtk::NO_WINDOW widgets.
1253 * @param x Return location for the X coordinate, or <tt>0</tt>.
1254 * @param y Return location for the Y coordinate, or <tt>0</tt>.
1256 void get_pointer(int &x, int &y) const;
1258 /** Determines whether @a widget is somewhere inside @a ancestor , possibly with
1259 * intermediate containers.
1260 * @param ancestor Another Gtk::Widget.
1261 * @return <tt>true</tt> if @a ancestor contains @a widget as a child, grandchild, great grandchild, etc.
1263 bool is_ancestor(Widget &ancestor) const;
1266 /** Translate coordinates relative to @a src_widget 's allocation to coordinates
1267 * relative to @a dest_widget 's allocations. In order to perform this
1268 * operation, both widgets must be realized, and must share a common
1270 * @param dest_widget A Gtk::Widget.
1271 * @param src_x X position relative to @a src_widget .
1272 * @param src_y Y position relative to @a src_widget .
1273 * @param dest_x Location to store X position relative to @a dest_widget .
1274 * @param dest_y Location to store Y position relative to @a dest_widget .
1275 * @return <tt>false</tt> if either widget was not realized, or there
1276 * was no common ancestor. In this case, nothing is stored in
1277 * * @a dest_x and * @a dest_y . Otherwise <tt>true</tt>.
1279 bool translate_coordinates(Widget& dest_widget,
1280 int src_x, int src_y,
1281 int& dest_x, int& dest_y);
1285 /** Sets the Gtk::Style for a widget ( @a widget ->style). You probably don't
1286 * want to use this function; it interacts badly with themes, because
1287 * themes work by replacing the Gtk::Style. Instead, use
1289 * @param style A Gtk::Style.
1291 void set_style(const Glib::RefPtr<Style>& style);
1295 /** Ensures that @a widget has a style ( @a widget ->style). Not a very useful
1296 * function; most of the time, if you want the style, the widget is
1297 * realized, and realized widgets are guaranteed to have a style
1300 void ensure_style();
1302 /** Simply an accessor function that returns @a widget ->style.
1303 * @return The widget's Gtk::Style.
1305 Glib::RefPtr<Style> get_style();
1307 /** Simply an accessor function that returns @a widget ->style.
1308 * @return The widget's Gtk::Style.
1310 Glib::RefPtr<const Style> get_style() const;
1312 /** Modifies style values on the widget. Modifications made using this
1313 * technique take precedence over style values set via an RC file,
1314 * however, they will be overriden if a style is explicitely set on
1315 * the widget using set_style(). The Gtk::RcStyle structure
1316 * is designed so each field can either be set or unset, so it is
1317 * possible, using this function, to modify some style values and
1318 * leave the others unchanged.
1320 * Note that modifications made with this function are not cumulative
1321 * with previous calls to modify_style() or with such
1322 * functions as modify_fg(). If you wish to retain
1323 * previous values, you must first call get_modifier_style(),
1324 * make your modifications to the returned style, then call
1325 * modify_style() with that style. On the other hand,
1326 * if you first call modify_style(), subsequent calls
1327 * to such functions modify_fg() will have a cumulative
1328 * effect with the initial modifications.
1329 * @param style The Gtk::RcStyle holding the style modifications.
1331 void modify_style(const Glib::RefPtr<RcStyle>& style);
1333 /** Returns the current modifier style for the widget. (As set by
1334 * modify_style().) If no style has previously set, a new
1335 * Gtk::RcStyle will be created with all values unset, and set as the
1336 * modifier style for the widget. If you make changes to this rc
1337 * style, you must call modify_style(), passing in the
1338 * returned rc style, to make sure that your changes take effect.
1340 * Caution: passing the style back to modify_style() will
1341 * normally end up destroying it, because modify_style() copies
1342 * the passed-in style and sets the copy as the new modifier style,
1343 * thus dropping any reference to the old modifier style. Add a reference
1344 * to the modifier style if you want to keep it alive.
1345 * @return The modifier style for the widget. This rc style is
1346 * owned by the widget. If you want to keep a pointer to value this
1347 * around, you must add a refcount using Gtk::RcStyle::ref().
1349 Glib::RefPtr<RcStyle> get_modifier_style();
1351 /** Returns the current modifier style for the widget. (As set by
1352 * modify_style().) If no style has previously set, a new
1353 * Gtk::RcStyle will be created with all values unset, and set as the
1354 * modifier style for the widget. If you make changes to this rc
1355 * style, you must call modify_style(), passing in the
1356 * returned rc style, to make sure that your changes take effect.
1358 * Caution: passing the style back to modify_style() will
1359 * normally end up destroying it, because modify_style() copies
1360 * the passed-in style and sets the copy as the new modifier style,
1361 * thus dropping any reference to the old modifier style. Add a reference
1362 * to the modifier style if you want to keep it alive.
1363 * @return The modifier style for the widget. This rc style is
1364 * owned by the widget. If you want to keep a pointer to value this
1365 * around, you must add a refcount using Gtk::RcStyle::ref().
1367 Glib::RefPtr<const RcStyle> get_modifier_style() const;
1369 // we need custom documentation because modify_* can take a NULL pointer
1370 // (which we wrap with unset_*)
1371 /** Sets the foreground color for a widget in a particular state.
1372 * All other style values are left untouched. See also modify_style() and
1375 * @param state The state for which to set the foreground color.
1376 * @param color The color to assign (does not need to be allocated).
1379 /** Sets the foreground color for a widget in a particular state. All
1380 * other style values are left untouched. See also
1382 * @param state The state for which to set the foreground color.
1383 * @param color The color to assign (does not need to be allocated).
1385 void modify_fg(StateType state, const Gdk::Color& color);
1388 /** Sets the background color for a widget in a particular state.
1389 * All other style values are left untouched. See also modify_style() and
1392 * @param state The state for which to set the background color.
1393 * @param color The color to assign (does not need to be allocated).
1396 /** Sets the background color for a widget in a particular state. All
1397 * other style values are left untouched. See also
1399 * @param state The state for which to set the background color.
1400 * @param color The color to assign (does not need to be allocated).
1402 void modify_bg(StateType state, const Gdk::Color& color);
1404 // TODO: Document this, and perhaps add unset_bg_pixmap
1405 void modify_bg_pixmap(StateType state, const Glib::ustring& pixmap_name);
1407 /** Sets the text color for a widget in a particular state.
1408 * All other style values are left untouched. The text color is the
1409 * foreground color used along with the base color (see modify_base() ) for
1410 * widgets such as Gtk::Entry and Gtk::TextView. See also modify_style() and
1413 * @param state The state for which to set the text color.
1414 * @param color The color to assign (does not need to be allocated).
1417 /** Sets the text color for a widget in a particular state. All other
1418 * style values are left untouched. The text color is the foreground
1419 * color used along with the base color (see modify_base())
1420 * for widgets such as Gtk::Entry and Gtk::TextView. See also
1422 * @param state The state for which to set the text color.
1423 * @param color The color to assign (does not need to be allocated).
1425 void modify_text(StateType state, const Gdk::Color& color);
1427 /** Sets the base color for a widget in a particular state.
1428 * All other style values are left untouched. The base color is the
1429 * background color used along with the text color (see modify_text() ) for
1430 * widgets such as Gtk::Entry and Gtk::TextView. See also modify_style() and
1433 * @param state The state for which to set the text color.
1434 * @param color The color to assign (does not need to be allocated).
1437 /** Sets the base color for a widget in a particular state.
1438 * All other style values are left untouched. The base color
1439 * is the background color used along with the text color
1440 * (see modify_text()) for widgets such as Gtk::Entry
1441 * and Gtk::TextView. See also modify_style().
1442 * @param state The state for which to set the base color.
1443 * @param color The color to assign (does not need to be allocated).
1445 void modify_base(StateType state, const Gdk::Color& color);
1447 /** Sets the font to use for a widget.
1448 * All other style values are left untouched. See also modify_style() and
1452 /** Sets the font to use for a widget. All other style values are left
1453 * untouched. See also modify_style().
1454 * @param font_desc The font description to use.
1456 void modify_font(const Pango::FontDescription& font_desc);
1458 /** Undo the effect of previous calls to modify_fg() for a particular state.
1459 * All other style values are left untouched. See also modify_style().
1461 void unset_fg(StateType state);
1463 /** Undo the effect of previous calls to modify_bg() for a particular state.
1464 * All other style values are left untouched. See also modify_style().
1466 void unset_bg(StateType state);
1468 /** Undo the effect of previous calls to modify_text() for a particular state.
1469 * All other style values are left untouched. See also modify_style().
1471 void unset_text(StateType state);
1473 /** Undo the effect of previous calls to modify_base() for a particular state.
1474 * All other style values are left untouched. See also modify_style().
1476 void unset_base(StateType state);
1478 /** Undo the effect of previous calls to modify_font() for a particular state.
1479 * All other style values are left untouched. See also modify_style().
1483 //The parameter name is "the_property_name" to avoid a warning because there is a method with the "property_name" name.
1484 template <class PropertyType>
1485 void get_style_property(const Glib::ustring& the_property_name, PropertyType& value) const;
1488 /** Creates a new Pango::Context with the appropriate colormap,
1489 * font description, and base direction for drawing text for
1490 * this widget. See also get_pango_context().
1491 * @return The new Pango::Context.
1493 Glib::RefPtr<Pango::Context> create_pango_context();
1495 /** Gets a Pango::Context with the appropriate colormap, font description
1496 * and base direction for this widget. Unlike the context returned
1497 * by create_pango_context(), this context is owned by
1498 * the widget (it can be used until the screen for the widget changes
1499 * or the widget is removed from its toplevel), and will be updated to
1500 * match any changes to the widget's attributes.
1502 * If you create and keep a Pango::Layout using this context, you must
1503 * deal with changes to the context by calling pango_layout_context_changed()
1504 * on the layout in response to the ::style-set and ::direction-changed signals
1506 * @return The Pango::Context for the widget.
1508 Glib::RefPtr<Pango::Context> get_pango_context();
1510 /** Creates a new Pango::Layout with the appropriate colormap,
1511 * font description, and base direction for drawing text for
1514 * If you keep a Pango::Layout created in this way around, in order
1515 * notify the layout of changes to the base direction or font of this
1516 * widget, you must call pango_layout_context_changed() in response to
1517 * the ::style-set and ::direction-changed signals for the widget.
1518 * @param text Text to set on the layout (can be <tt>0</tt>).
1519 * @return The new Pango::Layout.
1521 Glib::RefPtr<Pango::Layout> create_pango_layout(const Glib::ustring& text);
1524 /** A convenience function that uses the theme engine and RC file
1525 * settings for @a widget to look up @a stock_id and render it to
1526 * a pixbuf. @a stock_id should be a stock icon ID such as
1527 * Gtk::STOCK_OPEN or Gtk::STOCK_OK. @a size should be a size
1528 * such as Gtk::ICON_SIZE_MENU. @a detail should be a string that
1529 * identifies the widget or code doing the rendering, so that
1530 * theme engines can special-case rendering for that widget or code.
1532 * The pixels in the returned Gdk::Pixbuf are shared with the rest of
1533 * the application and should not be modified. The pixbuf should be freed
1534 * after use with Glib::object_unref().
1535 * @param stock_id A stock ID.
1536 * @param size A stock size. A size of (GtkIconSize)-1 means render at
1537 * the size of the source and don't scale (if there are multiple
1538 * source sizes, GTK+ picks one of the available sizes).
1539 * @param detail Render detail to pass to theme engine.
1540 * @return A new pixbuf, or <tt>0</tt> if the stock ID wasn't known.
1542 Glib::RefPtr<Gdk::Pixbuf> render_icon(const StockID& stock_id, IconSize size, const Glib::ustring& detail = Glib::ustring());
1545 /** Sets a widgets composite name. The widget must be
1546 * a composite child of its parent; see push_composite_child().
1547 * @param name The name to set.
1549 void set_composite_name(const Glib::ustring& name);
1550 void unset_composite_name();
1552 /** Obtains the composite name of a widget.
1553 * @return The composite name of @a widget , or <tt>0</tt> if @a widget is not
1554 * a composite child. The string should not be freed when it is no
1557 Glib::ustring get_composite_name() const;
1560 void reset_rc_styles();
1563 // PUSH/POP - these are used to create widgets. Hidden arguments to override the defaults.
1565 /** Pushes @a cmap onto a global stack of colormaps; the topmost
1566 * colormap on the stack will be used to create all widgets.
1567 * Remove @a cmap with pop_colormap(). There's little
1568 * reason to use this function.
1569 * @param cmap A Gdk::Colormap.
1571 static void push_colormap(const Glib::RefPtr<const Gdk::Colormap>& cmap);
1573 /** Removes a colormap pushed with push_colormap().
1575 static void pop_colormap();
1578 /** Makes all newly-created widgets as composite children until
1579 * the corresponding pop_composite_child() call.
1581 * A composite child is a child that's an implementation detail of the
1582 * container it's inside and should not be visible to people using the
1583 * container. Composite children aren't treated differently by GTK (but
1584 * see Gtk::Container::foreach() vs. Gtk::Container::forall()), but e.g. GUI
1585 * builders might want to treat them in a different way.
1587 * Here is a simple example:
1589 * gtk_widget_push_composite_child (<!-- -->);
1590 * scrolled_window->hscrollbar = gtk_hscrollbar_new (hadjustment);
1591 * gtk_widget_set_composite_name (scrolled_window->hscrollbar, "hscrollbar");
1592 * gtk_widget_pop_composite_child (<!-- -->);
1593 * gtk_widget_set_parent (scrolled_window->hscrollbar,
1594 * GTK_WIDGET (scrolled_window));
1595 * g_object_ref (scrolled_window->hscrollbar);
1598 static void push_composite_child();
1600 /** Cancels the effect of a previous call to push_composite_child().
1602 static void pop_composite_child();
1608 /** Sets the default colormap to use when creating widgets.
1609 * push_colormap() is a better function to use if
1610 * you only want to affect a few widgets, rather than all widgets.
1611 * @param colormap A Gdk::Colormap.
1613 static void set_default_colormap(const Glib::RefPtr<const Gdk::Colormap>& colormap);
1615 /** Returns the default style used by all widgets initially.
1616 * @return The default style. This Gtk::Style object is owned by GTK+ and
1617 * should not be modified or freed.
1619 static Glib::RefPtr<Style> get_default_style();
1621 /** Obtains the default colormap used to create widgets.
1622 * @return Default widget colormap.
1624 static Glib::RefPtr<Gdk::Colormap> get_default_colormap();
1626 /** Obtains the visual of the default colormap. Not really useful;
1627 * used to be useful before gdk_colormap_get_visual() existed.
1628 * @return Visual of the default colormap.
1630 static Glib::RefPtr<Gdk::Visual> get_default_visual();
1633 /* Directionality of Text */
1636 /** Sets the reading direction on a particular widget. This direction
1637 * controls the primary direction for widgets containing text,
1638 * and also the direction in which the children of a container are
1639 * packed. The ability to set the direction is present in order
1640 * so that correct localization into languages with right-to-left
1641 * reading directions can be done. Generally, applications will
1642 * let the default reading direction present, except for containers
1643 * where the containers are arranged in an order that is explicitely
1644 * visual rather than logical (such as buttons for text justification).
1646 * If the direction is set to Gtk::TEXT_DIR_NONE, then the value
1647 * set by set_default_direction() will be used.
1648 * @param dir The new direction.
1650 void set_direction(TextDirection dir);
1652 /** Gets the reading direction for a particular widget. See
1654 * @return The reading direction for the widget.
1656 TextDirection get_direction();
1658 /** Sets the default reading direction for widgets where the
1659 * direction has not been explicitly set by set_direction().
1660 * @param dir The new default direction. This cannot be
1661 * Gtk::TEXT_DIR_NONE.
1663 static void set_default_direction(TextDirection dir);
1665 /** Obtains the current default reading direction. See
1666 * set_default_direction().
1667 * @return The current default direction.
1669 static TextDirection get_default_direction();
1674 /** Sets a shape for this widget's GDK window. This allows for
1675 * transparent windows etc., see gdk_window_shape_combine_mask()
1676 * for more information.
1677 * @param shape_mask Shape to be added.
1678 * @param offset_x X position of shape mask with respect to @a window .
1679 * @param offset_y Y position of shape mask with respect to @a window .
1681 void shape_combine_mask(const Glib::RefPtr<const Gdk::Bitmap>& shape_mask, int offset_x, int offset_y);
1682 void unset_shape_combine_mask();
1687 /** Recursively resets the shape on this widget and its descendants.
1689 void reset_shapes();
1692 /// Compute a widget's path of the form "GtkWindow.MyLabel"
1693 void path(Glib::ustring& path, Glib::ustring& path_reversed);
1694 void class_path(Glib::ustring& path, Glib::ustring& path_reversed);
1697 /** Returns a newly allocated list of the widgets, normally labels, for
1698 * which this widget is a the target of a mnemonic (see for example,
1699 * Gtk::Label::set_mnemonic_widget()).
1701 * The widgets in the list are not individually referenced. If you
1702 * want to iterate through the list and perform actions involving
1703 * callbacks that might destroy the widgets, you
1704 * <em>must</em> call <tt>g_list_foreach (result,
1705 * (GFunc)g_object_ref, <tt>0</tt>)</tt> first, and then unref all the
1706 * widgets afterwards.
1707 * @return The list of mnemonic labels; free this list
1708 * with Glib::list_free() when you are done with it.
1712 Glib::ListHandle<Widget*> list_mnemonic_labels();
1714 /** Returns a newly allocated list of the widgets, normally labels, for
1715 * which this widget is a the target of a mnemonic (see for example,
1716 * Gtk::Label::set_mnemonic_widget()).
1718 * The widgets in the list are not individually referenced. If you
1719 * want to iterate through the list and perform actions involving
1720 * callbacks that might destroy the widgets, you
1721 * <em>must</em> call <tt>g_list_foreach (result,
1722 * (GFunc)g_object_ref, <tt>0</tt>)</tt> first, and then unref all the
1723 * widgets afterwards.
1724 * @return The list of mnemonic labels; free this list
1725 * with Glib::list_free() when you are done with it.
1729 Glib::ListHandle<const Widget*> list_mnemonic_labels() const;
1731 /** Adds a widget to the list of mnemonic labels for
1732 * this widget. (See list_mnemonic_labels()). Note the
1733 * list of mnemonic labels for the widget is cleared when the
1734 * widget is destroyed, so the caller must make sure to update
1735 * it's internal state at this point as well, by using a connection
1736 * to the ::destroy signal or a weak notifier.
1739 * @param label A Gtk::Widget that acts as a mnemonic label for @a widget .
1741 void add_mnemonic_label(Widget& label);
1743 /** Removes a widget from the list of mnemonic labels for
1744 * this widget. (See list_mnemonic_labels()). The widget
1745 * must have previously been added to the list with
1746 * add_mnemonic_label().
1749 * @param label A Gtk::Widget that was previously set as a mnemnic label for
1750 * @a widget with add_mnemonic_label().
1752 void remove_mnemonic_label(Widget& label);
1755 //TODO: Should drag_get_data() be const?
1757 void drag_get_data(const Glib::RefPtr<Gdk::DragContext>& context, Glib::ustring& target, guint32 time);
1759 void drag_highlight();
1761 void drag_unhighlight();
1763 void drag_dest_set(DestDefaults flags = DestDefaults(0), Gdk::DragAction actions = Gdk::DragAction(0));
1764 void drag_dest_set(const ArrayHandle_TargetEntry& targets, DestDefaults flags = DEST_DEFAULT_ALL, Gdk::DragAction actions = Gdk::ACTION_COPY);
1767 void drag_dest_set_proxy(const Glib::RefPtr<Gdk::Window>& proxy_window, Gdk::DragProtocol protocol, bool use_coordinates);
1769 void drag_dest_unset();
1771 /** Looks for a match between @a context ->targets and the
1772 * @a dest_target_list , returning the first matching target, otherwise
1773 * returning Gdk::NONE. @a dest_target_list should usually be the return
1774 * value from gtk_drag_dest_get_target_list(), but some widgets may
1775 * have different valid targets for different parts of the widget; in
1776 * that case, they will have to implement a drag_motion handler that
1777 * passes the correct target list to this function.
1778 * @param context Drag context.
1779 * @param target_list List of droppable targets.
1780 * @return First target that the source offers and the dest can accept, or Gdk::NONE.
1782 Glib::ustring drag_dest_find_target(const Glib::RefPtr<Gdk::DragContext>& context, const Glib::RefPtr<TargetList>& target_list) const;
1783 Glib::ustring drag_dest_find_target(const Glib::RefPtr<Gdk::DragContext>& context) const;
1786 /** Returns the list of targets this widget can accept from
1788 * @return The Gtk::TargetList, or <tt>0</tt> if none.
1790 Glib::RefPtr<TargetList> drag_dest_get_target_list();
1792 /** Returns the list of targets this widget can accept from
1794 * @return The Gtk::TargetList, or <tt>0</tt> if none.
1796 Glib::RefPtr<const TargetList> drag_dest_get_target_list() const;
1798 /** Sets the target types that this widget can accept from drag-and-drop.
1799 * The widget must first be made into a drag destination with
1800 * gtk_drag_dest_set().
1801 * @param target_list List of droppable targets, or <tt>0</tt> for none.
1803 void drag_dest_set_target_list(const Glib::RefPtr<TargetList>& target_list);
1806 /** Add the text targets supported by Gtk::Selection to
1807 * the target list of the drag destination. The targets
1808 * are added with @a info = 0. If you need another value,
1809 * use gtk_target_list_add_text_targets() and
1810 * gtk_drag_dest_set_target_list().
1813 * @param widget A Gtk::Widget that's a drag destination.
1815 void drag_dest_add_text_targets();
1817 /** Add the image targets supported by Gtk::Selection to
1818 * the target list of the drag destination. The targets
1819 * are added with @a info = 0. If you need another value,
1820 * use gtk_target_list_add_image_targets() and
1821 * gtk_drag_dest_set_target_list().
1824 * @param widget A Gtk::Widget that's a drag destination.
1826 void drag_dest_add_image_targets();
1828 /** Add the URI targets supported by Gtk::Selection to
1829 * the target list of the drag destination. The targets
1830 * are added with @a info = 0. If you need another value,
1831 * use gtk_target_list_add_uri_targets() and
1832 * gtk_drag_dest_set_target_list().
1835 * @param widget A Gtk::Widget that's a drag destination.
1837 void drag_dest_add_uri_targets();
1839 void drag_source_set(const ArrayHandle_TargetEntry& targets, Gdk::ModifierType start_button_mask = Gdk::MODIFIER_MASK, Gdk::DragAction actions = Gdk::ACTION_COPY);
1842 void drag_source_unset();
1845 /** Sets the icon that will be used for drags from a particular widget
1846 * from a pixmap/mask. GTK+ retains references for the arguments, and
1847 * will release them when they are no longer needed.
1848 * Use gtk_drag_source_set_icon_pixbuf() instead.
1849 * @param colormap The colormap of the icon.
1850 * @param pixmap The image data for the icon.
1851 * @param mask The transparency mask for an image.
1853 void drag_source_set_icon(const Glib::RefPtr<Gdk::Colormap>& colormap, const Glib::RefPtr<Gdk::Pixmap>& pixmap, const Glib::RefPtr<Gdk::Bitmap>& mask);
1855 /** Sets the icon that will be used for drags from a particular widget
1856 * from a Gdk::Pixbuf. GTK+ retains a reference for @a pixbuf and will
1857 * release it when it is no longer needed.
1858 * @param pixbuf The Gdk::Pixbuf for the drag icon.
1860 void drag_source_set_icon(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);
1862 /** Sets the icon that will be used for drags from a particular source
1864 * @param stock_id The ID of the stock icon to use.
1866 void drag_source_set_icon(const StockID& stock_id);
1869 /** Add the text targets supported by Gtk::Selection to
1870 * the target list of the drag source. The targets
1871 * are added with @a info = 0. If you need another value,
1872 * use gtk_target_list_add_text_targets() and
1873 * gtk_drag_source_set_target_list().
1876 * @param widget A Gtk::Widget that's is a drag source.
1878 void drag_source_add_text_targets();
1880 /** Add the URI targets supported by Gtk::Selection to
1881 * the target list of the drag source. The targets
1882 * are added with @a info = 0. If you need another value,
1883 * use gtk_target_list_add_uri_targets() and
1884 * gtk_drag_source_set_target_list().
1887 * @param widget A Gtk::Widget that's is a drag source.
1889 void drag_source_add_uri_targets();
1891 /** Add the writable image targets supported by Gtk::Selection to
1892 * the target list of the drag source. The targets
1893 * are added with @a info = 0. If you need another value,
1894 * use gtk_target_list_add_image_targets() and
1895 * gtk_drag_source_set_target_list().
1898 * @param widget A Gtk::Widget that's is a drag source.
1900 void drag_source_add_image_targets();
1903 /** Initiates a drag on the source side. The function
1904 * only needs to be used when the application is
1905 * starting drags itself, and is not needed when
1906 * gtk_drag_source_set() is used.
1907 * @param targets The targets (data formats) in which the
1908 * source can provide the data.
1909 * @param actions A bitmask of the allowed drag actions for this drag.
1910 * @param button The button the user clicked to start the drag.
1911 * @param event The event that triggered the start of the drag.
1912 * @return The context for this drag.
1914 Glib::RefPtr<Gdk::DragContext> drag_begin(const Glib::RefPtr<TargetList>& targets, Gdk::DragAction actions, int button, GdkEvent* event);
1916 /** Checks to see if a mouse drag starting at ( @a start_x , @a start_y ) and ending
1917 * at ( @a current_x , @a current_y ) has passed the GTK+ drag threshold, and thus
1918 * should trigger the beginning of a drag-and-drop operation.
1919 * @param start_x X coordinate of start of drag.
1920 * @param start_y Y coordinate of start of drag.
1921 * @param current_x Current X coordinate.
1922 * @param current_y Current Y coordinate.
1923 * @return <tt>true</tt> if the drag threshold has been passed.
1925 bool drag_check_threshold(int start_x, int start_y, int current_x, int current_y);
1928 //These should be a method of Gdk::DragContext, but gdkmm can't depend on gtkmm.
1929 static Widget* drag_get_source_widget(const Glib::RefPtr<Gdk::DragContext>& context);
1930 void drag_set_as_icon(const Glib::RefPtr<Gdk::DragContext>& context, int hot_x, int hot_y);
1933 /** This function works like queue_resize(), except that the
1934 * widget is not invalidated.
1938 void queue_resize_no_redraw();
1940 /** Returns the current value of the "no_show_all" property, which determines
1941 * whether calls to show_all() and hide_all()
1942 * will affect this widget.
1943 * @return The current value of the "no_show_all" property.
1947 bool get_no_show_all() const;
1949 /** Sets the "no_show_all" property, which determines whether calls to
1950 * show_all() and hide_all() will affect this widget.
1952 * This is mostly for use in constructing widget hierarchies with externally
1953 * controlled visibility, see Gtk::UIManager.
1956 * @param no_show_all The new value for the "no_show_all" property.
1958 void set_no_show_all(bool no_show_all = true);
1960 //Used when implementing containers:
1962 /** This function is useful only when implementing subclasses of Gtk::Container.
1963 * Sets the container as the parent of @a widget , and takes care of
1964 * some details such as updating the state and style of the child
1965 * to reflect its new location. The opposite function is
1967 * @param parent Parent container.
1969 void set_parent(Widget& parent);
1971 /** This function is only for use in widget implementations.
1972 * Should be called by implementations of the remove method
1973 * on Gtk::Container, to dissociate a child from the container.
1977 void draw_insertion_cursor(Glib::RefPtr<Gdk::Drawable> drawable, const Gdk::Rectangle& area, const Gdk::Rectangle& location, bool is_primary, TextDirection direction, bool draw_arrow = true);
1982 //: Returns property {flags.toplevel}.
1983 bool is_toplevel() const;
1985 //: Returns property {flags.nowindow}.
1986 bool has_no_window() const;
1988 //: Returns property {flags.realized}.
1989 bool is_realized() const;
1991 //: Returns property {flags.mapped}.
1992 bool is_mapped() const;
1994 //: Returns property {flags.visible}.
1995 bool is_visible() const;
1997 //: Returns if the widget is ready to be drawn to.
1998 // Checks to see if the widget is both visible and mapped which
1999 // makes it possible to perform drawing commands on.
2000 bool is_drawable() const;
2002 //: Returns property {flags.sensitive}. You might want to check
2003 // is_sensitive instead.
2004 bool sensitive() const;
2006 bool parent_sensitive() const;
2007 bool is_sensitive() const;
2008 bool can_focus() const;
2009 bool has_focus() const;
2010 bool can_default() const;
2011 bool has_default() const;
2012 bool has_grab() const;
2013 bool rc_style() const;
2014 bool is_composite_child() const;
2015 bool app_paintable() const;
2016 bool receives_default() const;
2017 bool double_buffered() const;
2019 WidgetFlags get_flags() const;
2020 void set_flags(WidgetFlags flags);
2021 void unset_flags(WidgetFlags flags);
2023 int get_width() const;
2024 int get_height() const;
2026 Gtk::StateType get_state() const;
2027 Gtk::StateType get_saved_state() const;
2028 Requisition get_requisition() const;
2029 Allocation get_allocation() const;
2030 Glib::RefPtr<Gdk::Window> get_window();
2031 Glib::RefPtr<const Gdk::Window> get_window() const;
2034 Glib::SignalProxy0< void > signal_show();
2037 Glib::SignalProxy0< void > signal_hide();
2040 //: Emitted on mapping of a widget to the screen.
2041 //- See {flags.mapped}.
2044 Glib::SignalProxy0< void > signal_map();
2047 //- See {flags.mapped}.
2050 Glib::SignalProxy0< void > signal_unmap();
2053 //: Emitted on realization of a widget.
2054 //- See {flags.realized}. This is also responsible for
2055 //- setting {flags.realized} when it is done. Therefore,
2056 //- when overriding the impl method, you should call the
2057 //- default realize method.
2060 Glib::SignalProxy0< void > signal_realize();
2063 //- See {flags.realized}. This should not be called by the user.
2064 //__WRAP(meth|sig|impl,void unrealize_(),gtk_widget_unrealize,"unrealize")
2067 Glib::SignalProxy0< void > signal_unrealize();
2070 Glib::SignalProxy1< void,Requisition* > signal_size_request();
2073 Glib::SignalProxy1< void,Allocation& > signal_size_allocate();
2076 // Changed signals -- inform widget of internal changes.
2077 // We rename parent_set => parent_changed
2078 // and style_set => style_changed
2079 // to avoid confusion with set_parent and set_style.
2081 //: Informs objects that their state has changed.
2082 //- The old state is passed as the argument.
2085 Glib::SignalProxy1< void,Gtk::StateType > signal_state_changed();
2088 //: Informs objects that their parent changed.
2089 //- The widget passed is the former parent, which may be 0 if
2090 //- there was no parent. (was parent_set in GTK+)
2093 Glib::SignalProxy1< void,Widget* > signal_parent_changed();
2096 Glib::SignalProxy1< void,Widget* > signal_hierarchy_changed();
2099 //: Informs objects that their style has been changed.
2100 //- The former style is passed as the argument. (was style_set in gtk+)
2103 Glib::SignalProxy1< void,const Glib::RefPtr<Style>& > signal_style_changed();
2106 Glib::SignalProxy1< void,TextDirection > signal_direction_changed();
2109 Glib::SignalProxy1< void,bool > signal_grab_notify();
2112 Glib::SignalProxy1< void,GParamSpec* > signal_child_notify();
2115 //_WRAP_SIGNAL(void add_accelerator(guint, GtkAccelGroup*, guint accel_key, Gdk::ModifierType, AccelFlags), "add-accelerator")
2116 //_WRAP_SIGNAL(void remove_accelerator(GtkAccelGroup* accel_group, guint, Gdk::ModifierType), "remove-accelerator")
2119 Glib::SignalProxy1< bool,bool > signal_mnemonic_activate();
2122 Glib::SignalProxy0< void > signal_grab_focus();
2125 Glib::SignalProxy1< bool,DirectionType > signal_focus();
2128 Glib::SignalProxy1< bool,GdkEvent* > signal_event();
2131 Glib::SignalProxy1< void,GdkEvent* > signal_event_after();
2134 //: Event triggered by user pressing button.
2137 Glib::SignalProxy1< bool,GdkEventButton* > signal_button_press_event();
2140 //: Event triggered by user releasing button.
2143 Glib::SignalProxy1< bool,GdkEventButton* > signal_button_release_event();
2146 Glib::SignalProxy1< bool,GdkEventScroll* > signal_scroll_event();
2149 //: Event triggered by user moving pointer.
2152 Glib::SignalProxy1< bool,GdkEventMotion* > signal_motion_notify_event();
2155 //: Event triggered by window being closed.
2158 Glib::SignalProxy1< bool,GdkEventAny* > signal_delete_event();
2161 //: Event triggered by window requiring a refresh.
2162 //- Expose events cover a rectangular area that was covered
2163 //- or obscured by another window. That area is now exposed
2164 //- and thus is needs to be redrawn.
2166 //- If the application is not capable of redrawing sections
2167 //- it should watch the count field and only draw on the last
2168 //- even indicated. This is important for things such as
2169 //- Gtk::DrawingArea.
2172 Glib::SignalProxy1< bool,GdkEventExpose* > signal_expose_event();
2175 //: Event triggered by a key press will widget has focus.
2178 Glib::SignalProxy1< bool,GdkEventKey* > signal_key_press_event();
2181 //: Event triggered by a key release will widget has focus.
2184 Glib::SignalProxy1< bool,GdkEventKey* > signal_key_release_event();
2187 //: Event triggered by pointer entering widget area.
2190 Glib::SignalProxy1< bool,GdkEventCrossing* > signal_enter_notify_event();
2193 //: Event triggered by pointer leaving widget area.
2196 Glib::SignalProxy1< bool,GdkEventCrossing* > signal_leave_notify_event();
2199 //: Event triggered by a window resizing.
2202 Glib::SignalProxy1< bool,GdkEventConfigure* > signal_configure_event();
2205 Glib::SignalProxy1< bool,GdkEventFocus* > signal_focus_in_event();
2208 Glib::SignalProxy1< bool,GdkEventFocus* > signal_focus_out_event();
2211 Glib::SignalProxy1< bool,GdkEventAny* > signal_map_event();
2214 Glib::SignalProxy1< bool,GdkEventAny* > signal_unmap_event();
2217 Glib::SignalProxy1< bool,GdkEventProperty* > signal_property_notify_event();
2220 Glib::SignalProxy1< bool,GdkEventSelection* > signal_selection_clear_event();
2223 Glib::SignalProxy1< bool,GdkEventSelection* > signal_selection_request_event();
2226 Glib::SignalProxy1< bool,GdkEventSelection* > signal_selection_notify_event();
2229 Glib::SignalProxy1< bool,GdkEventProximity* > signal_proximity_in_event();
2232 Glib::SignalProxy1< bool,GdkEventProximity* > signal_proximity_out_event();
2235 Glib::SignalProxy1< bool,GdkEventVisibility* > signal_visibility_notify_event();
2238 Glib::SignalProxy1< bool,GdkEventClient* > signal_client_event();
2241 Glib::SignalProxy1< bool,GdkEventAny* > signal_no_expose_event();
2244 Glib::SignalProxy1< bool,GdkEventWindowState* > signal_window_state_event();
2247 //We use the optional custom_c_callback parameter with _WRAP_SIGNAL() for some of these,
2248 //so that we can write special code to wrap the non-const SelectioData& output parameters:
2251 Glib::SignalProxy3< void,SelectionData&,guint,guint > signal_selection_get();
2254 Glib::SignalProxy2< void,const SelectionData&,guint > signal_selection_received();
2257 Glib::SignalProxy1< void,const Glib::RefPtr<Gdk::DragContext>& > signal_drag_begin();
2260 Glib::SignalProxy1< void,const Glib::RefPtr<Gdk::DragContext>& > signal_drag_end();
2263 Glib::SignalProxy4< void,const Glib::RefPtr<Gdk::DragContext>&,SelectionData&,guint,guint > signal_drag_data_get();
2266 Glib::SignalProxy1< void,const Glib::RefPtr<Gdk::DragContext>& > signal_drag_data_delete();
2269 Glib::SignalProxy2< void,const Glib::RefPtr<Gdk::DragContext>&,guint > signal_drag_leave();
2272 Glib::SignalProxy4< bool,const Glib::RefPtr<Gdk::DragContext>&,int,int,guint > signal_drag_motion();
2275 Glib::SignalProxy4< bool,const Glib::RefPtr<Gdk::DragContext>&,int,int,guint > signal_drag_drop();
2278 Glib::SignalProxy6< void,const Glib::RefPtr<Gdk::DragContext>&,int,int,const SelectionData&,guint,guint > signal_drag_data_received();
2281 //accessibility signals:
2284 Glib::SignalProxy0< Glib::RefPtr<Atk::Object> > signal_get_accessible();
2287 Glib::SignalProxy1< void,const Glib::RefPtr<Gdk::Screen>& > signal_screen_changed();
2290 //TODO: The signal_id is very C-like here:
2291 //_WRAP_SIGNAL(bool can_activate_accel(guint signal_id), "can_activate_accel")
2293 //Keybinding signals:
2296 /** The name of the widget.
2298 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2299 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2300 * the value of the property changes.
2302 Glib::PropertyProxy<Glib::ustring> property_name() ;
2304 /** The name of the widget.
2306 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2307 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2308 * the value of the property changes.
2310 Glib::PropertyProxy_ReadOnly<Glib::ustring> property_name() const;
2312 /** The parent widget of this widget. Must be a Container widget.
2314 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2315 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2316 * the value of the property changes.
2318 Glib::PropertyProxy<Container*> property_parent() ;
2320 /** The parent widget of this widget. Must be a Container widget.
2322 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2323 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2324 * the value of the property changes.
2326 Glib::PropertyProxy_ReadOnly<Container*> property_parent() const;
2328 /** Override for width request of the widget
2330 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2331 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2332 * the value of the property changes.
2334 Glib::PropertyProxy<int> property_width_request() ;
2336 /** Override for width request of the widget
2338 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2339 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2340 * the value of the property changes.
2342 Glib::PropertyProxy_ReadOnly<int> property_width_request() const;
2344 /** Override for height request of the widget
2346 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2347 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2348 * the value of the property changes.
2350 Glib::PropertyProxy<int> property_height_request() ;
2352 /** Override for height request of the widget
2354 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2355 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2356 * the value of the property changes.
2358 Glib::PropertyProxy_ReadOnly<int> property_height_request() const;
2360 /** Whether the widget is visible.
2362 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2363 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2364 * the value of the property changes.
2366 Glib::PropertyProxy<bool> property_visible() ;
2368 /** Whether the widget is visible.
2370 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2371 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2372 * the value of the property changes.
2374 Glib::PropertyProxy_ReadOnly<bool> property_visible() const;
2376 /** Whether the widget responds to input.
2378 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2379 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2380 * the value of the property changes.
2382 Glib::PropertyProxy<bool> property_sensitive() ;
2384 /** Whether the widget responds to input.
2386 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2387 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2388 * the value of the property changes.
2390 Glib::PropertyProxy_ReadOnly<bool> property_sensitive() const;
2392 /** Whether the application will paint directly on the widget.
2394 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2395 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2396 * the value of the property changes.
2398 Glib::PropertyProxy<bool> property_app_paintable() ;
2400 /** Whether the application will paint directly on the widget.
2402 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2403 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2404 * the value of the property changes.
2406 Glib::PropertyProxy_ReadOnly<bool> property_app_paintable() const;
2408 /** Whether the widget can accept the input focus.
2410 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2411 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2412 * the value of the property changes.
2414 Glib::PropertyProxy<bool> property_can_focus() ;
2416 /** Whether the widget can accept the input focus.
2418 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2419 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2420 * the value of the property changes.
2422 Glib::PropertyProxy_ReadOnly<bool> property_can_focus() const;
2424 /** Whether the widget has the input focus.
2426 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2427 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2428 * the value of the property changes.
2430 Glib::PropertyProxy<bool> property_has_focus() ;
2432 /** Whether the widget has the input focus.
2434 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2435 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2436 * the value of the property changes.
2438 Glib::PropertyProxy_ReadOnly<bool> property_has_focus() const;
2440 /** Whether the widget can be the default widget.
2442 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2443 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2444 * the value of the property changes.
2446 Glib::PropertyProxy<bool> property_can_default() ;
2448 /** Whether the widget can be the default widget.
2450 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2451 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2452 * the value of the property changes.
2454 Glib::PropertyProxy_ReadOnly<bool> property_can_default() const;
2456 /** Whether the widget is the default widget.
2458 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2459 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2460 * the value of the property changes.
2462 Glib::PropertyProxy<bool> property_has_default() ;
2464 /** Whether the widget is the default widget.
2466 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2467 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2468 * the value of the property changes.
2470 Glib::PropertyProxy_ReadOnly<bool> property_has_default() const;
2474 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2475 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2476 * the value of the property changes.
2478 Glib::PropertyProxy<bool> property_receives_default() ;
2482 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2483 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2484 * the value of the property changes.
2486 Glib::PropertyProxy_ReadOnly<bool> property_receives_default() const;
2488 /** Whether the widget is part of a composite widget.
2490 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2491 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2492 * the value of the property changes.
2494 Glib::PropertyProxy_ReadOnly<bool> property_composite_child() const;
2497 /** The style of the widget
2499 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2500 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2501 * the value of the property changes.
2503 Glib::PropertyProxy< Glib::RefPtr<Style> > property_style() ;
2505 /** The style of the widget
2507 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2508 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2509 * the value of the property changes.
2511 Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Style> > property_style() const;
2513 /** The event mask that decides what kind of GdkEvents this widget gets.
2515 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2516 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2517 * the value of the property changes.
2519 Glib::PropertyProxy<Gdk::EventMask> property_events() ;
2521 /** The event mask that decides what kind of GdkEvents this widget gets.
2523 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2524 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2525 * the value of the property changes.
2527 Glib::PropertyProxy_ReadOnly<Gdk::EventMask> property_events() const;
2529 /** The mask that decides what kind of extension events this widget gets.
2531 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2532 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2533 * the value of the property changes.
2535 Glib::PropertyProxy<Gdk::ExtensionMode> property_extension_events() ;
2537 /** The mask that decides what kind of extension events this widget gets.
2539 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
2540 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
2541 * the value of the property changes.
2543 Glib::PropertyProxy_ReadOnly<Gdk::ExtensionMode> property_extension_events() const;
2547 //comment in GTK+ header: "seldomly overidden"
2548 virtual void dispatch_child_properties_changed_vfunc(guint p1, GParamSpec** p2);
2550 virtual void show_all_vfunc();
2551 virtual void hide_all_vfunc();
2553 virtual Glib::RefPtr<Atk::Object> get_accessible_vfunc();
2560 /** This function is only for use in widget implementations. Causes
2561 * a widget to be mapped if it isn't already.
2565 /** This function is only for use in widget implementations. Causes
2566 * a widget to be unmapped if it's currently mapped.
2570 /** Creates the GDK (windowing system) resources associated with a
2571 * widget. For example, @a widget ->window will be created when a widget
2572 * is realized. Normally realization happens implicitly; if you show
2573 * a widget and all its parent containers, then the widget will be
2574 * realized and mapped automatically.
2576 * Realizing a widget requires all
2577 * the widget's parent widgets to be realized; calling
2578 * realize() realizes the widget's parents in addition to
2579 * @a widget itself. If a widget is not yet inside a toplevel window
2580 * when you realize it, bad things will happen.
2582 * This function is primarily used in widget implementations, and
2583 * isn't very useful otherwise. Many times when you think you might
2584 * need it, a better approach is to connect to a signal that will be
2585 * called after the widget is realized automatically, such as
2586 * "expose_event". Or simply Glib::signal_connect_after() to the
2591 /** This function is only useful in widget implementations.
2592 * Causes a widget to be unrealized (frees all GDK resources
2593 * associated with the widget, such as @a widget ->window).
2598 /** This function is only for use in widget implementations. Obtains
2599 * @a widget ->requisition, unless someone has forced a particular
2600 * geometry on the widget (e.g. with set_usize()), in which
2601 * case it returns that geometry instead of the widget's requisition.
2603 * This function differs from size_request() in that
2604 * it retrieves the last size request value from @a widget ->requisition,
2605 * while size_request() actually calls the "size_request" method
2606 * on @a widget to compute the size request and fill in @a widget ->requisition,
2607 * and only then returns @a widget ->requisition.
2609 * Because this function does not call the "size_request" method, it
2610 * can only be used when you know that @a widget ->requisition is
2611 * up-to-date, that is, size_request() has been called
2612 * since the last time a resize was queued. In general, only container
2613 * implementations have this information; applications should use
2615 * @param requisition A Gtk::Requisition to be filled in.
2617 void get_child_requisition(Requisition& requisition) const;
2619 //The parameter name is "the_property_name" to avoid a warning because there is a method with the "property_name" name.
2621 /** Gets the value of a style property of @a widget .
2622 * @param the_property_name The name of a style property.
2623 * @param value Location to return the property value.
2625 void get_style_property_value(
2626 const Glib::ustring& the_property_name, Glib::ValueBase& value) const;
2628 void realize_if_needed();
2630 void set_allocation(const Allocation& value);
2631 void set_window(const Glib::RefPtr<Gdk::Window>& value);
2637 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2639 //The parameter name is "the_property_name" to avoid a warning because there is a method with the "property_name" name.
2640 template <class PropertyType>
2641 void Widget::get_style_property(const Glib::ustring& the_property_name, PropertyType& value) const
2643 Glib::Value<PropertyType> property_value;
2644 property_value.init(Glib::Value<PropertyType>::value_type());
2646 this->get_style_property_value(the_property_name, property_value);
2648 value = property_value.get();
2651 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
2658 /** @relates Gtk::Widget
2659 * @param object The C instance
2660 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
2661 * @result A C++ instance that wraps this C instance.
2663 Gtk::Widget* wrap(GtkWidget* object, bool take_copy = false);
2665 #endif /* _GTKMM_WIDGET_H */