// Generated by gmmproc 2.54.0 -- DO NOT MODIFY!
#ifndef _GTKMM_WIDGET_H
#define _GTKMM_WIDGET_H
#include <gtkmmconfig.h>
#include <glibmm/ustring.h>
#include <sigc++/sigc++.h>
/* Copyright (C) 2002, 2003 The gtkmm Development Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#include <vector>
#include <pangomm/context.h>
#include <pangomm/layout.h>
#ifdef GTKMM_ATKMM_ENABLED
#include <atkmm/object.h>
#include <atkmm/implementor.h>
#endif //GTKMM_ATKMM_ENABLED
#include <gtkmm/object.h>
#include <gtkmm/buildable.h>
#include <gdkmm/event.h>
#include <gdkmm/types.h>
#include <gdkmm/window.h>
#include <gdkmm/dragcontext.h>
#include <gdkmm/pixbuf.h>
#include <gdkmm/screen.h>
#include <gtkmm/enums.h>
#include <gdkmm/display.h>
#include <gtkmm/targetlist.h>
#include <gtkmm/clipboard.h>
#include <gtkmm/requisition.h>
#include <gtkmm/stylecontext.h>
#include <gtkmm/widgetpath.h>
#include <giomm/actiongroup.h>
#ifndef DOXYGEN_SHOULD_SKIP_THIS
extern "C"
{
typedef struct _GtkTargetEntry GtkTargetEntry;
}
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
using GtkWidget = struct _GtkWidget;
using GtkWidgetClass = struct _GtkWidgetClass;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Gtk
{ class Widget_Class; } // namespace Gtk
#endif //DOXYGEN_SHOULD_SKIP_THIS
namespace Gtk
{
/** @addtogroup gtkmmEnums gtkmm Enums and Flags */
/**
* @var DestDefaults DEST_DEFAULT_MOTION
* If set for a widget, GTK+, during a drag over this
* widget will check if the drag matches this widget’s list of possible targets
* and actions.
* GTK+ will then call gdk_drag_status() as appropriate.
*
* @var DestDefaults DEST_DEFAULT_HIGHLIGHT
* If set for a widget, GTK+ will draw a highlight on
* this widget as long as a drag is over this widget and the widget drag format
* and action are acceptable.
*
* @var DestDefaults DEST_DEFAULT_DROP
* If set for a widget, when a drop occurs, GTK+ will
* will check if the drag matches this widget’s list of possible targets and
* actions. If so, GTK+ will call gtk_drag_get_data() on behalf of the widget.
* Whether or not the drop is successful, GTK+ will call gtk_drag_finish(). If
* the action was a move, then if the drag was successful, then <tt>true</tt> will be
* passed for the @a delete parameter to gtk_drag_finish().
*
* @var DestDefaults DEST_DEFAULT_ALL
* If set, specifies that all default actions should
* be taken.
*
* @enum DestDefaults
*
* The Gtk::DestDefaults enumeration specifies the various
* types of action that will be taken on behalf
* of the user for a drag destination site.
*
* @ingroup gtkmmEnums
* @par Bitwise operators:
* <tt>%DestDefaults operator|(DestDefaults, DestDefaults)</tt><br>
* <tt>%DestDefaults operator&(DestDefaults, DestDefaults)</tt><br>
* <tt>%DestDefaults operator^(DestDefaults, DestDefaults)</tt><br>
* <tt>%DestDefaults operator~(DestDefaults)</tt><br>
* <tt>%DestDefaults& operator|=(DestDefaults&, DestDefaults)</tt><br>
* <tt>%DestDefaults& operator&=(DestDefaults&, DestDefaults)</tt><br>
* <tt>%DestDefaults& operator^=(DestDefaults&, DestDefaults)</tt><br>
*/
enum DestDefaults
{
DEST_DEFAULT_MOTION = 1 << 0,
DEST_DEFAULT_HIGHLIGHT = 1 << 1,
DEST_DEFAULT_DROP = 1 << 2,
DEST_DEFAULT_ALL = 0x07
};
/** @ingroup gtkmmEnums */
inline DestDefaults operator|(DestDefaults lhs, DestDefaults rhs)
{ return static_cast<DestDefaults>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
/** @ingroup gtkmmEnums */
inline DestDefaults operator&(DestDefaults lhs, DestDefaults rhs)
{ return static_cast<DestDefaults>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
/** @ingroup gtkmmEnums */
inline DestDefaults operator^(DestDefaults lhs, DestDefaults rhs)
{ return static_cast<DestDefaults>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
/** @ingroup gtkmmEnums */
inline DestDefaults operator~(DestDefaults flags)
{ return static_cast<DestDefaults>(~static_cast<unsigned>(flags)); }
/** @ingroup gtkmmEnums */
inline DestDefaults& operator|=(DestDefaults& lhs, DestDefaults rhs)
{ return (lhs = static_cast<DestDefaults>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
/** @ingroup gtkmmEnums */
inline DestDefaults& operator&=(DestDefaults& lhs, DestDefaults rhs)
{ return (lhs = static_cast<DestDefaults>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
/** @ingroup gtkmmEnums */
inline DestDefaults& operator^=(DestDefaults& lhs, DestDefaults rhs)
{ return (lhs = static_cast<DestDefaults>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
} // namespace Gtk
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{
template <>
class Value<Gtk::DestDefaults> : public Glib::Value_Flags<Gtk::DestDefaults>
{
public:
static GType value_type() G_GNUC_CONST;
};
} // namespace Glib
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
namespace Gtk
{
/**
* @var WidgetHelpType WIDGET_HELP_TOOLTIP
* Tooltip.
*
* @var WidgetHelpType WIDGET_HELP_WHATS_THIS
* What’s this.
*
* @enum WidgetHelpType
*
* Kinds of widget-specific help. Used by the signal_show_help() signal.
*
* @ingroup gtkmmEnums
*/
enum WidgetHelpType
{
WIDGET_HELP_TOOLTIP,
WIDGET_HELP_WHATS_THIS
};
} // namespace Gtk
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{
template <>
class Value<Gtk::WidgetHelpType> : public Glib::Value_Enum<Gtk::WidgetHelpType>
{
public:
static GType value_type() G_GNUC_CONST;
};
} // namespace Glib
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
namespace Gtk
{
/**
* @var DragResult DRAG_RESULT_SUCCESS
* The drag operation was successful.
*
* @var DragResult DRAG_RESULT_NO_TARGET
* No suitable drag target.
*
* @var DragResult DRAG_RESULT_USER_CANCELLED
* The user cancelled the drag operation.
*
* @var DragResult DRAG_RESULT_TIMEOUT_EXPIRED
* The drag operation timed out.
*
* @var DragResult DRAG_RESULT_GRAB_BROKEN
* The pointer or keyboard grab used
* for the drag operation was broken.
*
* @var DragResult DRAG_RESULT_ERROR
* The drag operation failed due to some
* unspecified error.
*
* @enum DragResult
*
* Gives an indication why a drag operation failed.
* The value can by obtained by connecting to the
* Gtk::Widget::signal_drag_failed() signal.
*
* @ingroup gtkmmEnums
*/
enum DragResult
{
DRAG_RESULT_SUCCESS,
DRAG_RESULT_NO_TARGET,
DRAG_RESULT_USER_CANCELLED,
DRAG_RESULT_TIMEOUT_EXPIRED,
DRAG_RESULT_GRAB_BROKEN,
DRAG_RESULT_ERROR
};
} // namespace Gtk
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{
template <>
class Value<Gtk::DragResult> : public Glib::Value_Enum<Gtk::DragResult>
{
public:
static GType value_type() G_GNUC_CONST;
};
} // namespace Glib
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
namespace Gtk
{
class Action;
class Style;
class AccelGroup;
class Adjustment;
class Window;
class Container;
class Settings;
class Tooltip;
class StockID; //deprecated.
// Gtk::Allocation is a typedef of Gdk::Rectangle because GtkAllocation is
// a typedef of GdkRectangle.
typedef Gdk::Rectangle Allocation;
/** @defgroup Widgets Widgets
*/
//TODO: Deal with the GtkObject->GObject change:
/** Abstract Widget (Base class for all widgets)
*
* As the base class of all widgets this contains all of the properties
* and methods common to all widgets. It is an abstract class that
* can not be instantiated.
*
* Important part of widgets are the *_event signals and virtual methods
* that every widget have. Those are events coming directly from gdk and
* thus also from XLib. By overriding those virtual methods you can
* trap everything a widget can ever do.
* In order to capture events from a widget, the event mask must
* first be set with ().
*
* Only widgets with a Gdk::Window on the server side are allowed to
* capture events. Widgets in the Gtk::Misc group for example lack
* a Gdk::Window.
*/
class Widget
: public Object,
public Buildable
#ifdef GTKMM_ATKMM_ENABLED
,public Atk::Implementor
#endif //GTKMM_ATKMM_ENABLED
{
public:
#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef Widget CppObjectType;
typedef Widget_Class CppClassType;
typedef GtkWidget BaseObjectType;
typedef GtkWidgetClass BaseClassType;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
Widget(Widget&& src) noexcept;
Widget& operator=(Widget&& src) noexcept;
// noncopyable
Widget(const Widget&) = delete;
Widget& operator=(const Widget&) = delete;
/** Destroys the widget. The widget will be automatically removed from the parent container.
*/
~Widget() noexcept override;
#ifndef DOXYGEN_SHOULD_SKIP_THIS
private:
friend class Widget_Class;
static CppClassType widget_class_;
protected:
explicit Widget(const Glib::ConstructParams& construct_params);
explicit Widget(GtkWidget* castitem);
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
public:
/** Get the GType for this class, for use with the underlying GObject type system.
*/
static GType get_type() G_GNUC_CONST;
#ifndef DOXYGEN_SHOULD_SKIP_THIS
static GType get_base_type() G_GNUC_CONST;
#endif
///Provides access to the underlying C GtkObject.
GtkWidget* gobj() { return reinterpret_cast<GtkWidget*>(gobject_); }
///Provides access to the underlying C GtkObject.
const GtkWidget* gobj() const { return reinterpret_cast<GtkWidget*>(gobject_); }
public:
//C++ methods used to invoke GTK+ virtual functions:
protected:
//GTK+ Virtual Functions (override these to change behaviour):
//Default Signal Handlers::
/// This is a default handler for the signal signal_show().
virtual void on_show();
/// This is a default handler for the signal signal_hide().
virtual void on_hide();
/// This is a default handler for the signal signal_map().
virtual void on_map();
/// This is a default handler for the signal signal_unmap().
virtual void on_unmap();
/// This is a default handler for the signal signal_realize().
virtual void on_realize();
/// This is a default handler for the signal signal_unrealize().
virtual void on_unrealize();
/// This is a default handler for the signal signal_size_allocate().
virtual void on_size_allocate(Allocation& allocation);
/// This is a default handler for the signal signal_state_changed().
virtual void on_state_changed(Gtk::StateType previous_state);
/// This is a default handler for the signal signal_parent_changed().
virtual void on_parent_changed(Widget* previous_parent);
/// This is a default handler for the signal signal_hierarchy_changed().
virtual void on_hierarchy_changed(Widget* previous_toplevel);
/// This is a default handler for the signal signal_style_updated().
virtual void on_style_updated();
/// This is a default handler for the signal signal_direction_changed().
virtual void on_direction_changed(TextDirection direction);
/// This is a default handler for the signal signal_grab_notify().
virtual void on_grab_notify(bool was_grabbed);
/// This is a default handler for the signal signal_child_notify().
virtual void on_child_notify(GParamSpec* pspec);
/// This is a default handler for the signal signal_mnemonic_activate().
virtual bool on_mnemonic_activate(bool group_cycling);
/// This is a default handler for the signal signal_grab_focus().
virtual void on_grab_focus();
/// This is a default handler for the signal signal_focus().
virtual bool on_focus(DirectionType direction);
/// This is a default handler for the signal signal_event().
virtual bool on_event(GdkEvent* gdk_event);
/// This is a default handler for the signal signal_button_press_event().
virtual bool on_button_press_event(GdkEventButton* button_event);
/// This is a default handler for the signal signal_button_release_event().
virtual bool on_button_release_event(GdkEventButton* release_event);
/// This is a default handler for the signal signal_scroll_event().
virtual bool on_scroll_event(GdkEventScroll* scroll_event);
/// This is a default handler for the signal signal_motion_notify_event().
virtual bool on_motion_notify_event(GdkEventMotion* motion_event);
/// This is a default handler for the signal signal_delete_event().
virtual bool on_delete_event(GdkEventAny* any_event);
/// This is a default handler for the signal signal_draw().
virtual bool on_draw(const ::Cairo::RefPtr< ::Cairo::Context>& cr);
/// This is a default handler for the signal signal_key_press_event().
virtual bool on_key_press_event(GdkEventKey* key_event);
/// This is a default handler for the signal signal_key_release_event().
virtual bool on_key_release_event(GdkEventKey* key_event);
/// This is a default handler for the signal signal_enter_notify_event().
virtual bool on_enter_notify_event(GdkEventCrossing* crossing_event);
/// This is a default handler for the signal signal_leave_notify_event().
virtual bool on_leave_notify_event(GdkEventCrossing* crossing_event);
/// This is a default handler for the signal signal_configure_event().
virtual bool on_configure_event(GdkEventConfigure* configure_event);
/// This is a default handler for the signal signal_focus_in_event().
virtual bool on_focus_in_event(GdkEventFocus* focus_event);
/// This is a default handler for the signal signal_focus_out_event().
virtual bool on_focus_out_event(GdkEventFocus* gdk_event);
/// This is a default handler for the signal signal_map_event().
virtual bool on_map_event(GdkEventAny* any_event);
/// This is a default handler for the signal signal_unmap_event().
virtual bool on_unmap_event(GdkEventAny* any_event);
/// This is a default handler for the signal signal_property_notify_event().
virtual bool on_property_notify_event(GdkEventProperty* property_event);
/// This is a default handler for the signal signal_selection_clear_event().
virtual bool on_selection_clear_event(GdkEventSelection* selection_event);
/// This is a default handler for the signal signal_selection_request_event().
virtual bool on_selection_request_event(GdkEventSelection* selection_event);
/// This is a default handler for the signal signal_selection_notify_event().
virtual bool on_selection_notify_event(GdkEventSelection* selection_event);
/// This is a default handler for the signal signal_proximity_in_event().
virtual bool on_proximity_in_event(GdkEventProximity* proximity_event);
/// This is a default handler for the signal signal_proximity_out_event().
virtual bool on_proximity_out_event(GdkEventProximity* proximity_event);
/// This is a default handler for the signal signal_visibility_notify_event().
virtual bool on_visibility_notify_event(GdkEventVisibility* visibility_event);
/// This is a default handler for the signal signal_window_state_event().
virtual bool on_window_state_event(GdkEventWindowState* window_state_event);
/// This is a default handler for the signal signal_selection_get().
virtual void on_selection_get(SelectionData& selection_data, guint info, guint time);
/// This is a default handler for the signal signal_selection_received().
virtual void on_selection_received(const SelectionData& selection_data, guint time);
/// This is a default handler for the signal signal_drag_begin().
virtual void on_drag_begin(const Glib::RefPtr<Gdk::DragContext>& context);
/// This is a default handler for the signal signal_drag_end().
virtual void on_drag_end(const Glib::RefPtr<Gdk::DragContext>& context);
/// This is a default handler for the signal signal_drag_data_get().
virtual void on_drag_data_get(const Glib::RefPtr<Gdk::DragContext>& context, SelectionData& selection_data, guint info, guint time);
/// This is a default handler for the signal signal_drag_data_delete().
virtual void on_drag_data_delete(const Glib::RefPtr<Gdk::DragContext>& context);
/// This is a default handler for the signal signal_drag_leave().
virtual void on_drag_leave(const Glib::RefPtr<Gdk::DragContext>& context, guint time);
/// This is a default handler for the signal signal_drag_motion().
virtual bool on_drag_motion(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, guint time);
/// This is a default handler for the signal signal_drag_drop().
virtual bool on_drag_drop(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, guint time);
/// This is a default handler for the signal signal_drag_data_received().
virtual void on_drag_data_received(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, const SelectionData& selection_data, guint info, guint time);
/// This is a default handler for the signal signal_screen_changed().
virtual void on_screen_changed(const Glib::RefPtr<Gdk::Screen>& previous_screen);
private:
public:
friend class Main;
/** Flags a widget to be displayed. Any widget that isn’t shown will
* not appear on the screen. If you want to show all the widgets in a
* container, it’s easier to call show_all() on the
* container, instead of individually showing the widgets.
*
* Remember that you have to show the containers containing a widget,
* in addition to the widget itself, before it will appear onscreen.
*
* When a toplevel container is shown, it is immediately realized and
* mapped; other shown widgets are realized and mapped when their
* toplevel container is realized and mapped.
*/
void show();
/** Shows a widget. If the widget is an unmapped toplevel widget
* (i.e. a Gtk::Window that has not yet been shown), enter the main
* loop and wait for the window to actually be mapped. Be careful;
* because the main loop is running, anything can happen during
* this function.
*/
void show_now();
/** Reverses the effects of show(), causing the widget to be
* hidden (invisible to the user).
*/
void hide();
/** Recursively shows a widget, and any child widgets (if the widget is
* a container).
*/
void show_all();
/* QUEUE DRAWS */
/** Equivalent to calling queue_draw_area() for the
* entire area of a widget.
*/
void queue_draw();
/** Convenience function that calls queue_draw_region() on
* the region created from the given coordinates.
*
* The region here is specified in widget coordinates.
* Widget coordinates are a bit odd; for historical reasons, they are
* defined as @a widget->window coordinates for widgets that return <tt>true</tt> for
* get_has_window(), and are relative to @a widget->allocation.x,
* @a widget->allocation.y otherwise.
*
* @a width or @a height may be 0, in this case this function does
* nothing. Negative values for @a width and @a height are not allowed.
*
* @param x X coordinate of upper-left corner of rectangle to redraw.
* @param y Y coordinate of upper-left corner of rectangle to redraw.
* @param width Width of region to draw.
* @param height Height of region to draw.
*/
void queue_draw_area(int x, int y, int width, int height);
/** Invalidates the area of @a widget defined by @a region by calling
* gdk_window_invalidate_region() on the widget’s window and all its
* child windows. Once the main loop becomes idle (after the current
* batch of events has been processed, roughly), the window will
* receive expose events for the union of all regions that have been
* invalidated.
*
* Normally you would only use this function in widget
* implementations. You might also use it to schedule a redraw of a
* Gtk::DrawingArea or some portion thereof.
*
* @newin{3,0}
*
* @param region Region to draw.
*/
void queue_draw_region(const ::Cairo::RefPtr<const ::Cairo::Region>& region);
/** This function is only for use in widget implementations.
* Flags a widget to have its size renegotiated; should
* be called when a widget for some reason has a new size request.
* For example, when you change the text in a Gtk::Label, Gtk::Label
* queues a resize to ensure there’s enough space for the new text.
*
* Note that you cannot call queue_resize() on a widget
* from inside its implementation of the GtkWidgetClass::size_allocate
* virtual method. Calls to queue_resize() from inside
* GtkWidgetClass::size_allocate will be silently ignored.
*/
void queue_resize();
/** This function is only for use in widget implementations.
*
* Flags the widget for a rerun of the GtkWidgetClass::size_allocate
* function. Use this function instead of queue_resize()
* when the @a widget's size request didn't change but it wants to
* reposition its contents.
*
* An example user of this function is set_halign().
*
* @newin{3,20}
*/
void queue_allocate();
/** This function is only used by Gtk::Container subclasses, to assign a size
* and position to their child widgets.
*
* In this function, the allocation may be adjusted. It will be forced
* to a 1x1 minimum size, and the adjust_size_allocation virtual
* method on the child will be used to adjust the allocation. Standard
* adjustments include removing the widget’s margins, and applying the
* widget’s Gtk::Widget::property_halign() and Gtk::Widget::property_valign() properties.
*
* For baseline support in containers you need to use size_allocate_with_baseline()
* instead.
*
* @param allocation Position and size to be allocated to @a widget.
*/
void size_allocate(const Allocation& allocation);
/** This function is only used by Gtk::Container subclasses, to assign a size,
* position and (optionally) baseline to their child widgets.
*
* In this function, the allocation and baseline may be adjusted. It
* will be forced to a 1x1 minimum size, and the
* adjust_size_allocation virtual and adjust_baseline_allocation
* methods on the child will be used to adjust the allocation and
* baseline. Standard adjustments include removing the widget's
* margins, and applying the widget’s Gtk::Widget::property_halign() and
* Gtk::Widget::property_valign() properties.
*
* If the child widget does not have a valign of Gtk::ALIGN_BASELINE the
* baseline argument is ignored and -1 is used instead.
*
* @newin{3,10}
*
* @param allocation Position and size to be allocated to @a widget.
* @param baseline The baseline of the child, or -1.
*/
void size_allocate(const Allocation& allocation, int baseline);
//deprecated
/** Gets whether the widget prefers a height-for-width layout
* or a width-for-height layout.
*
* Gtk::Bin widgets generally propagate the preference of
* their child, container widgets need to request something either in
* context of their children or in context of their allocation
* capabilities.
*
* @newin{3,0}
*
* @return The Gtk::SizeRequestMode preferred by @a widget.
*/
SizeRequestMode get_request_mode() const;
/** Retrieves a widget’s initial minimum and natural width.
*
* This call is specific to height-for-width requests.
*
* The returned request will be modified by the
* GtkWidgetClass::adjust_size_request virtual method and by any
* Gtk::SizeGroups that have been applied. That is, the returned request
* is the one that should be used for layout, not necessarily the one
* returned by the widget itself.
*
* @newin{3,0}
*
* @param minimum_width Location to store the minimum width, or <tt>nullptr</tt>.
* @param natural_width Location to store the natural width, or <tt>nullptr</tt>.
*/
void get_preferred_width(int& minimum_width, int& natural_width) const;
/** Retrieves a widget’s minimum and natural height if it would be given
* the specified @a width.
*
* The returned request will be modified by the
* GtkWidgetClass::adjust_size_request virtual method and by any
* Gtk::SizeGroups that have been applied. That is, the returned request
* is the one that should be used for layout, not necessarily the one
* returned by the widget itself.
*
* @newin{3,0}
*
* @param width The width which is available for allocation.
* @param minimum_height Location for storing the minimum height, or <tt>nullptr</tt>.
* @param natural_height Location for storing the natural height, or <tt>nullptr</tt>.
*/
void get_preferred_height_for_width(int width, int& minimum_height, int& natural_height) const;
/** Retrieves a widget’s minimum and natural height and the corresponding baselines if it would be given
* the specified @a width, or the default height if @a width is -1. The baselines may be -1 which means
* that no baseline is requested for this widget.
*
* The returned request will be modified by the
* GtkWidgetClass::adjust_size_request and GtkWidgetClass::adjust_baseline_request virtual methods
* and by any Gtk::SizeGroups that have been applied. That is, the returned request
* is the one that should be used for layout, not necessarily the one
* returned by the widget itself.
*
* @newin{3,10}
*
* @param width The width which is available for allocation, or -1 if none.
* @param minimum_height Location for storing the minimum height, or <tt>nullptr</tt>.
* @param natural_height Location for storing the natural height, or <tt>nullptr</tt>.
* @param minimum_baseline Location for storing the baseline for the minimum height, or <tt>nullptr</tt>.
* @param natural_baseline Location for storing the baseline for the natural height, or <tt>nullptr</tt>.
*/
void get_preferred_height_for_width(int width, int& minimum_height, int& natural_height, int& minimum_baseline, int& natural_baseline) const;
/** Retrieves a widget’s initial minimum and natural height.
*
* This call is specific to width-for-height requests.
*
* The returned request will be modified by the
* GtkWidgetClass::adjust_size_request virtual method and by any
* Gtk::SizeGroups that have been applied. That is, the returned request
* is the one that should be used for layout, not necessarily the one
* returned by the widget itself.
*
* @newin{3,0}
*
* @param minimum_height Location to store the minimum height, or <tt>nullptr</tt>.
* @param natural_height Location to store the natural height, or <tt>nullptr</tt>.
*/
void get_preferred_height(int& minimum_height, int& natural_height) const;
/** Retrieves a widget’s minimum and natural width if it would be given
* the specified @a height.
*
* The returned request will be modified by the
* GtkWidgetClass::adjust_size_request virtual method and by any
* Gtk::SizeGroups that have been applied. That is, the returned request
* is the one that should be used for layout, not necessarily the one
* returned by the widget itself.
*
* @newin{3,0}
*
* @param height The height which is available for allocation.
* @param minimum_width Location for storing the minimum width, or <tt>nullptr</tt>.
* @param natural_width Location for storing the natural width, or <tt>nullptr</tt>.
*/
void get_preferred_width_for_height(int height, int& minimum_width, int& natural_width) const;
/** Retrieves the minimum and natural size of a widget, taking
* into account the widget’s preference for height-for-width management.
*
* This is used to retrieve a suitable size by container widgets which do
* not impose any restrictions on the child placement. It can be used
* to deduce toplevel window and menu sizes as well as child widgets in
* free-form containers such as GtkLayout.
*
* Handle with care. Note that the natural height of a height-for-width
* widget will generally be a smaller size than the minimum height, since the required
* height for the natural width is generally smaller than the required height for
* the minimum width.
*
* Use get_preferred_height_and_baseline_for_width() if you want to support
* baseline alignment.
*
* @newin{3,0}
*
* @param minimum_size Location for storing the minimum size, or <tt>nullptr</tt>.
* @param natural_size Location for storing the natural size, or <tt>nullptr</tt>.
*/
void get_preferred_size(Requisition& minimum_size, Requisition& natural_size) const;
/** Installs an accelerator for this @a widget in @a accel_group that causes
* @a accel_signal to be emitted if the accelerator is activated.
* The @a accel_group needs to be added to the widget’s toplevel via
* Gtk::Window::add_accel_group(), and the signal must be of type SIGNAL_ACTION.
* Accelerators added through this function are not user changeable during
* runtime. If you want to support accelerators that can be changed by the
* user, use Gtk::AccelMap::add_entry() and set_accel_path() or
* Gtk::MenuItem::set_accel_path() instead.
*
* @param accel_signal Widget signal to emit on accelerator activation.
* @param accel_group Accel group for this widget, added to its toplevel.
* @param accel_key GDK keyval of the accelerator.
* @param accel_mods Modifier key combination of the accelerator.
* @param accel_flags Flag accelerators, e.g. Gtk::ACCEL_VISIBLE.
*/
void add_accelerator(const Glib::ustring& accel_signal, const Glib::RefPtr<AccelGroup>& accel_group, guint accel_key, Gdk::ModifierType accel_mods, AccelFlags accel_flags);
/** Removes an accelerator from @a widget, previously installed with
* add_accelerator().
*
* @param accel_group Accel group for this widget.
* @param accel_key GDK keyval of the accelerator.
* @param accel_mods Modifier key combination of the accelerator.
* @return Whether an accelerator was installed and could be removed.
*/
bool remove_accelerator(const Glib::RefPtr<AccelGroup>& accel_group, guint accel_key, Gdk::ModifierType accel_mods);
/** Given an accelerator group, @a accel_group, and an accelerator path,
* @a accel_path, sets up an accelerator in @a accel_group so whenever the
* key binding that is defined for @a accel_path is pressed, @a widget
* will be activated. This removes any accelerators (for any
* accelerator group) installed by previous calls to
* set_accel_path(). Associating accelerators with
* paths allows them to be modified by the user and the modifications
* to be saved for future use. (See Gtk::AccelMap::save().)
*
* This function is a low level function that would most likely
* be used by a menu creation system like Gtk::UIManager. If you
* use Gtk::UIManager, setting up accelerator paths will be done
* automatically.
*
* Even when you you aren’t using Gtk::UIManager, if you only want to
* set up accelerators on menu items Gtk::MenuItem::set_accel_path()
* provides a somewhat more convenient interface.
*
* Note that @a accel_path string will be stored in a Quark. Therefore, if you
* pass a static string, you can save some memory by interning it first with
* Glib::intern_static_string().
*
* @param accel_path Path used to look up the accelerator.
* @param accel_group A Gtk::AccelGroup.
*/
void set_accel_path(const Glib::ustring& accel_path, const Glib::RefPtr<AccelGroup>& accel_group);
//GList* gtk_widget_list_accel_closures();
/** Emits the Gtk::Widget::signal_mnemonic_activate() signal.
*
* The default handler for this signal activates the @a widget if
* @a group_cycling is <tt>false</tt>, and just grabs the focus if @a group_cycling
* is <tt>true</tt>.
*
* @param group_cycling <tt>true</tt> if there are other widgets with the same mnemonic.
* @return <tt>true</tt> if the signal has been handled.
*/
bool mnemonic_activate(bool group_cycling);
//Probably not useful. Too C-specific: _WRAP_METHOD(bool can_activate_accel(guint signal_id) const, gtk_widget_can_activate_accel)
//TODO: Use C++ type
/** Rarely-used function. This function is used to emit
* the event signals on a widget (those signals should never
* be emitted without using this function to do so).
* If you want to synthesize an event though, don’t use this function;
* instead, use gtk_main_do_event() so the event will behave as if
* it were in the event queue. Don’t synthesize expose events; instead,
* use gdk_window_invalidate_rect() to invalidate a region of the
* window.
*
* @param gdk_event A Gdk::Event.
* @return Return from the event signal emission (<tt>true</tt> if
* the event was handled).
*/
bool event(GdkEvent* gdk_event);
#ifndef GTKMM_DISABLE_DEPRECATED
/** Very rarely-used function. This function is used to emit
* an expose event on a widget. This function is not normally used
* directly. The only time it is used is when propagating an expose
* event to a windowless child widget (get_has_window() is <tt>false</tt>),
* and that is normally done using Gtk::Container::propagate_draw().
*
* If you want to force an area of a window to be redrawn,
* use gdk_window_invalidate_rect() or gdk_window_invalidate_region().
* To cause the redraw to be done immediately, follow that call
* with a call to gdk_window_process_updates().
*
* Deprecated: 3.22: Application and widget code should not handle
* expose events directly; invalidation should use the Gtk::Widget
* API, and drawing should only happen inside Gtk::Widget::signal_draw()
* implementations
*
* @deprecated %Application and widget code should not handle expose events directly; invalidation should use the Gtk::Widget API, and drawing should only happen inside signal_draw() implementations.
*
* @param gdk_event A expose Gdk::Event.
* @return Return from the event signal emission (<tt>true</tt> if
* the event was handled).
*/
int send_expose(GdkEvent* gdk_event);
#endif // GTKMM_DISABLE_DEPRECATED
/** Sends the focus change @a gdk_event to @a widget
*
* This function is not meant to be used by applications. The only time it
* should be used is when it is necessary for a Gtk::Widget to assign focus
* to a widget that is semantically owned by the first widget even though
* it’s not a direct child - for instance, a search entry in a floating
* window similar to the quick search in Gtk::TreeView.
*
* An example of its usage is:
*
*
* [C example ellipted]
*
* @newin{2,20}
*
* @param gdk_event A Gdk::Event of type GDK_FOCUS_CHANGE.
* @return The return value from the event signal emission: <tt>true</tt>
* if the event was handled, and <tt>false</tt> otherwise.
*/
bool send_focus_change(GdkEvent* gdk_event);
/** For widgets that can be “activated” (buttons, menu items, etc.)
* this function activates them. Activation is what happens when you
* press Enter on a widget during key navigation. If @a widget isn't
* activatable, the function returns <tt>false</tt>.
*
* @return <tt>true</tt> if the widget was activatable.
*/
bool activate();
//TODO: When we can break ABI/API, change to void reparent(Container& new_parent).
// gtk_widget_reparent() is deprecated, but we want to keep Gtk::Widget::reparent().
/** Moves a widget from one Gtk::Container to another, handling reference
* count issues to avoid destroying the widget.
*
* @param new_parent A Gtk::Container to move the widget into.
*/
void reparent(Widget& new_parent);
bool intersect(const Gdk::Rectangle& area) const;
/** Computes the intersection of a @a widget’s area and @a area, storing
* the intersection in @a intersection, and returns <tt>true</tt> if there was
* an intersection. @a intersection may be <tt>nullptr</tt> if you’re only
* interested in whether there was an intersection.
*
* @param area A rectangle.
* @param intersection Rectangle to store intersection of @a widget and @a area.
* @return <tt>true</tt> if there was an intersection.
*/
bool intersect(const Gdk::Rectangle& area, Gdk::Rectangle& intersection) const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** Computes the intersection of a @a widget’s area and @a region, returning
* the intersection. The result may be empty, use cairo_region_is_empty() to
* check.
*
* Deprecated: 3.14: Use get_allocation() and
* cairo_region_intersect_rectangle() to get the same behavior.
*
* @deprecated Use get_allocation() and Cairo::Region::intersect(const Cairo::RectangleInt&) to get the same behavior.
*
* @param region A #cairo_region_t, in the same coordinate system as
* @a widget->allocation. That is, relative to @a widget->window
* for widgets which return <tt>false</tt> from get_has_window();
* relative to the parent window of @a widget->window otherwise.
* @return A newly allocated region holding the intersection of @a widget
* and @a region.
*/
::Cairo::RefPtr< ::Cairo::Region> region_intersect(const ::Cairo::RefPtr< ::Cairo::Region>& region) const;
#endif // GTKMM_DISABLE_DEPRECATED
/** Stops emission of Gtk::Widget::signal_child_notify() signals on @a widget. The
* signals are queued until thaw_child_notify() is called
* on @a widget.
*
* This is the analogue of Glib::object_freeze_notify() for child properties.
*/
void freeze_child_notify();
/** Emits a Gtk::Widget::signal_child_notify() signal for the
* [child property][child-properties] @a child_property
* on @a widget.
*
* This is the analogue of Glib::object_notify() for child properties.
*
* Also see Gtk::Container::child_notify().
*
* @param child_property The name of a child property installed on the
* class of @a widget’s parent.
*/
void child_notify(const Glib::ustring& child_property);
/** Reverts the effect of a previous call to freeze_child_notify().
* This causes all queued Gtk::Widget::signal_child_notify() signals on @a widget to be
* emitted.
*/
void thaw_child_notify();
/** Specifies whether @a widget can own the input focus. See
* grab_focus() for actually setting the input focus on a
* widget.
*
* @newin{2,18}
*
* @param can_focus Whether or not @a widget can own the input focus.
*/
void set_can_focus(bool can_focus = true);
/** Determines whether @a widget can own the input focus. See
* set_can_focus().
*
* @newin{2,18}
*
* @return <tt>true</tt> if @a widget can own the input focus, <tt>false</tt> otherwise.
*/
bool get_can_focus() const;
/** Determines if the widget has the global input focus. See
* is_focus() for the difference between having the global
* input focus, and only having the focus within a toplevel.
*
* @newin{2,18}
*
* @return <tt>true</tt> if the widget has the global input focus.
*/
bool has_focus() const;
/** Determines if the widget is the focus widget within its
* toplevel. (This does not mean that the Gtk::Widget::property_has_focus() property is
* necessarily set; Gtk::Widget::property_has_focus() will only be set if the
* toplevel widget additionally has the global input focus.)
*
* @return <tt>true</tt> if the widget is the focus widget.
*/
bool is_focus() const;
/** Determines if the widget should show a visible indication that
* it has the global input focus. This is a convenience function for
* use in signal_draw() handlers that takes into account whether focus
* indication should currently be shown in the toplevel window of
* @a widget. See Gtk::Window::get_focus_visible() for more information
* about focus indication.
*
* To find out if the widget has the global input focus, use
* has_focus().
*
* @newin{3,2}
*
* @return <tt>true</tt> if the widget should display a “focus rectangle”.
*/
bool has_visible_focus() const;
/** Causes @a widget to have the keyboard focus for the Gtk::Window it's
* inside. @a widget must be a focusable widget, such as a Gtk::Entry;
* something like Gtk::Frame won’t work.
*
* More precisely, it must have the Gtk::CAN_FOCUS flag set. Use
* set_can_focus() to modify that flag.
*
* The widget also needs to be realized and mapped. This is indicated by the
* related signals. Grabbing the focus immediately after creating the widget
* will likely fail and cause critical warnings.
*/
void grab_focus();
/** Sets whether the widget should grab focus when it is clicked with the mouse.
* Making mouse clicks not grab focus is useful in places like toolbars where
* you don’t want the keyboard focus removed from the main area of the
* application.
*
* @newin{3,20}
*
* @param focus_on_click Whether the widget should grab focus when clicked with the mouse.
*/
void set_focus_on_click(bool focus_on_click = true);
/** Returns whether the widget should grab focus when it is clicked with the mouse.
* See set_focus_on_click().
*
* @newin{3,20}
*
* @return <tt>true</tt> if the widget should grab focus when it is clicked with
* the mouse.
*/
bool get_focus_on_click() const;
/** Specifies whether @a widget can be a default widget. See
* grab_default() for details about the meaning of
* “default”.
*
* @newin{2,18}
*
* @param can_default Whether or not @a widget can be a default widget.
*/
void set_can_default(bool can_default = true);
/** Determines whether @a widget can be a default widget. See
* set_can_default().
*
* @newin{2,18}
*
* @return <tt>true</tt> if @a widget can be a default widget, <tt>false</tt> otherwise.
*/
bool get_can_default() const;
/** Determines whether @a widget is the current default widget within its
* toplevel. See set_can_default().
*
* @newin{2,18}
*
* @return <tt>true</tt> if @a widget is the current default widget within
* its toplevel, <tt>false</tt> otherwise.
*/
bool has_default() const;
/** Causes @a widget to become the default widget. @a widget must be able to be
* a default widget; typically you would ensure this yourself
* by calling set_can_default() with a <tt>true</tt> value.
* The default widget is activated when
* the user presses Enter in a window. Default widgets must be
* activatable, that is, activate() should affect them. Note
* that Gtk::Entry widgets require the “activates-default” property
* set to <tt>true</tt> before they activate the default widget when Enter
* is pressed and the Gtk::Entry is focused.
*/
void grab_default();
/** Specifies whether @a widget will be treated as the default widget
* within its toplevel when it has the focus, even if another widget
* is the default.
*
* See grab_default() for details about the meaning of
* “default”.
*
* @newin{2,18}
*
* @param receives_default Whether or not @a widget can be a default widget.
*/
void set_receives_default(bool receives_default = true);
/** Determines whether @a widget is always treated as the default widget
* within its toplevel when it has the focus, even if another widget
* is the default.
*
* See set_receives_default().
*
* @newin{2,18}
*
* @return <tt>true</tt> if @a widget acts as the default widget when focused,
* <tt>false</tt> otherwise.
*/
bool get_receives_default() const;
/** Determines whether the widget is currently grabbing events, so it
* is the only widget receiving input events (keyboard and mouse).
*
* See also gtk_grab_add().
*
* @newin{2,18}
*
* @return <tt>true</tt> if the widget is in the grab_widgets stack.
*/
bool has_grab() const;
/** Returns <tt>true</tt> if @a device has been shadowed by a GTK+
* device grab on another widget, so it would stop sending
* events to @a widget. This may be used in the
* Gtk::Widget::signal_grab_notify() signal to check for specific
* devices. See gtk_device_grab_add().
*
* @newin{3,0}
*
* @param device A Gdk::Device.
* @return <tt>true</tt> if there is an ongoing grab on @a device
* by another Gtk::Widget than @a widget.
*/
bool device_is_shadowed(const Glib::RefPtr<const Gdk::Device>& device);
/** Block events to everything else than this widget and its children. This
* way you can get modal behaviour (usually not recommended). One practical
* example could be when implementing a key-binding widget that needs
* exclusive access to the key combination that the user presses next.
*
* Calls to add_modal_grab should be paired with calls to remove_modal_grab.
*/
void add_modal_grab();
/** Remove the modal grab of the widget in case it was previously grabbed.
*/
void remove_modal_grab();
/** Retrieve the widget which is currently grabbing all events.
*/
static Widget* get_current_modal_grab();
/** Widgets can be named, which allows you to refer to them from a
* CSS file. You can apply a style to widgets with a particular name
* in the CSS file. See the documentation for the CSS syntax (on the
* same page as the docs for Gtk::StyleContext).
*
* Note that the CSS syntax has certain special characters to delimit
* and represent elements in a selector (period, #, >, *...), so using
* these will make your widget impossible to match by name. Any combination
* of alphanumeric symbols, dashes and underscores will suffice.
*
* @param name Name for the widget.
*/
void set_name(const Glib::ustring& name);
void unset_name();
/** Retrieves the name of a widget. See set_name() for the
* significance of widget names.
*
* @return Name of the widget. This string is owned by GTK+ and
* should not be modified or freed.
*/
Glib::ustring get_name() const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** This function is for use in widget implementations. Sets the state
* of a widget (insensitive, prelighted, etc.) Usually you should set
* the state using wrapper functions such as set_sensitive().
*
* Deprecated: 3.0: Use set_state_flags() instead.
*
* @deprecated Use set_state_flags() instead.
*
* @param state New state for @a widget.
*/
void set_state(StateType state);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Returns the widget’s state. See set_state().
*
* @newin{2,18}
*
* Deprecated: 3.0: Use get_state_flags() instead.
*
* @deprecated Use get_state_flags() instead.
*
* @return The state of @a widget.
*/
StateType get_state() const;
#endif // GTKMM_DISABLE_DEPRECATED
/** This function is for use in widget implementations. Turns on flag
* values in the current widget state (insensitive, prelighted, etc.).
*
* This function accepts the values Gtk::STATE_FLAG_DIR_LTR and
* Gtk::STATE_FLAG_DIR_RTL but ignores them. If you want to set the widget's
* direction, use set_direction().
*
* It is worth mentioning that any other state than Gtk::STATE_FLAG_INSENSITIVE,
* will be propagated down to all non-internal children if @a widget is a
* Gtk::Container, while Gtk::STATE_FLAG_INSENSITIVE itself will be propagated
* down to all Gtk::Container children by different means than turning on the
* state flag down the hierarchy, both get_state_flags() and
* is_sensitive() will make use of these.
*
* @newin{3,0}
*
* @param flags State flags to turn on.
* @param clear Whether to clear state before turning on @a flags.
*/
void set_state_flags(StateFlags flags, bool clear = true);
/** This function is for use in widget implementations. Turns off flag
* values for the current widget state (insensitive, prelighted, etc.).
* See set_state_flags().
*
* @newin{3,0}
*
* @param flags State flags to turn off.
*/
void unset_state_flags(StateFlags flags);
/** Returns the widget state as a flag set. It is worth mentioning
* that the effective Gtk::STATE_FLAG_INSENSITIVE state will be
* returned, that is, also based on parent insensitivity, even if
* @a widget itself is sensitive.
*
* Also note that if you are looking for a way to obtain the
* Gtk::StateFlags to pass to a Gtk::StyleContext method, you
* should look at Gtk::StyleContext::get_state().
*
* @newin{3,0}
*
* @return The state flags for widget.
*/
StateFlags get_state_flags() const;
/** Sets the sensitivity of a widget. A widget is sensitive if the user
* can interact with it. Insensitive widgets are “grayed out” and the
* user can’t interact with them. Insensitive widgets are known as
* “inactive”, “disabled”, or “ghosted” in some other toolkits.
*
* @param sensitive <tt>true</tt> to make the widget sensitive.
*/
void set_sensitive(bool sensitive = true);
/** Returns the widget’s sensitivity (in the sense of returning
* the value that has been set using set_sensitive()).
*
* The effective sensitivity of a widget is however determined by both its
* own and its parent widget’s sensitivity. See is_sensitive().
*
* @newin{2,18}
*
* @return <tt>true</tt> if the widget is sensitive.
*/
bool get_sensitive() const;
/** Returns the widget’s effective sensitivity, which means
* it is sensitive itself and also its parent widget is sensitive
*
* @newin{2,18}
*
* @return <tt>true</tt> if the widget is effectively sensitive.
*/
bool is_sensitive() const;
/** Sets the visibility state of @a widget. Note that setting this to
* <tt>true</tt> doesn’t mean the widget is actually viewable, see
* get_visible().
*
* This function simply calls show() or hide()
* but is nicer to use when the visibility of the widget depends on
* some condition.
*
* @newin{2,18}
*
* @param visible Whether the widget should be shown or not.
*/
void set_visible(bool visible = true);
/** Determines whether the widget is visible. If you want to
* take into account whether the widget’s parent is also marked as
* visible, use is_visible() instead.
*
* This function does not check if the widget is obscured in any way.
*
* See set_visible().
*
* @newin{2,18}
*
* @return <tt>true</tt> if the widget is visible.
*/
bool get_visible() const;
/** Determines whether the widget and all its parents are marked as
* visible.
*
* This function does not check if the widget is obscured in any way.
*
* See also get_visible() and set_visible()
*
* @newin{3,8}
*
* @return <tt>true</tt> if the widget and all its parents are visible.
*/
bool is_visible() const;
/** Determines whether @a widget has a Gdk::Window of its own. See
* set_has_window().
*
* @newin{2,18}
*
* @return <tt>true</tt> if @a widget has a window, <tt>false</tt> otherwise.
*/
bool get_has_window() const;
/** Determines whether @a widget is a toplevel widget.
*
* Currently only Gtk::Window and Gtk::Invisible (and out-of-process
* Gtk::Plugs) are toplevel widgets. Toplevel widgets have no parent
* widget.
*
* @newin{2,18}
*
* @return <tt>true</tt> if @a widget is a toplevel, <tt>false</tt> otherwise.
*/
bool get_is_toplevel() const;
/** Determines whether @a widget can be drawn to. A widget can be drawn
* to if it is mapped and visible.
*
* @newin{2,18}
*
* @return <tt>true</tt> if @a widget is drawable, <tt>false</tt> otherwise.
*/
bool get_is_drawable() const;
/** Determines whether @a widget is realized.
*
* @newin{2,20}
*
* @return <tt>true</tt> if @a widget is realized, <tt>false</tt> otherwise.
*/
bool get_realized() const;
/** Whether the widget is mapped.
*
* @newin{2,20}
*
* @return <tt>true</tt> if the widget is mapped, <tt>false</tt> otherwise.
*/
bool get_mapped() const;
/** Sets whether the application intends to draw on the widget in
* an Gtk::Widget::signal_draw() handler.
*
* This is a hint to the widget and does not affect the behavior of
* the GTK+ core; many widgets ignore this flag entirely. For widgets
* that do pay attention to the flag, such as Gtk::EventBox and Gtk::Window,
* the effect is to suppress default themed drawing of the widget's
* background. (Children of the widget will still be drawn.) The application
* is then entirely responsible for drawing the widget background.
*
* Note that the background is still drawn when the widget is mapped.
*
* @param app_paintable <tt>true</tt> if the application will paint on the widget.
*/
void set_app_paintable(bool app_paintable = true);
/** Determines whether the application intends to draw on the widget in
* an Gtk::Widget::signal_draw() handler.
*
* See set_app_paintable()
*
* @newin{2,18}
*
* @return <tt>true</tt> if the widget is app paintable.
*/
bool get_app_paintable() const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** Widgets are double buffered by default; you can use this function
* to turn off the buffering. “Double buffered” simply means that
* gdk_window_begin_draw_frame() and gdk_window_end_draw_frame() are called
* automatically around expose events sent to the
* widget. gdk_window_begin_draw_frame() diverts all drawing to a widget's
* window to an offscreen buffer, and gdk_window_end_draw_frame() draws the
* buffer to the screen. The result is that users see the window
* update in one smooth step, and don’t see individual graphics
* primitives being rendered.
*
* In very simple terms, double buffered widgets don’t flicker,
* so you would only use this function to turn off double buffering
* if you had special needs and really knew what you were doing.
*
* @note if you turn off double-buffering, you have to handle
* expose events, since even the clearing to the background color or
* pixmap will not happen automatically (as it is done in
* gdk_window_begin_draw_frame()).
*
* In 3.10 GTK and GDK have been restructured for translucent drawing. Since
* then expose events for double-buffered widgets are culled into a single
* event to the toplevel GDK window. If you now unset double buffering, you
* will cause a separate rendering pass for every widget. This will likely
* cause rendering problems - in particular related to stacking - and usually
* increases rendering times significantly.
*
* Deprecated: 3.14: This function does not work under non-X11 backends or with
* non-native windows.
* It should not be used in newly written code.
*
* @deprecated This does not work under non-X11 backends, and it should not be used in newly written code.
*
* @param double_buffered <tt>true</tt> to double-buffer a widget.
*/
void set_double_buffered(bool double_buffered = true);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Determines whether the widget is double buffered.
*
* See set_double_buffered()
*
* @newin{2,18}
*
* @deprecated This should not be used in newly written code.
*
* @return <tt>true</tt> if the widget is double buffered.
*/
bool get_double_buffered() const;
#endif // GTKMM_DISABLE_DEPRECATED
/** Sets whether the entire widget is queued for drawing when its size
* allocation changes. By default, this setting is <tt>true</tt> and
* the entire widget is redrawn on every size change. If your widget
* leaves the upper left unchanged when made bigger, turning this
* setting off will improve performance.
*
* Note that for widgets where get_has_window() is <tt>false</tt>
* setting this flag to <tt>false</tt> turns off all allocation on resizing:
* the widget will not even redraw if its position changes; this is to
* allow containers that don’t draw anything to avoid excess
* invalidations. If you set this flag on a widget with no window that
* does draw on @a widget->window, you are
* responsible for invalidating both the old and new allocation of the
* widget when the widget is moved and responsible for invalidating
* regions newly when the widget increases size.
*
* @param redraw_on_allocate If <tt>true</tt>, the entire widget will be redrawn
* when it is allocated to a new size. Otherwise, only the
* new portion of the widget will be redrawn.
*/
void set_redraw_on_allocate(bool redraw_on_allocate = true);
/** Sets whether @a widget should be mapped along with its when its parent
* is mapped and @a widget has been shown with show().
*
* The child visibility can be set for widget before it is added to
* a container with set_parent(), to avoid mapping
* children unnecessary before immediately unmapping them. However
* it will be reset to its default state of <tt>true</tt> when the widget
* is removed from a container.
*
* Note that changing the child visibility of a widget does not
* queue a resize on the widget. Most of the time, the size of
* a widget is computed from all visible children, whether or
* not they are mapped. If this is not the case, the container
* can queue a resize itself.
*
* This function is only useful for container implementations and
* never should be called by an application.
*
* @param visible If <tt>true</tt>, @a widget should be mapped along with its parent.
*/
void set_child_visible(bool visible = true);
/** Gets the value set with set_child_visible().
* If you feel a need to use this function, your code probably
* needs reorganization.
*
* This function is only useful for container implementations and
* never should be called by an application.
*
* @return <tt>true</tt> if the widget is mapped with the parent.
*/
bool get_child_visible() const;
/** Returns the widget’s window if it is realized, <tt>nullptr</tt> otherwise
*
* @newin{2,14}
*
* @return @a widget’s window.
*/
Glib::RefPtr<Gdk::Window> get_window();
/** Returns the widget’s window if it is realized, <tt>nullptr</tt> otherwise
*
* @newin{2,14}
*
* @return @a widget’s window.
*/
Glib::RefPtr<const Gdk::Window> get_window() const;
/** Registers a Gdk::Window with the widget and sets it up so that
* the widget receives events for it. Call unregister_window()
* when destroying the window.
*
* Before 3.8 you needed to call gdk_window_set_user_data() directly to set
* this up. This is now deprecated and you should use register_window()
* instead. Old code will keep working as is, although some new features like
* transparency might not work perfectly.
*
* @newin{3,8}
*
* @param window A Gdk::Window.
*/
void register_window(const Glib::RefPtr<Gdk::Window>& window);
/** Unregisters a Gdk::Window from the widget that was previously set up with
* register_window(). You need to call this when the window is
* no longer used by the widget, such as when you destroy it.
*
* @newin{3,8}
*
* @param window A Gdk::Window.
*/
void unregister_window(const Glib::RefPtr<Gdk::Window>& window);
/** Returns the width that has currently been allocated to @a widget.
* This function is intended to be used when implementing handlers
* for the Gtk::Widget::signal_draw() function.
*
* @return The width of the @a widget.
*/
int get_allocated_width() const;
/** Returns the height that has currently been allocated to @a widget.
* This function is intended to be used when implementing handlers
* for the Gtk::Widget::signal_draw() function.
*
* @return The height of the @a widget.
*/
int get_allocated_height() const;
/** Returns the baseline that has currently been allocated to @a widget.
* This function is intended to be used when implementing handlers
* for the Gtk::Widget::signal_draw() function, and when allocating child
* widgets in Gtk::Widget::size_allocate.
*
* @newin{3,10}
*
* @return The baseline of the @a widget, or -1 if none.
*/
int get_allocated_baseline() const;
/** Retrieves the widget’s allocated size.
*
* This function returns the last values passed to
* size_allocate_with_baseline(). The value differs from
* the size returned in get_allocation() in that functions
* like set_halign() can adjust the allocation, but not
* the value returned by this function.
*
* If a widget is not visible, its allocated size is 0.
*
* @newin{3,20}
*
* @param allocation A pointer to a Gtk::Allocation to copy to.
* @param baseline A pointer to an integer to copy to.
*/
void get_allocated_size(Allocation& allocation, int& baseline) const;
/** Retrieves the widget's location.
* Note, when implementing a Container: a widget's allocation will be its "adjusted" allocation,
* that is, the widget's parent container typically calls size_allocate() with an allocation,
* and that allocation is then adjusted (to handle margin and alignment for example) before
* assignment to the widget. get_allocation() returns the adjusted allocation that was actually
* assigned to the widget. The adjusted allocation is guaranteed to be completely contained
* within the size_allocate() allocation, however. So a Container is guaranteed that its
* children stay inside the assigned bounds, but not that they have exactly the bounds the
* container assigned. There is no way to get the original allocation assigned by
* size_allocate(), since it isn't stored. If a container implementation needs that information
* it will have to track it itself.
*
* @return The widget's allocated area.
*/
Allocation get_allocation() const;
/** Sets the widget’s allocation. This should not be used
* directly, but from within a widget’s size_allocate method.
*
* The allocation set should be the “adjusted” or actual
* allocation. If you’re implementing a Gtk::Container, you want to use
* size_allocate() instead of set_allocation().
* The GtkWidgetClass::adjust_size_allocation virtual method adjusts the
* allocation inside size_allocate() to create an adjusted
* allocation.
*
* @newin{2,18}
*
* @param allocation A pointer to a Gtk::Allocation to copy from.
*/
void set_allocation(const Allocation& allocation);
/** Sets the widget’s clip. This must not be used directly,
* but from within a widget’s size_allocate method.
* It must be called after set_allocation() (or after chaining up
* to the parent class), because that function resets the clip.
*
* The clip set should be the area that @a widget draws on. If @a widget is a
* Gtk::Container, the area must contain all children's clips.
*
* If this function is not called by @a widget during a signal_size_allocate() handler,
* the clip will be set to @a widget's allocation.
*
* @newin{3,14}
*
* @param clip A pointer to a Gtk::Allocation to copy from.
*/
void set_clip(const Allocation& clip);
/** Retrieves the widget’s clip area.
*
* The clip area is the area in which all of the widget's drawing will
* happen. Other toolkits call it the bounding box.
*
* Historically, in GTK+ the clip area has been equal to the allocation
* retrieved via get_allocation().
*
* @newin{3,14}
*/
Allocation get_clip() const;
/** Returns the parent container of @a widget.
*
* @return The parent container of @a widget, or <tt>nullptr</tt>.
*/
Container* get_parent();
/** Returns the parent container of @a widget.
*
* @return The parent container of @a widget, or <tt>nullptr</tt>.
*/
const Container* get_parent() const;
/** Gets @a widget’s parent window.
*
* @return The parent window of @a widget.
*/
Glib::RefPtr<Gdk::Window> get_parent_window();
/** Gets @a widget’s parent window.
*
* @return The parent window of @a widget.
*/
Glib::RefPtr<const Gdk::Window> get_parent_window() const;
/** Sets a non default parent window for @a widget.
*
* For Gtk::Window classes, setting a @a parent_window effects whether
* the window is a toplevel window or can be embedded into other
* widgets.
*
* For Gtk::Window classes, this needs to be called before the
* window is realized.
*
* @param parent_window The new parent window.
*/
void set_parent_window(const Glib::RefPtr<const Gdk::Window>& parent_window);
/** This function is used by custom widget implementations; if you're
* writing an app, you’d use grab_focus() to move the focus
* to a particular widget, and Gtk::Container::set_focus_chain() to
* change the focus tab order. So you may want to investigate those
* functions instead.
*
* child_focus() is called by containers as the user moves
* around the window using keyboard shortcuts. @a direction indicates
* what kind of motion is taking place (up, down, left, right, tab
* forward, tab backward). child_focus() emits the
* Gtk::Widget::signal_focus() signal; widgets override the default handler
* for this signal in order to implement appropriate focus behavior.
*
* The default signal_focus() handler for a widget should return <tt>true</tt> if
* moving in @a direction left the focus on a focusable location inside
* that widget, and <tt>false</tt> if moving in @a direction moved the focus
* outside the widget. If returning <tt>true</tt>, widgets normally
* call grab_focus() to place the focus accordingly;
* if returning <tt>false</tt>, they don’t modify the current focus location.
*
* @param direction Direction of focus movement.
* @return <tt>true</tt> if focus ended up inside @a widget.
*/
bool child_focus(DirectionType direction);
/** This function should be called whenever keyboard navigation within
* a single widget hits a boundary. The function emits the
* Gtk::Widget::signal_keynav_failed() signal on the widget and its return
* value should be interpreted in a way similar to the return value of
* child_focus():
*
* When <tt>true</tt> is returned, stay in the widget, the failed keyboard
* navigation is OK and/or there is nowhere we can/should move the
* focus to.
*
* When <tt>false</tt> is returned, the caller should continue with keyboard
* navigation outside the widget, e.g. by calling
* child_focus() on the widget’s toplevel.
*
* The default signal_keynav_failed() handler returns <tt>true</tt> for
* Gtk::DIR_TAB_FORWARD and Gtk::DIR_TAB_BACKWARD. For the other
* values of Gtk::DirectionType it returns <tt>false</tt>.
*
* Whenever the default handler returns <tt>true</tt>, it also calls
* error_bell() to notify the user of the failed keyboard
* navigation.
*
* A use case for providing an own implementation of signal_keynav_failed()
* (either by connecting to it or by overriding it) would be a row of
* Gtk::Entry widgets where the user should be able to navigate the
* entire row with the cursor keys, as e.g. known from user interfaces
* that require entering license keys.
*
* @newin{2,12}
*
* @param direction Direction of focus movement.
* @return <tt>true</tt> if stopping keyboard navigation is fine, <tt>false</tt>
* if the emitting widget should try to handle the keyboard
* navigation attempt in its parent container(s).
*/
bool keynav_failed(DirectionType direction);
/** Notifies the user about an input-related error on this widget.
* If the Gtk::Settings gtk-error-bell property is true, it calls
* Gdk::Window::beep(), otherwise it does nothing.
*
* Note that the effect of Gdk::Window::beep() can be configured in many
* ways, depending on the windowing backend and the desktop environment
* or window manager that is used.
*
* @newin{2,12}
*/
void error_bell();
/** Sets the minimum size of a widget; that is, the widget’s size
* request will be at least @a width by @a height. You can use this
* function to force a widget to be larger than it normally would be.
*
* In most cases, Gtk::Window::set_default_size() is a better choice for
* toplevel windows than this function; setting the default size will
* still allow users to shrink the window. Setting the size request
* will force them to leave the window at least as large as the size
* request. When dealing with window sizes,
* Gtk::Window::set_geometry_hints() can be a useful function as well.
*
* Note the inherent danger of setting any fixed size - themes,
* translations into other languages, different fonts, and user action
* can all change the appropriate size for a given widget. So, it's
* basically impossible to hardcode a size that will always be
* correct.
*
* The size request of a widget is the smallest size a widget can
* accept while still functioning well and drawing itself correctly.
* However in some strange cases a widget may be allocated less than
* its requested size, and in many cases a widget may be allocated more
* space than it requested.
*
* If the size request in a given direction is -1 (unset), then
* the “natural” size request of the widget will be used instead.
*
* The size request set here does not include any margin from the
* Gtk::Widget properties margin-left, margin-right, margin-top, and
* margin-bottom, but it does include pretty much all other padding
* or border properties set by any subclass of Gtk::Widget.
*
* @param width Width @a widget should request, or -1 to unset.
* @param height Height @a widget should request, or -1 to unset.
*/
void set_size_request(int width = -1, int height = -1);
/** Gets the size request that was explicitly set for the widget using
* set_size_request(). A value of -1 stored in @a width or
* @a height indicates that that dimension has not been set explicitly
* and the natural requisition of the widget will be used instead. See
* set_size_request(). To get the size a widget will
* actually request, call get_preferred_size() instead of
* this function.
*
* @param width Return location for width, or <tt>nullptr</tt>.
* @param height Return location for height, or <tt>nullptr</tt>.
*/
void get_size_request(int& width, int& height) const;
/** Sets the event mask (see Gdk::EventMask) for a widget. The event
* mask determines which events a widget will receive. Keep in mind
* that different widgets have different default event masks, and by
* changing the event mask you may disrupt a widget’s functionality,
* so be careful. This function must be called while a widget is
* unrealized. Consider add_events() for widgets that are
* already realized, or if you want to preserve the existing event
* mask. This function can’t be used with widgets that have no window.
* (See get_has_window()). To get events on those widgets,
* place them inside a Gtk::EventBox and receive events on the event
* box.
*
* @param events Event mask.
*/
void set_events(Gdk::EventMask events);
/** Adds the events in the bitfield @a events to the event mask for
* @a widget. See set_events() and the
* [input handling overview][event-masks] for details.
*
* @param events An event mask, see Gdk::EventMask.
*/
void add_events(Gdk::EventMask events);
/** Sets the device event mask (see Gdk::EventMask) for a widget. The event
* mask determines which events a widget will receive from @a device. Keep
* in mind that different widgets have different default event masks, and by
* changing the event mask you may disrupt a widget’s functionality,
* so be careful. This function must be called while a widget is
* unrealized. Consider add_device_events() for widgets that are
* already realized, or if you want to preserve the existing event
* mask. This function can’t be used with windowless widgets (which return
* <tt>false</tt> from get_has_window());
* to get events on those widgets, place them inside a Gtk::EventBox
* and receive events on the event box.
*
* @newin{3,0}
*
* @param device A Gdk::Device.
* @param events Event mask.
*/
void set_device_events(const Glib::RefPtr<const Gdk::Device>& device, Gdk::EventMask events);
/** Adds the device events in the bitfield @a events to the event mask for
* @a widget. See set_device_events() for details.
*
* @newin{3,0}
*
* @param device A Gdk::Device.
* @param events An event mask, see Gdk::EventMask.
*/
void add_device_events(const Glib::RefPtr<const Gdk::Device>& device, Gdk::EventMask events);
/** Request the @a widget to be rendered partially transparent,
* with opacity 0 being fully transparent and 1 fully opaque. (Opacity values
* are clamped to the [0,1] range.).
* This works on both toplevel widget, and child widgets, although there
* are some limitations:
*
* For toplevel widgets this depends on the capabilities of the windowing
* system. On X11 this has any effect only on X screens with a compositing manager
* running. See is_composited(). On Windows it should work
* always, although setting a window’s opacity after the window has been
* shown causes it to flicker once on Windows.
*
* For child widgets it doesn’t work if any affected widget has a native window, or
* disables double buffering.
*
* @newin{3,8}
*
* @param opacity Desired opacity, between 0 and 1.
*/
void set_opacity(double opacity);
/** Fetches the requested opacity for this widget.
* See set_opacity().
*
* @newin{3,8}
*
* @return The requested opacity for this widget.
*/
double get_opacity() const;
/** Enables or disables a Gdk::Device to interact with @a widget
* and all its children.
*
* It does so by descending through the Gdk::Window hierarchy
* and enabling the same mask that is has for core events
* (i.e. the one that gdk_window_get_events() returns).
*
* @newin{3,0}
*
* @param device A Gdk::Device.
* @param enabled Whether to enable the device.
*/
void set_device_enabled(const Glib::RefPtr<Gdk::Device>& device, bool enabled = true);
/** Returns whether @a device can interact with @a widget and its
* children. See set_device_enabled().
*
* @newin{3,0}
*
* @param device A Gdk::Device.
* @return <tt>true</tt> is @a device is enabled for @a widget.
*/
bool get_device_enabled(const Glib::RefPtr<const Gdk::Device>& device) const;
/** This function returns the topmost widget in the container hierarchy
* @a widget is a part of. If @a widget has no parent widgets, it will be
* returned as the topmost widget. No reference will be added to the
* returned widget; it should not be unreferenced.
*
* Note the difference in behavior vs. get_ancestor();
* `gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)`
* would return
* <tt>nullptr</tt> if @a widget wasn’t inside a toplevel window, and if the
* window was inside a Gtk::Window-derived widget which was in turn
* inside the toplevel Gtk::Window. While the second case may
* seem unlikely, it actually happens when a Gtk::Plug is embedded
* inside a Gtk::Socket within the same application.
*
* To reliably find the toplevel Gtk::Window, use
* get_toplevel() and call is_toplevel()
* on the result.
*
* [C example ellipted]
*
* @return The topmost ancestor of @a widget, or @a widget itself
* if there’s no ancestor.
*/
Container* get_toplevel();
/** This function returns the topmost widget in the container hierarchy
* @a widget is a part of. If @a widget has no parent widgets, it will be
* returned as the topmost widget. No reference will be added to the
* returned widget; it should not be unreferenced.
*
* Note the difference in behavior vs. get_ancestor();
* `gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)`
* would return
* <tt>nullptr</tt> if @a widget wasn’t inside a toplevel window, and if the
* window was inside a Gtk::Window-derived widget which was in turn
* inside the toplevel Gtk::Window. While the second case may
* seem unlikely, it actually happens when a Gtk::Plug is embedded
* inside a Gtk::Socket within the same application.
*
* To reliably find the toplevel Gtk::Window, use
* get_toplevel() and call is_toplevel()
* on the result.
*
* [C example ellipted]
*
* @return The topmost ancestor of @a widget, or @a widget itself
* if there’s no ancestor.
*/
const Container* get_toplevel() const;
/** Gets the first ancestor of @a widget with type @a widget_type. For example,
* `gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets
* the first Gtk::Box that’s an ancestor of @a widget. No reference will be
* added to the returned widget; it should not be unreferenced. See note
* about checking for a toplevel Gtk::Window in the docs for
* get_toplevel().
*
* Note that unlike is_ancestor(), get_ancestor()
* considers @a widget to be an ancestor of itself.
*
* @param widget_type Ancestor type.
* @return The ancestor widget, or <tt>nullptr</tt> if not found.
*/
Widget* get_ancestor(GType widget_type);
/** Gets the first ancestor of @a widget with type @a widget_type. For example,
* `gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets
* the first Gtk::Box that’s an ancestor of @a widget. No reference will be
* added to the returned widget; it should not be unreferenced. See note
* about checking for a toplevel Gtk::Window in the docs for
* get_toplevel().
*
* Note that unlike is_ancestor(), get_ancestor()
* considers @a widget to be an ancestor of itself.
*
* @param widget_type Ancestor type.
* @return The ancestor widget, or <tt>nullptr</tt> if not found.
*/
const Widget* get_ancestor(GType widget_type) const;
/** Gets the visual that will be used to render @a widget.
*
* @return The visual for @a widget.
*/
Glib::RefPtr<Gdk::Visual> get_visual();
/** Get the Gdk::Screen from the toplevel window associated with
* this widget. This function can only be called after the widget
* has been added to a widget hierarchy with a Gtk::Window
* at the top.
*
* In general, you should only create screen specific
* resources when a widget has been realized, and you should
* free those resources when the widget is unrealized.
*
* @newin{2,2}
*
* @return The Gdk::Screen for the toplevel for this widget.
*/
Glib::RefPtr<Gdk::Screen> get_screen();
/** Get the Gdk::Screen from the toplevel window associated with
* this widget. This function can only be called after the widget
* has been added to a widget hierarchy with a Gtk::Window
* at the top.
*
* In general, you should only create screen specific
* resources when a widget has been realized, and you should
* free those resources when the widget is unrealized.
*
* @newin{2,2}
*
* @return The Gdk::Screen for the toplevel for this widget.
*/
Glib::RefPtr<const Gdk::Screen> get_screen() const;
/** Checks whether there is a Gdk::Screen is associated with
* this widget. All toplevel widgets have an associated
* screen, and all widgets added into a hierarchy with a toplevel
* window at the top.
*
* @newin{2,2}
*
* @return <tt>true</tt> if there is a Gdk::Screen associated
* with the widget.
*/
bool has_screen() const;
/** Retrieves the internal scale factor that maps from window coordinates
* to the actual device pixels. On traditional systems this is 1, on
* high density outputs, it can be a higher value (typically 2).
*
* See gdk_window_get_scale_factor().
*
* @newin{3,10}
*
* @return The scale factor for @a widget.
*/
int get_scale_factor() const;
/** Get the Gdk::Display for the toplevel window associated with
* this widget. This function can only be called after the widget
* has been added to a widget hierarchy with a Gtk::Window at the top.
*
* In general, you should only create display specific
* resources when a widget has been realized, and you should
* free those resources when the widget is unrealized.
*
* @newin{2,2}
*
* @return The Gdk::Display for the toplevel for this widget.
*/
Glib::RefPtr<Gdk::Display> get_display();
/** Get the Gdk::Display for the toplevel window associated with
* this widget. This function can only be called after the widget
* has been added to a widget hierarchy with a Gtk::Window at the top.
*
* In general, you should only create display specific
* resources when a widget has been realized, and you should
* free those resources when the widget is unrealized.
*
* @newin{2,2}
*
* @return The Gdk::Display for the toplevel for this widget.
*/
Glib::RefPtr<const Gdk::Display> get_display() const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** Get the root window where this widget is located. This function can
* only be called after the widget has been added to a widget
* hierarchy with Gtk::Window at the top.
*
* The root window is useful for such purposes as creating a popup
* Gdk::Window associated with the window. In general, you should only
* create display specific resources when a widget has been realized,
* and you should free those resources when the widget is unrealized.
*
* @newin{2,2}
*
* Deprecated: 3.12: Use gdk_screen_get_root_window() instead
*
* @deprecated Use Gdk::Screen::get_root_window() instead.
*
* @return The Gdk::Window root window for the toplevel for this widget.
*/
Glib::RefPtr<Gdk::Window> get_root_window();
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Get the root window where this widget is located. This function can
* only be called after the widget has been added to a widget
* hierarchy with Gtk::Window at the top.
*
* The root window is useful for such purposes as creating a popup
* Gdk::Window associated with the window. In general, you should only
* create display specific resources when a widget has been realized,
* and you should free those resources when the widget is unrealized.
*
* @newin{2,2}
*
* Deprecated: 3.12: Use gdk_screen_get_root_window() instead
*
* @deprecated Use Gdk::Screen::get_root_window() instead.
*
* @return The Gdk::Window root window for the toplevel for this widget.
*/
Glib::RefPtr<const Gdk::Window> get_root_window() const;
#endif // GTKMM_DISABLE_DEPRECATED
/** Gets the settings object holding the settings used for this widget.
*
* Note that this function can only be called when the Gtk::Widget
* is attached to a toplevel, since the settings object is specific
* to a particular Gdk::Screen.
*
* @return The relevant Gtk::Settings object.
*/
Glib::RefPtr<Settings> get_settings();
/** Returns the clipboard object for the given selection to
* be used with @a widget. @a widget must have a Gdk::Display
* associated with it, so must be attached to a toplevel
* window.
*
* @newin{2,2}
*
* @param selection A Gdk::Atom which identifies the clipboard
* to use. Gdk::SELECTION_CLIPBOARD gives the
* default clipboard. Another common value
* is Gdk::SELECTION_PRIMARY, which gives
* the primary X selection.
* @return The appropriate clipboard object. If no
* clipboard already exists, a new one will
* be created. Once a clipboard object has
* been created, it is persistent for all time.
*/
Glib::RefPtr<Clipboard> get_clipboard(const Glib::ustring& selection);
/** Returns the clipboard object for the given selection to
* be used with @a widget. @a widget must have a Gdk::Display
* associated with it, so must be attached to a toplevel
* window.
*
* @newin{2,2}
*
* @param selection A Gdk::Atom which identifies the clipboard
* to use. Gdk::SELECTION_CLIPBOARD gives the
* default clipboard. Another common value
* is Gdk::SELECTION_PRIMARY, which gives
* the primary X selection.
* @return The appropriate clipboard object. If no
* clipboard already exists, a new one will
* be created. Once a clipboard object has
* been created, it is persistent for all time.
*/
Glib::RefPtr<const Clipboard> get_clipboard(const Glib::ustring& selection) const;
/** Gets whether the widget would like any available extra horizontal
* space. When a user resizes a Gtk::Window, widgets with expand=<tt>true</tt>
* generally receive the extra space. For example, a list or
* scrollable area or document in your window would often be set to
* expand.
*
* Containers should use compute_expand() rather than
* this function, to see whether a widget, or any of its children,
* has the expand flag set. If any child of a widget wants to
* expand, the parent may ask to expand also.
*
* This function only looks at the widget’s own hexpand flag, rather
* than computing whether the entire widget tree rooted at this widget
* wants to expand.
*
* @return Whether hexpand flag is set.
*/
bool get_hexpand() const;
/** Sets whether the widget would like any available extra horizontal
* space. When a user resizes a Gtk::Window, widgets with expand=<tt>true</tt>
* generally receive the extra space. For example, a list or
* scrollable area or document in your window would often be set to
* expand.
*
* Call this function to set the expand flag if you would like your
* widget to become larger horizontally when the window has extra
* room.
*
* By default, widgets automatically expand if any of their children
* want to expand. (To see if a widget will automatically expand given
* its current children and state, call compute_expand(). A
* container can decide how the expandability of children affects the
* expansion of the container by overriding the compute_expand virtual
* method on Gtk::Widget.).
*
* Setting hexpand explicitly with this function will override the
* automatic expand behavior.
*
* This function forces the widget to expand or not to expand,
* regardless of children. The override occurs because
* set_hexpand() sets the hexpand-set property (see
* set_hexpand_set()) which causes the widget’s hexpand
* value to be used, rather than looking at children and widget state.
*
* @param expand Whether to expand.
*/
void set_hexpand(bool expand = true);
/** Gets whether set_hexpand() has been used to
* explicitly set the expand flag on this widget.
*
* If hexpand is set, then it overrides any computed
* expand value based on child widgets. If hexpand is not
* set, then the expand value depends on whether any
* children of the widget would like to expand.
*
* There are few reasons to use this function, but it’s here
* for completeness and consistency.
*
* @return Whether hexpand has been explicitly set.
*/
bool get_hexpand_set() const;
/** Sets whether the hexpand flag (see get_hexpand()) will
* be used.
*
* The hexpand-set property will be set automatically when you call
* set_hexpand() to set hexpand, so the most likely
* reason to use this function would be to unset an explicit expand
* flag.
*
* If hexpand is set, then it overrides any computed
* expand value based on child widgets. If hexpand is not
* set, then the expand value depends on whether any
* children of the widget would like to expand.
*
* There are few reasons to use this function, but it’s here
* for completeness and consistency.
*
* @param set Value for hexpand-set property.
*/
void set_hexpand_set(bool set = true);
/** Gets whether the widget would like any available extra vertical
* space.
*
* See get_hexpand() for more detail.
*
* @return Whether vexpand flag is set.
*/
bool get_vexpand() const;
/** Sets whether the widget would like any available extra vertical
* space.
*
* See set_hexpand() for more detail.
*
* @param expand Whether to expand.
*/
void set_vexpand(bool expand = true);
/** Gets whether set_vexpand() has been used to
* explicitly set the expand flag on this widget.
*
* See get_hexpand_set() for more detail.
*
* @return Whether vexpand has been explicitly set.
*/
bool get_vexpand_set() const;
/** Sets whether the vexpand flag (see get_vexpand()) will
* be used.
*
* See set_hexpand_set() for more detail.
*
* @param set Value for vexpand-set property.
*/
void set_vexpand_set(bool set = true);
/** Mark @a widget as needing to recompute its expand flags. Call
* this function when setting legacy expand child properties
* on the child of a container.
*
* See compute_expand().
*/
void queue_compute_expand();
/** Computes whether a container should give this widget extra space
* when possible. Containers should check this, rather than
* looking at get_hexpand() or get_vexpand().
*
* This function already checks whether the widget is visible, so
* visibility does not need to be checked separately. Non-visible
* widgets are not expanded.
*
* The computed expand value uses either the expand setting explicitly
* set on the widget itself, or, if none has been explicitly set,
* the widget may expand if some of its children do.
*
* @param orientation Expand direction.
* @return Whether widget tree rooted here should be expanded.
*/
bool compute_expand(Orientation orientation);
/** Returns <tt>true</tt> if @a widget is multiple pointer aware. See
* set_support_multidevice() for more information.
*
* @return <tt>true</tt> if @a widget is multidevice aware.
*/
bool get_support_multidevice() const;
/** Enables or disables multiple pointer awareness. If this setting is <tt>true</tt>,
* @a widget will start receiving multiple, per device enter/leave events. Note
* that if custom Gdk::Windows are created in Gtk::Widget::signal_realize(),
* gdk_window_set_support_multidevice() will have to be called manually on them.
*
* @newin{3,0}
*
* @param support_multidevice <tt>true</tt> to support input from multiple devices.
*/
void set_support_multidevice(bool support_multidevice = true);
#ifdef GTKMM_ATKMM_ENABLED
/** Returns the accessible object that describes the widget to an
* assistive technology.
*
* If accessibility support is not available, this Atk::Object
* instance may be a no-op. Likewise, if no class-specific Atk::Object
* implementation is available for the widget instance in question,
* it will inherit an Atk::Object implementation from the first ancestor
* class for which such an implementation is defined.
*
* The documentation of the
* [ATK](http://developer.gnome.org/atk/stable/)
* library contains more information about accessible objects and their uses.
*
* @return The Atk::Object associated with @a widget.
*/
Glib::RefPtr<Atk::Object> get_accessible();
#endif // GTKMM_ATKMM_ENABLED
#ifdef GTKMM_ATKMM_ENABLED
/** Returns the accessible object that describes the widget to an
* assistive technology.
*
* If accessibility support is not available, this Atk::Object
* instance may be a no-op. Likewise, if no class-specific Atk::Object
* implementation is available for the widget instance in question,
* it will inherit an Atk::Object implementation from the first ancestor
* class for which such an implementation is defined.
*
* The documentation of the
* [ATK](http://developer.gnome.org/atk/stable/)
* library contains more information about accessible objects and their uses.
*
* @return The Atk::Object associated with @a widget.
*/
Glib::RefPtr<const Atk::Object> get_accessible() const;
#endif // GTKMM_ATKMM_ENABLED
/** Gets the value of the Gtk::Widget::property_halign() property.
*
* For backwards compatibility reasons this method will never return
* Gtk::ALIGN_BASELINE, but instead it will convert it to
* Gtk::ALIGN_FILL. Baselines are not supported for horizontal
* alignment.
*
* @return The horizontal alignment of @a widget.
*/
Align get_halign() const;
/** Sets the horizontal alignment of @a widget.
* See the Gtk::Widget::property_halign() property.
*
* @param align The horizontal alignment.
*/
void set_halign(Align align);
/** Gets the value of the Gtk::Widget::property_valign() property.
*
* For backwards compatibility reasons this method will never return
* Gtk::ALIGN_BASELINE, but instead it will convert it to
* Gtk::ALIGN_FILL. If your widget want to support baseline aligned
* children it must use get_valign_with_baseline(), or
* `g_object_get (widget, "valign", &value, <tt>nullptr</tt>)`, which will
* also report the true value.
*
* @return The vertical alignment of @a widget, ignoring baseline alignment.
*/
Align get_valign() const;
/** Gets the value of the Gtk::Widget::property_valign() property, including
* Gtk::ALIGN_BASELINE.
*
* @newin{3,10}
*
* @return The vertical alignment of @a widget.
*/
Align get_valign_with_baseline() const;
/** Sets the vertical alignment of @a widget.
* See the Gtk::Widget::property_valign() property.
*
* @param align The vertical alignment.
*/
void set_valign(Align align);
#ifndef GTKMM_DISABLE_DEPRECATED
/** Gets the value of the Gtk::Widget::property_margin_left() property.
*
* Deprecated: 3.12: Use get_margin_start() instead.
*
* @newin{3,0}
*
* @deprecated Use get_margin_start() instead.
*
* @return The left margin of @a widget.
*/
int get_margin_left() const;
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets the left margin of @a widget.
* See the Gtk::Widget::property_margin_left() property.
*
* Deprecated: 3.12: Use set_margin_start() instead.
*
* @newin{3,0}
*
* @deprecated Use set_margin_start() instead.
*
* @param margin The left margin.
*/
void set_margin_left(int margin);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Gets the value of the Gtk::Widget::property_margin_right() property.
*
* Deprecated: 3.12: Use get_margin_end() instead.
*
* @newin{3,0}
*
* @deprecated Use get_margin_end() instead.
*
* @return The right margin of @a widget.
*/
int get_margin_right() const;
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets the right margin of @a widget.
* See the Gtk::Widget::property_margin_right() property.
*
* Deprecated: 3.12: Use set_margin_end() instead.
*
* @newin{3,0}
*
* @deprecated Use set_margin_end() instead.
*
* @param margin The right margin.
*/
void set_margin_right(int margin);
#endif // GTKMM_DISABLE_DEPRECATED
/** Gets the value of the Gtk::Widget::property_margin_start() property.
*
* @newin{3,12}
*
* @return The start margin of @a widget.
*/
int get_margin_start() const;
/** Sets the start margin of @a widget.
* See the Gtk::Widget::property_margin_start() property.
*
* @newin{3,12}
*
* @param margin The start margin.
*/
void set_margin_start(int margin);
/** Gets the value of the Gtk::Widget::property_margin_end() property.
*
* @newin{3,12}
*
* @return The end margin of @a widget.
*/
int get_margin_end() const;
/** Sets the end margin of @a widget.
* See the Gtk::Widget::property_margin_end() property.
*
* @newin{3,12}
*
* @param margin The end margin.
*/
void set_margin_end(int margin);
/** Gets the value of the Gtk::Widget::property_margin_top() property.
*
* @newin{3,0}
*
* @return The top margin of @a widget.
*/
int get_margin_top() const;
/** Sets the top margin of @a widget.
* See the Gtk::Widget::property_margin_top() property.
*
* @newin{3,0}
*
* @param margin The top margin.
*/
void set_margin_top(int margin);
/** Gets the value of the Gtk::Widget::property_margin_bottom() property.
*
* @newin{3,0}
*
* @return The bottom margin of @a widget.
*/
int get_margin_bottom() const;
/** Sets the bottom margin of @a widget.
* See the Gtk::Widget::property_margin_bottom() property.
*
* @newin{3,0}
*
* @param margin The bottom margin.
*/
void set_margin_bottom(int margin);
/** Returns the event mask (see Gdk::EventMask) for the widget. These are the
* events that the widget will receive.
*
* @note Internally, the widget event mask will be the logical OR of the event
* mask set through set_events() or add_events(), and the
* event mask necessary to cater for every Gtk::EventController created for the
* widget.
*
* @return Event mask for @a widget.
*/
Gdk::EventMask get_events() const;
/** Returns the events mask for the widget corresponding to an specific device. These
* are the events that the widget will receive when @a device operates on it.
*
* @newin{3,0}
*
* @param device A Gdk::Device.
* @return Device event mask for @a widget.
*/
Gdk::EventMask get_device_events(const Glib::RefPtr<const Gdk::Device>& device) const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** Obtains the location of the mouse pointer in widget coordinates.
* Widget coordinates are a bit odd; for historical reasons, they are
* defined as @a widget->window coordinates for widgets that return <tt>true</tt> for
* get_has_window(); and are relative to @a widget->allocation.x,
* @a widget->allocation.y otherwise.
*
* Deprecated: 3.4: Use gdk_window_get_device_position() instead.
*
* @deprecated Use Gdk::Window::get_device_position instead.
*
* @param x Return location for the X coordinate, or <tt>nullptr</tt>.
* @param y Return location for the Y coordinate, or <tt>nullptr</tt>.
*/
void get_pointer(int & x, int & y) const;
#endif // GTKMM_DISABLE_DEPRECATED
/** Determines whether @a widget is somewhere inside @a ancestor, possibly with
* intermediate containers.
*
* @param ancestor Another Gtk::Widget.
* @return <tt>true</tt> if @a ancestor contains @a widget as a child,
* grandchild, great grandchild, etc.
*/
bool is_ancestor(Widget & ancestor) const;
/** Translate coordinates relative to @a src_widget’s allocation to coordinates
* relative to @a dest_widget’s allocations. In order to perform this
* operation, both widgets must be realized, and must share a common
* toplevel.
*
* @param dest_widget A Gtk::Widget.
* @param src_x X position relative to @a src_widget.
* @param src_y Y position relative to @a src_widget.
* @param dest_x Location to store X position relative to @a dest_widget.
* @param dest_y Location to store Y position relative to @a dest_widget.
* @return <tt>false</tt> if either widget was not realized, or there
* was no common ancestor. In this case, nothing is stored in
* * @a dest_x and * @a dest_y. Otherwise <tt>true</tt>.
*/
bool translate_coordinates(Widget& dest_widget, int src_x, int src_y, int& dest_x, int& dest_y);
//deprecated broadly in favour of StyleContext.;
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets the color to use for a widget.
*
* All other style values are left untouched.
*
* This function does not act recursively. Setting the color of a
* container does not affect its children. Note that some widgets that
* you may not think of as containers, for instance Gtk::Buttons,
* are actually containers.
*
* This API is mostly meant as a quick way for applications to
* change a widget appearance. If you are developing a widgets
* library and intend this change to be themeable, it is better
* done by setting meaningful CSS classes in your
* widget/container implementation through Gtk::StyleContext::add_class().
*
* This way, your widget library can install a Gtk::CssProvider
* with the Gtk::STYLE_PROVIDER_PRIORITY_FALLBACK priority in order
* to provide a default styling for those widgets that need so, and
* this theming may fully overridden by the user’s theme.
*
* Note that for complex widgets this may bring in undesired
* results (such as uniform background color everywhere), in
* these cases it is better to fully style such widgets through a
* Gtk::CssProvider with the Gtk::STYLE_PROVIDER_PRIORITY_APPLICATION
* priority.
*
* @newin{3,0}
*
* Deprecated:3.16: Use a custom style provider and style classes instead
*
* @deprecated Use a custom style provider and style classes instead.
*
* @param state The state for which to set the color.
* @param color The color to assign, or <tt>nullptr</tt> to undo the effect
* of previous calls to override_color().
*/
void override_color(const Gdk::RGBA& color, StateFlags state = STATE_FLAG_NORMAL);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Undoes the effect of previous calls to override_color().
*
* @newin{3,0}
* @deprecated Use a custom style provider and style classes instead.
*
* @param state The state for which to use the color of the user's theme.
*/
void unset_color(StateFlags state = STATE_FLAG_NORMAL);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets the background color to use for a widget.
*
* All other style values are left untouched.
* See override_color().
*
* @newin{3,0}
*
* Deprecated: 3.16: This function is not useful in the context of CSS-based
* rendering. If you wish to change the way a widget renders its background
* you should use a custom CSS style, through an application-specific
* Gtk::StyleProvider and a CSS style class. You can also override the default
* drawing of a widget through the Gtk::Widget::signal_draw() signal, and use Cairo to
* draw a specific color, regardless of the CSS style.
*
* @deprecated Use a custom style provider and style classes instead.
*
* @param state The state for which to set the background color.
* @param color The color to assign, or <tt>nullptr</tt> to undo the effect
* of previous calls to override_background_color().
*/
void override_background_color(const Gdk::RGBA& color, StateFlags state = STATE_FLAG_NORMAL);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Undoes the effect of previous calls to override_background_color().
*
* @newin{3,0}
* @deprecated Use a custom style provider and style classes instead.
*
* @param state The state for which to use the background color of the user's theme.
*/
void unset_background_color(StateFlags state = STATE_FLAG_NORMAL);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets the font to use for a widget. All other style values are
* left untouched. See override_color().
*
* @newin{3,0}
*
* Deprecated: 3.16: This function is not useful in the context of CSS-based
* rendering. If you wish to change the font a widget uses to render its text
* you should use a custom CSS style, through an application-specific
* Gtk::StyleProvider and a CSS style class.
*
* @deprecated Use a custom style provider and style classes instead.
*
* @param font_desc The font description to use, or <tt>nullptr</tt> to undo
* the effect of previous calls to override_font().
*/
void override_font(const Pango::FontDescription& font_desc);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Undoes the effect of previous calls to override_font().
*
* @newin{3,0}
* @deprecated Use a custom style provider and style classes instead.
*/
void unset_font();
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets a symbolic color for a widget.
*
* All other style values are left untouched.
* See override_color() for overriding the foreground
* or background color.
*
* @newin{3,0}
*
* Deprecated: 3.16: This function is not useful in the context of CSS-based
* rendering. If you wish to change the color used to render symbolic icons
* you should use a custom CSS style, through an application-specific
* Gtk::StyleProvider and a CSS style class.
*
* @deprecated Use a custom style provider and style classes instead.
*
* @param name The name of the symbolic color to modify.
* @param color The color to assign (does not need
* to be allocated), or <tt>nullptr</tt> to undo the effect of previous
* calls to override_symbolic_color().
*/
void override_symbolic_color(const Glib::ustring& name, const Gdk::RGBA& color);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Undoes the effect of previous calls to override_symbolic_color().
*
* @newin{3,0}
* @deprecated Use a custom style provider and style classes instead.
*
* @param name The name of the symbolic color to fetch from the user's theme.
*/
void unset_symbolic_color(const Glib::ustring& name);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets the cursor color to use in a widget, overriding the
* cursor-color and secondary-cursor-color
* style properties. All other style values are left untouched.
* See also modify_style().
*
* Note that the underlying properties have the Gdk::Color type,
* so the alpha value in @a primary and @a secondary will be ignored.
*
* @newin{3,0}
*
* Deprecated: 3.16: This function is not useful in the context of CSS-based
* rendering. If you wish to change the color used to render the primary
* and secondary cursors you should use a custom CSS style, through an
* application-specific Gtk::StyleProvider and a CSS style class.
*
* @deprecated Use a custom style provider and style classes instead.
*
* @param cursor The color to use for primary cursor (does not need to be
* allocated), or <tt>nullptr</tt> to undo the effect of previous calls to
* of override_cursor().
* @param secondary_cursor The color to use for secondary cursor (does not
* need to be allocated), or <tt>nullptr</tt> to undo the effect of previous
* calls to of override_cursor().
*/
void override_cursor(const Gdk::RGBA& cursor, const Gdk::RGBA& secondary_cursor);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Undoes the effect of previous calls to override_cursor().
*
* @newin{3,0}
* @deprecated Use a custom style provider and style classes instead.
*/
void unset_cursor();
#endif // GTKMM_DISABLE_DEPRECATED
//deprecated
/** Updates the style context of @a widget and all descendants
* by updating its widget path. Gtk::Containers may want
* to use this on a child when reordering it in a way that a different
* style might apply to it. See also Gtk::Container::get_path_for_child().
*
* @newin{3,0}
*/
void reset_style();
//The parameter name is "the_property_name" to avoid a warning because there is a method with the "property_name" name.
/** Gets the value of a style property of @a widget.
* @param the_property_name The name of a style property.
* @param value Location to return the property value.
*/
template <class PropertyType>
void get_style_property(const Glib::ustring& the_property_name, PropertyType& value) const;
/** Creates a new Pango::Context with the appropriate font map,
* font options, font description, and base direction for drawing
* text for this widget. See also get_pango_context().
*
* @return The new Pango::Context.
*/
Glib::RefPtr<Pango::Context> create_pango_context();
/** Gets a Pango::Context with the appropriate font map, font description,
* and base direction for this widget. Unlike the context returned
* by create_pango_context(), this context is owned by
* the widget (it can be used until the screen for the widget changes
* or the widget is removed from its toplevel), and will be updated to
* match any changes to the widget’s attributes. This can be tracked
* by using the Gtk::Widget::signal_screen_changed() signal on the widget.
*
* @return The Pango::Context for the widget.
*/
Glib::RefPtr<Pango::Context> get_pango_context();
/** Sets the #cairo_font_options_t used for Pango rendering in this widget.
* When not set, the default font options for the Gdk::Screen will be used.
*
* @newin{3,18}
*
* @param options A #cairo_font_options_t, or <tt>nullptr</tt> to unset any
* previously set default font options.
*/
void set_font_options(const ::Cairo::FontOptions& options);
/** Undoes the effect of previous calls to set_font_options().
*
* @newin{3,20}
*/
void unset_font_options();
// This returns a const, so we assume that we must copy it:
/** Returns the #cairo_font_options_t used for Pango rendering. When not set,
* the defaults font options for the Gdk::Screen will be used.
*
* @newin{3,18}
*
* @return The #cairo_font_options_t or <tt>nullptr</tt> if not set.
*/
::Cairo::FontOptions get_font_options() const;
/** Creates a new Pango::Layout with the appropriate font map,
* font description, and base direction for drawing text for
* this widget.
*
* If you keep a Pango::Layout created in this way around, you need
* to re-create it when the widget Pango::Context is replaced.
* This can be tracked by using the Gtk::Widget::signal_screen_changed() signal
* on the widget.
*
* @param text Text to set on the layout (can be <tt>nullptr</tt>).
* @return The new Pango::Layout.
*/
Glib::RefPtr<Pango::Layout> create_pango_layout(const Glib::ustring& text);
//deprecated.
#ifndef GTKMM_DISABLE_DEPRECATED
/** A convenience function that uses the theme engine and style
* settings for @a widget to look up @a stock_id and render it to
* a pixbuf. @a stock_id should be a stock icon ID such as
* Gtk::STOCK_OPEN or Gtk::STOCK_OK. @a size should be a size
* such as Gtk::ICON_SIZE_MENU.
*
* The pixels in the returned Gdk::Pixbuf are shared with the rest of
* the application and should not be modified. The pixbuf should be freed
* after use with Glib::object_unref().
*
* @newin{3,0}
*
* Deprecated: 3.10: Use Gtk::IconTheme::load_icon() instead.
*
* @deprecated Use IconTheme::load_icon() instead.
*
* @param stock_id A stock ID.
* @param size A stock size (Gtk::IconSize). A size of `(GtkIconSize)-1`
* means render at the size of the source and don’t scale (if there are
* multiple source sizes, GTK+ picks one of the available sizes).
* @return A new pixbuf, or <tt>nullptr</tt> if the
* stock ID wasn’t known.
*/
Glib::RefPtr<Gdk::Pixbuf> render_icon_pixbuf(const StockID& stock_id, IconSize size);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets a widgets composite name. The widget must be
* a composite child of its parent; see push_composite_child().
*
* Deprecated: 3.10: Use class_set_template(), or don’t use this API at all.
*
* @deprecated Use gtk_widget_class_set_template(), or don't use this API at all.
*
* @param name The name to set.
*/
void set_composite_name(const Glib::ustring& name);
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** @deprecated Use gtk_widget_class_set_template(), or don't use this API at all.
*/
void unset_composite_name();
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Obtains the composite name of a widget.
*
* Deprecated: 3.10: Use class_set_template(), or don’t use this API at all.
*
* @deprecated Use gtk_widget_class_set_template(), or don't use this API at all.
*
* @return The composite name of @a widget, or an empty string if @a widget is not
* a composite child.
*/
Glib::ustring get_composite_name() const;
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Makes all newly-created widgets as composite children until
* the corresponding pop_composite_child() call.
*
* A composite child is a child that’s an implementation detail of the
* container it’s inside and should not be visible to people using the
* container. Composite children aren’t treated differently by GTK+ (but
* see Gtk::Container::foreach() vs. Gtk::Container::forall()), but e.g. GUI
* builders might want to treat them in a different way.
*
* Deprecated: 3.10: This API never really worked well and was mostly unused, now
* we have a more complete mechanism for composite children, see class_set_template().
*
* @deprecated This API never really worked well and was mostly unused, now we have a more complete mechanism for composite children, see gtk_widget_class_set_template().
*/
static void push_composite_child();
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Cancels the effect of a previous call to push_composite_child().
*
* Deprecated: 3.10: Use class_set_template(), or don’t use this API at all.
*
* @deprecated Use gtk_widget_class_set_template(), or don't use this API at all.
*/
static void pop_composite_child();
#endif // GTKMM_DISABLE_DEPRECATED
/* Directionality of Text */
/** Sets the reading direction on a particular widget. This direction
* controls the primary direction for widgets containing text,
* and also the direction in which the children of a container are
* packed. The ability to set the direction is present in order
* so that correct localization into languages with right-to-left
* reading directions can be done. Generally, applications will
* let the default reading direction present, except for containers
* where the containers are arranged in an order that is explicitly
* visual rather than logical (such as buttons for text justification).
*
* If the direction is set to Gtk::TEXT_DIR_NONE, then the value
* set by set_default_direction() will be used.
*
* @param dir The new direction.
*/
void set_direction(TextDirection dir);
/** Gets the reading direction for a particular widget. See
* set_direction().
*
* @return The reading direction for the widget.
*/
TextDirection get_direction() const;
/** Sets the default reading direction for widgets where the
* direction has not been explicitly set by set_direction().
*
* @param dir The new default direction. This cannot be
* Gtk::TEXT_DIR_NONE.
*/
static void set_default_direction(TextDirection dir);
/** Obtains the current default reading direction. See
* set_default_direction().
*
* @return The current default direction.
*/
static TextDirection get_default_direction();
/** Sets a shape for this widget’s GDK window. This allows for
* transparent windows etc., see gdk_window_shape_combine_region()
* for more information.
*
* @newin{3,0}
*
* @param region Shape to be added, or <tt>nullptr</tt> to remove an existing shape.
*/
void shape_combine_region(const ::Cairo::RefPtr<const ::Cairo::Region>& region);
/** Sets an input shape for this widget’s GDK window. This allows for
* windows which react to mouse click in a nonrectangular region, see
* gdk_window_input_shape_combine_region() for more information.
*
* @newin{3,0}
*
* @param region Shape to be added, or <tt>nullptr</tt> to remove an existing shape.
*/
void input_shape_combine_region(const ::Cairo::RefPtr<const ::Cairo::Region>& region);
/** Returns the Gtk::WidgetPath representing @a widget, if the widget
* is not connected to a toplevel widget, a partial path will be
* created.
*
* @return The Gtk::WidgetPath representing @a widget.
*/
WidgetPath get_path() const;
//deprecated
/** Returns a newly allocated list of the widgets, normally labels, for
* which this widget is the target of a mnemonic (see for example,
* Gtk::Label::set_mnemonic_widget()).
*
* The widgets in the list are not individually referenced. If you
* want to iterate through the list and perform actions involving
* callbacks that might destroy the widgets, you
* must call `g_list_foreach (result,
* (GFunc)g_object_ref, <tt>nullptr</tt>)` first, and then unref all the
* widgets afterwards.
*
* @newin{2,4}
*
* @return The list of
* mnemonic labels; free this list
* with Glib::list_free() when you are done with it.
*/
std::vector<Widget*> list_mnemonic_labels();
/** Returns a newly allocated list of the widgets, normally labels, for
* which this widget is the target of a mnemonic (see for example,
* Gtk::Label::set_mnemonic_widget()).
*
* The widgets in the list are not individually referenced. If you
* want to iterate through the list and perform actions involving
* callbacks that might destroy the widgets, you
* must call `g_list_foreach (result,
* (GFunc)g_object_ref, <tt>nullptr</tt>)` first, and then unref all the
* widgets afterwards.
*
* @newin{2,4}
*
* @return The list of
* mnemonic labels; free this list
* with Glib::list_free() when you are done with it.
*/
std::vector<const Widget*> list_mnemonic_labels() const;
/** Adds a widget to the list of mnemonic labels for
* this widget. (See list_mnemonic_labels()). Note the
* list of mnemonic labels for the widget is cleared when the
* widget is destroyed, so the caller must make sure to update
* its internal state at this point as well.
*
* @newin{2,4}
*
* @param label A Gtk::Widget that acts as a mnemonic label for @a widget.
*/
void add_mnemonic_label(Widget& label);
/** Removes a widget from the list of mnemonic labels for
* this widget. (See list_mnemonic_labels()). The widget
* must have previously been added to the list with
* add_mnemonic_label().
*
* @newin{2,4}
*
* @param label A Gtk::Widget that was previously set as a mnemonic label for
* @a widget with add_mnemonic_label().
*/
void remove_mnemonic_label(Widget& label);
//TODO: Should drag_get_data() be const?
/** @param context The drag context.
* @param target The target (form of the data) to retrieve.
* @param time A timestamp for retrieving the data. This will
* generally be the time received in a Gtk::Widget::signal_drag_motion()"
* or Gtk::Widget::signal_drag_drop()" signal.
*/
void drag_get_data(const Glib::RefPtr<Gdk::DragContext>& context, const Glib::ustring& target, guint32 time);
/**
*/
void drag_highlight();
/**
*/
void drag_unhighlight();
//TODO: Change the defaults? Maybe we should use ALL for DestDefaults. See other drag_dest_set() methods here and in other widgets.
void drag_dest_set(DestDefaults flags = DestDefaults(0), Gdk::DragAction actions = Gdk::DragAction(0));
void drag_dest_set(const std::vector<TargetEntry>& targets, DestDefaults flags = DEST_DEFAULT_ALL, Gdk::DragAction actions = Gdk::ACTION_COPY);
#ifndef GTKMM_DISABLE_DEPRECATED
/** @deprecated No replacement available.
*
* @param proxy_window The window to which to forward drag events.
* @param protocol The drag protocol which the @a proxy_window accepts
* (You can use gdk_drag_get_protocol() to determine this).
* @param use_coordinates If <tt>true</tt>, send the same coordinates to the
* destination, because it is an embedded
* subwindow.
*/
void drag_dest_set_proxy(const Glib::RefPtr<Gdk::Window>& proxy_window, Gdk::DragProtocol protocol, bool use_coordinates);
#endif // GTKMM_DISABLE_DEPRECATED
/**
*/
void drag_dest_unset();
/** Looks for a match between @a context->targets and the
* @a dest_target_list, returning the first matching target, otherwise
* returning Gdk::NONE. @a dest_target_list should usually be the return
* value from gtk_drag_dest_get_target_list(), but some widgets may
* have different valid targets for different parts of the widget; in
* that case, they will have to implement a drag_motion handler that
* passes the correct target list to this function.
*
* @param context Drag context.
* @param target_list List of droppable targets.
* @return First target that the source offers and the dest can accept, or Gdk::NONE.
*/
Glib::ustring drag_dest_find_target(const Glib::RefPtr<Gdk::DragContext>& context, const Glib::RefPtr<TargetList>& target_list) const;
Glib::ustring drag_dest_find_target(const Glib::RefPtr<Gdk::DragContext>& context) const;
/**
*/
Glib::RefPtr<TargetList> drag_dest_get_target_list();
/**
*/
Glib::RefPtr<const TargetList> drag_dest_get_target_list() const;
/** @param target_list List of droppable targets, or <tt>nullptr</tt> for none.
*/
void drag_dest_set_target_list(const Glib::RefPtr<TargetList>& target_list);
/**
*/
void drag_dest_add_text_targets();
/**
*/
void drag_dest_add_image_targets();
/**
*/
void drag_dest_add_uri_targets();
void drag_source_set(const std::vector<TargetEntry>& targets, Gdk::ModifierType start_button_mask = Gdk::MODIFIER_MASK, Gdk::DragAction actions = Gdk::ACTION_COPY);
/** Undoes the effects of gtk_drag_source_set().
*/
void drag_source_unset();
/** Sets the icon that will be used for drags from a particular widget
* from a Gdk::Pixbuf. GTK+ retains a reference for @a pixbuf and will
* release it when it is no longer needed.
*
* @param pixbuf The Gdk::Pixbuf for the drag icon.
*/
void drag_source_set_icon(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);
#ifndef GTKMM_DISABLE_DEPRECATED
/** Sets the icon that will be used for drags from a particular source
* to a stock icon.
*
* Deprecated: 3.10: Use gtk_drag_source_set_icon_name() instead.
*
* @deprecated Use the drag_source_set_icon() that takes a Glib::ustring instead.
*
* @param stock_id The ID of the stock icon to use.
*/
void drag_source_set_icon(const StockID& stock_id);
#endif // GTKMM_DISABLE_DEPRECATED
/** Sets the icon that will be used for drags from a particular source
* to a themed icon. See the docs for Gtk::IconTheme for more details.
*
* @newin{2,8}
*
* @param icon_name Name of icon to use.
*/
void drag_source_set_icon(const Glib::ustring& icon_name);
/** Add the text targets supported by Gtk::SelectionData to
* the target list of the drag source. The targets
* are added with @a info = 0. If you need another value,
* use Gtk::TargetList::add_text_targets() and
* gtk_drag_source_set_target_list().
*
* @newin{2,6}
*/
void drag_source_add_text_targets();
/** Add the URI targets supported by Gtk::SelectionData to
* the target list of the drag source. The targets
* are added with @a info = 0. If you need another value,
* use Gtk::TargetList::add_uri_targets() and
* gtk_drag_source_set_target_list().
*
* @newin{2,6}
*/
void drag_source_add_uri_targets();
/** Add the writable image targets supported by Gtk::SelectionData to
* the target list of the drag source. The targets
* are added with @a info = 0. If you need another value,
* use Gtk::TargetList::add_image_targets() and
* gtk_drag_source_set_target_list().
*
* @newin{2,6}
*/
void drag_source_add_image_targets();
#ifndef GTKMM_DISABLE_DEPRECATED
/** @deprecated Use the drag_begin() that takes x,y coordinates.
*
* @param targets The targets (data formats) in which the
* source can provide the data.
* @param actions A bitmask of the allowed drag actions for this drag.
* @param button The button the user clicked to start the drag.
* @param gdk_event The event that triggered the start of the drag.
*/
Glib::RefPtr<Gdk::DragContext> drag_begin(const Glib::RefPtr<TargetList>& targets, Gdk::DragAction actions, int button, GdkEvent* gdk_event);
#endif // GTKMM_DISABLE_DEPRECATED
/**
*/
Glib::RefPtr<Gdk::DragContext> drag_begin(const Glib::RefPtr<TargetList>& targets, Gdk::DragAction actions, int button, GdkEvent* gdk_event, int x, int y);
/** @param start_x X coordinate of start of drag.
* @param start_y Y coordinate of start of drag.
* @param current_x Current X coordinate.
* @param current_y Current Y coordinate.
*/
bool drag_check_threshold(int start_x, int start_y, int current_x, int current_y);
//These should be a method of Gdk::DragContext, but gdkmm can't depend on gtkmm.
static Widget* drag_get_source_widget(const Glib::RefPtr<Gdk::DragContext>& context);
void drag_set_as_icon(const Glib::RefPtr<Gdk::DragContext>& context, int hot_x, int hot_y);
/** This function works like queue_resize(),
* except that the widget is not invalidated.
*
* @newin{2,4}
*/
void queue_resize_no_redraw();
//TODO: _WRAP_METHOD(GdkFrameClock* get_frame_clock(), gtk_widget_get_frame_clock)
/** Returns the current value of the Gtk::Widget::property_no_show_all() property,
* which determines whether calls to show_all()
* will affect this widget.
*
* @newin{2,4}
*
* @return The current value of the “no-show-all” property.
*/
bool get_no_show_all() const;
/** Sets the Gtk::Widget::property_no_show_all() property, which determines whether
* calls to show_all() will affect this widget.
*
* This is mostly for use in constructing widget hierarchies with externally
* controlled visibility, see Gtk::UIManager.
*
* @newin{2,4}
*
* @param no_show_all The new value for the “no-show-all” property.
*/
void set_no_show_all(bool no_show_all = true);
//Used when implementing containers:
/** This function is useful only when implementing subclasses of
* Gtk::Container.
* Sets the container as the parent of @a widget, and takes care of
* some details such as updating the state and style of the child
* to reflect its new location. The opposite function is
* unparent().
*
* @param parent Parent container.
*/
void set_parent(Widget& parent);
/** This function is only for use in widget implementations.
* Should be called by implementations of the remove method
* on Gtk::Container, to dissociate a child from the container.
*/
void unparent();
//TODO: When exactly do we need to custom containers need to call map() on the child widgets?
//Most containers that derive from GtkContainer do not need to, but GtkNotebook does.
/** This function is only for use in widget implementations. Causes
* a widget to be mapped if it isn’t already.
*/
void map();
/** This function is only for use in widget implementations. Causes
* a widget to be unmapped if it’s currently mapped.
*/
void unmap();
#ifndef GTKMM_DISABLE_DEPRECATED
/** Draws a text caret on @a cr at @a location.
* This is not a style function but merely a convenience function for drawing
* the standard cursor shape.
*
* @deprecated Use StyleContext::render_insertion_cursor() instead.
*/
void draw_insertion_cursor(const ::Cairo::RefPtr< ::Cairo::Context>& cr, const Gdk::Rectangle& location, bool is_primary, TextDirection direction, bool draw_arrow = true);
#endif // GTKMM_DISABLE_DEPRECATED
// Gtk+ 2.12 tooltip API
/** Replaces the default, usually yellow, window used for displaying
* tooltips with @a custom_window. GTK+ will take care of showing and
* hiding @a custom_window at the right moment, to behave likewise as
* the default tooltip window. If @a custom_window is <tt>nullptr</tt>, the default
* tooltip window will be used.
*
* If the custom window should have the default theming it needs to
* have the name “gtk-tooltip”, see set_name().
*
* @newin{2,12}
*
* @param custom_window A Gtk::Window, or <tt>nullptr</tt>.
*/
void set_tooltip_window(Window& custom_window);
/** Returns the Gtk::Window of the current tooltip. This can be the
* GtkWindow created by default, or the custom tooltip window set
* using set_tooltip_window().
*
* @newin{2,12}
*
* @return The Gtk::Window of the current tooltip.
*/
Window* get_tooltip_window();
/** Triggers a tooltip query on the display where the toplevel of @a widget
* is located. See Gtk::Tooltip::trigger_tooltip_query() for more
* information.
*
* @newin{2,12}
*/
void trigger_tooltip_query();
/** Sets @a text as the contents of the tooltip. This function will take
* care of setting Gtk::Widget::property_has_tooltip() to <tt>true</tt> and of the default
* handler for the Gtk::Widget::signal_query_tooltip() signal.
*
* See also the Gtk::Widget::property_tooltip_text() property and Gtk::Tooltip::set_text().
*
* @newin{2,12}
*
* @param text The contents of the tooltip for @a widget.
*/
void set_tooltip_text(const Glib::ustring& text);
/** Gets the contents of the tooltip for @a widget.
*
* @newin{2,12}
*
* @return The tooltip text.
*/
Glib::ustring get_tooltip_text() const;
/** Sets @a markup as the contents of the tooltip, which is marked up with
* the Pango text markup language.
*
* This function will take care of setting GtkWidget:has-tooltip to <tt>true</tt>
* and of the default handler for the GtkWidget::query-tooltip signal.
*
* See also the GtkWidget:tooltip-markup property and
* Gtk::Tooltip::set_markup().
*
* @newin{2,12}
*
* @param markup The contents of the tooltip for @a widget.
*/
void set_tooltip_markup(const Glib::ustring& markup);
/** Gets the contents of the tooltip for @a widget.
*
* @newin{2,12}
*
* @return The tooltip text.
*/
Glib::ustring get_tooltip_markup() const;
/** Sets the has-tooltip property on @a widget to @a has_tooltip. See
* Gtk::Widget::property_has_tooltip() for more information.
*
* @newin{2,12}
*
* @param has_tooltip Whether or not @a widget has a tooltip.
*/
void set_has_tooltip(bool has_tooltip = TRUE);
/** Returns the current value of the has-tooltip property. See
* Gtk::Widget::property_has_tooltip() for more information.
*
* @newin{2,12}
*
* @return Current value of has-tooltip on @a widget.
*/
bool get_has_tooltip() const;
int get_width() const;
int get_height() const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** Whether @a widget can rely on having its alpha channel
* drawn correctly. On X11 this function returns whether a
* compositing manager is running for @a widget’s screen.
*
* Please note that the semantics of this call will change
* in the future if used on a widget that has a composited
* window in its hierarchy (as set by gdk_window_set_composited()).
*
* @newin{2,10}
*
* @deprecated Use Gdk::Screen::is_composited() instead.
*
* @return <tt>true</tt> if the widget can rely on its alpha
* channel being drawn correctly.
*/
bool is_composited() const;
#endif // GTKMM_DISABLE_DEPRECATED
/** Returns whether the widget is currently being destroyed.
* This information can sometimes be used to avoid doing
* unnecessary work.
*
* @return <tt>true</tt> if @a widget is being destroyed.
*/
bool in_destruction() const;
/** Returns the style context associated to @a widget. The returned object is
* guaranteed to be the same for the lifetime of @a widget.
*
* @return A Gtk::StyleContext. This memory is owned by @a widget and
* must not be freed.
*/
Glib::RefPtr<StyleContext> get_style_context();
/** Returns the style context associated to @a widget. The returned object is
* guaranteed to be the same for the lifetime of @a widget.
*
* @return A Gtk::StyleContext. This memory is owned by @a widget and
* must not be freed.
*/
Glib::RefPtr<Gtk::StyleContext> get_style_context() const;
/** Returns the modifier mask the @a widget’s windowing system backend
* uses for a particular purpose.
*
* See gdk_keymap_get_modifier_mask().
*
* @newin{3,4}
*
* @param intent The use case for the modifier mask.
* @return The modifier mask used for @a intent.
*/
Gdk::ModifierType get_modifier_mask(Gdk::ModifierIntent intent);
//TODO: guint gtk_widget_add_tick_callback (GtkWidget *widget, GtkTickCallback callback, gpointer user_data, GDestroyNotify notify);
//TODO: void gtk_widget_remove_tick_callback (GtkWidget *widget, guint id);
//This is mostly only needed by the class itself, so it could be protected,
//but it is sometimes helpful to call it from outside:
/** Inserts @a group into @a widget. Children of @a widget that implement
* Gtk::Actionable can then be associated with actions in @a group by
* setting their “action-name” to
* @a prefix.`action-name`.
*
* If @a group is <tt>nullptr</tt>, a previously inserted group for @a name is removed
* from @a widget.
*
* @newin{3,6}
*
* @param name The prefix for actions in @a group.
* @param group A ActionGroup, or <tt>nullptr</tt>.
*/
void insert_action_group(const Glib::ustring& name, const Glib::RefPtr<Gio::ActionGroup>& group);
/** Removes a group from the widget.
* See insert_action_group().
*
* @param name The prefix for actions.
*
* @newin{3,10}
*/
void remove_action_group(const Glib::ustring& name);
/** Retrieves the ActionGroup that was registered using @a prefix. The resulting
* ActionGroup may have been registered to @a widget or any Gtk::Widget in its
* ancestry.
*
* If no action group was found matching @a prefix, then <tt>nullptr</tt> is returned.
*
* @newin{3,16}
*
* @param prefix The “prefix” of the action group.
* @return A ActionGroup or <tt>nullptr</tt>.
*/
Glib::RefPtr<Gio::ActionGroup> get_action_group(const Glib::ustring& prefix);
/** Retrieves the ActionGroup that was registered using @a prefix. The resulting
* ActionGroup may have been registered to @a widget or any Gtk::Widget in its
* ancestry.
*
* If no action group was found matching @a prefix, then <tt>nullptr</tt> is returned.
*
* @newin{3,16}
*
* @param prefix The “prefix” of the action group.
* @return A ActionGroup or <tt>nullptr</tt>.
*/
Glib::RefPtr<const Gio::ActionGroup> get_action_group(const Glib::ustring& prefix) const;
/** Retrieves a <tt>nullptr</tt>-terminated array of strings containing the prefixes of
* ActionGroup's available to @a widget.
*
* @newin{3,16}
*
* @return A <tt>nullptr</tt>-terminated array of strings.
*/
std::vector<Glib::ustring> list_action_prefixes() const;
/** Sets the font map to use for Pango rendering. When not set, the widget
* will inherit the font map from its parent.
*
* @newin{3,18}
*
* @param font_map A Pango::FontMap, or <tt>nullptr</tt> to unset any previously
* set font map.
*/
void set_font_map(const Glib::RefPtr<Pango::FontMap>& font_map);
/** Gets the font map that has been set with set_font_map().
*
* @newin{3,18}
*
* @return A Pango::FontMap, or <tt>nullptr</tt>.
*/
Glib::RefPtr<Pango::FontMap> get_font_map();
/** Gets the font map that has been set with set_font_map().
*
* @newin{3,18}
*
* @return A Pango::FontMap, or <tt>nullptr</tt>.
*/
Glib::RefPtr<const Pango::FontMap> get_font_map() const;
/**
* @par Slot Prototype:
* <tt>void on_my_%show()</tt>
*
* Flags: Run First
*
* The signal_show() signal is emitted when @a widget is shown, for example with
* Gtk::Widget::show().
*/
Glib::SignalProxy< void > signal_show();
/**
* @par Slot Prototype:
* <tt>void on_my_%hide()</tt>
*
* Flags: Run First
*
* The signal_hide() signal is emitted when @a widget is hidden, for example with
* Gtk::Widget::hide().
*/
Glib::SignalProxy< void > signal_hide();
/// Emitted on mapping of a widget to the screen.
//- See {flags.mapped}.
/**
* @par Slot Prototype:
* <tt>void on_my_%map()</tt>
*
* Flags: Run First
*
* The signal_map() signal is emitted when @a widget is going to be mapped, that is
* when the widget is visible (which is controlled with
* Gtk::Widget::set_visible()) and all its parents up to the toplevel widget
* are also visible. Once the map has occurred, Gtk::Widget::signal_map_event() will
* be emitted.
*
* The signal_map() signal can be used to determine whether a widget will be drawn,
* for instance it can resume an animation that was stopped during the
* emission of Gtk::Widget::signal_unmap().
*/
Glib::SignalProxy< void > signal_map();
//- See {flags.mapped}.
/**
* @par Slot Prototype:
* <tt>void on_my_%unmap()</tt>
*
* Flags: Run First
*
* The signal_unmap() signal is emitted when @a widget is going to be unmapped, which
* means that either it or any of its parents up to the toplevel widget have
* been set as hidden.
*
* As signal_unmap() indicates that a widget will not be shown any longer, it can be
* used to, for example, stop an animation on the widget.
*/
Glib::SignalProxy< void > signal_unmap();
/// Emitted on realization of a widget.
//- See {flags.realized}. This is also responsible for
//- setting {flags.realized} when it is done. Therefore,
//- when overriding the impl method, you should call the
//- default realize method.
/**
* @par Slot Prototype:
* <tt>void on_my_%realize()</tt>
*
* Flags: Run First
*
* The signal_realize() signal is emitted when @a widget is associated with a
* Gdk::Window, which means that Gtk::Widget::realize() has been called or the
* widget has been mapped (that is, it is going to be drawn).
*/
Glib::SignalProxy< void > signal_realize();
//- See {flags.realized}. This should not be called by the user.
//__WRAP(meth|sig|impl,void unrealize_(),gtk_widget_unrealize,"unrealize")
/**
* @par Slot Prototype:
* <tt>void on_my_%unrealize()</tt>
*
* Flags: Run Last
*
* The signal_unrealize() signal is emitted when the Gdk::Window associated with
* @a widget is destroyed, which means that Gtk::Widget::unrealize() has been
* called or the widget has been unmapped (that is, it is going to be
* hidden).
*/
Glib::SignalProxy< void > signal_unrealize();
/**
* @par Slot Prototype:
* <tt>void on_my_%size_allocate(Allocation& allocation)</tt>
*
* Flags: Run First
*
* @param allocation The region which has been
* allocated to the widget.
*/
Glib::SignalProxy< void,Allocation& > signal_size_allocate();
// Changed signals -- inform widget of internal changes.
// We rename parent_set => parent_changed
// and style_set => style_changed
// to avoid confusion with set_parent and set_style.
#ifndef GTKMM_DISABLE_DEPRECATED
/**
* @par Slot Prototype:
* <tt>void on_my_%state_changed(Gtk::StateType previous_state)</tt>
*
* Flags: Run First
*
* The signal_state_changed() signal is emitted when the widget state changes.
* See Gtk::Widget::get_state().
*
* Deprecated: 3.0: Use Gtk::Widget::signal_state_flags_changed() instead.
*
* @deprecated Use signal_state_flags_changed() instead.
*
* @param previous_state The previous state.
*/
Glib::SignalProxy< void,Gtk::StateType > signal_state_changed();
#endif // GTKMM_DISABLE_DEPRECATED
//TODO: Remove no_default_handler when we can break ABI:
/**
* @par Slot Prototype:
* <tt>void on_my_%state_flags_changed(Gtk::StateFlags previous_state_flags)</tt>
*
* Flags: Run First
*
* The signal_state_flags_changed() signal is emitted when the widget state
* changes, see Gtk::Widget::get_state_flags().
*
* @newin{3,0}
*
* @param previous_state_flags The previous state flags.
*/
Glib::SignalProxy< void,Gtk::StateFlags > signal_state_flags_changed();
/// Informs objects that their parent changed.
//- The widget passed is the former parent, which may be 0 if
//- there was no parent. (was parent_set in GTK+)
/**
* @par Slot Prototype:
* <tt>void on_my_%parent_changed(Widget* previous_parent)</tt>
*
* Flags: Run First
*
* The signal_parent_set() signal is emitted when a new parent
* has been set on a widget.
*
* @param previous_parent The previous parent, or <tt>nullptr</tt> if the widget
* just got its initial parent.
*/
Glib::SignalProxy< void,Widget* > signal_parent_changed();
/**
* @par Slot Prototype:
* <tt>void on_my_%hierarchy_changed(Widget* previous_toplevel)</tt>
*
* Flags: Run Last
*
* The signal_hierarchy_changed() signal is emitted when the
* anchored state of a widget changes. A widget is
* “anchored” when its toplevel
* ancestor is a Gtk::Window. This signal is emitted when
* a widget changes from un-anchored to anchored or vice-versa.
*
* @param previous_toplevel The previous toplevel ancestor, or <tt>nullptr</tt>
* if the widget was previously unanchored.
*/
Glib::SignalProxy< void,Widget* > signal_hierarchy_changed();
//uses deprecated GtkStyle.
/**
* @par Slot Prototype:
* <tt>void on_my_%style_updated()</tt>
*
* Flags: Run First
*
* The signal_style_updated() signal is a convenience signal that is emitted when the
* Gtk::StyleContext::signal_changed() signal is emitted on the @a widget's associated
* Gtk::StyleContext as returned by Gtk::Widget::get_style_context().
*
* Note that style-modifying functions like Gtk::Widget::override_color() also
* cause this signal to be emitted.
*
* @newin{3,0}
*/
Glib::SignalProxy< void > signal_style_updated();
/**
* @par Slot Prototype:
* <tt>void on_my_%direction_changed(TextDirection direction)</tt>
*
* Flags: Run First
*
* The signal_direction_changed() signal is emitted when the text direction
* of a widget changes.
*
* @param direction The previous text direction of @a widget.
*/
Glib::SignalProxy< void,TextDirection > signal_direction_changed();
/**
* @par Slot Prototype:
* <tt>void on_my_%grab_notify(bool was_grabbed)</tt>
*
* Flags: Run First
*
* The signal_grab_notify() signal is emitted when a widget becomes
* shadowed by a GTK+ grab (not a pointer or keyboard grab) on
* another widget, or when it becomes unshadowed due to a grab
* being removed.
*
* A widget is shadowed by a gtk_grab_add() when the topmost
* grab widget in the grab stack of its window group is not
* its ancestor.
*
* @param was_grabbed <tt>false</tt> if the widget becomes shadowed, <tt>true</tt>
* if it becomes unshadowed.
*/
Glib::SignalProxy< void,bool > signal_grab_notify();
/**
* @par Slot Prototype:
* <tt>void on_my_%child_notify(GParamSpec* pspec)</tt>
*
* Flags: Run First
*
* The signal_child_notify() signal is emitted for each
* [child property][child-properties] that has
* changed on an object. The signal's detail holds the property name.
*
* @param pspec The ParamSpec of the changed child property.
*/
Glib::SignalProxy< void,GParamSpec* > signal_child_notify();
/**
* @par Slot Prototype:
* <tt>bool on_my_%mnemonic_activate(bool group_cycling)</tt>
*
* Flags: Run Last
*
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,bool > signal_mnemonic_activate();
/**
* @par Slot Prototype:
* <tt>void on_my_%grab_focus()</tt>
*
* Flags: Run Last
*
*
*/
Glib::SignalProxy< void > signal_grab_focus();
/**
* @par Slot Prototype:
* <tt>bool on_my_%focus(DirectionType direction)</tt>
*
* Flags: Run Last
*
* @return <tt>true</tt> to stop other handlers from being invoked for the event. <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,DirectionType > signal_focus();
/**
* @par Slot Prototype:
* <tt>bool on_my_%event(GdkEvent* gdk_event)</tt>
*
* Flags: Run Last
*
* The GTK+ main loop will emit three signals for each GDK event delivered
* to a widget: one generic signal_event() signal, another, more specific,
* signal that matches the type of event delivered (e.g.\ Gtk::Widget::signal_key_press_event()) and finally a generic
* Gtk::Widget::signal_event_after() signal.
*
* @param gdk_event The Gdk::Event which triggered this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event
* and to cancel the emission of the second specific signal_event() signal.
* <tt>false</tt> to propagate the event further and to allow the emission of
* the second signal. The signal_event_after() signal is emitted regardless of
* the return value.
*/
Glib::SignalProxy< bool,GdkEvent* > signal_event();
/**
* @par Slot Prototype:
* <tt>void on_my_%event_after(GdkEvent* gdk_event)</tt>
*
* After the emission of the Gtk::Widget::signal_event() signal and (optionally)
* the second more specific signal, signal_event_after() will be emitted
* regardless of the previous two signals handlers return values.
*
* @param gdk_event The Gdk::Event which triggered this signal.
*/
Glib::SignalProxy< void,GdkEvent* > signal_event_after();
/** Event triggered by user pressing button.
*
* @par Slot Prototype:
* <tt>bool on_my_%button_press_event(GdkEventButton* button_event)</tt>
*
* Flags: Run Last
*
* The signal_button_press_event() signal will be emitted when a button
* (typically from a mouse) is pressed.
*
* To receive this signal, the Gdk::Window associated to the
* widget needs to enable the Gdk::BUTTON_PRESS_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param button_event The Gdk::EventButton which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventButton* > signal_button_press_event();
/** Event triggered by user releasing button.
*
* @par Slot Prototype:
* <tt>bool on_my_%button_release_event(GdkEventButton* release_event)</tt>
*
* Flags: Run Last
*
* The signal_button_release_event() signal will be emitted when a button
* (typically from a mouse) is released.
*
* To receive this signal, the Gdk::Window associated to the
* widget needs to enable the Gdk::BUTTON_RELEASE_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param release_event The Gdk::EventButton which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventButton* > signal_button_release_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%scroll_event(GdkEventScroll* scroll_event)</tt>
*
* Flags: Run Last
*
* The signal_scroll_event() signal is emitted when a button in the 4 to 7
* range is pressed. Wheel mice are usually configured to generate
* button press events for buttons 4 and 5 when the wheel is turned.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::SCROLL_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param scroll_event The Gdk::EventScroll which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventScroll* > signal_scroll_event();
/** Event triggered by user moving pointer.
*
* @par Slot Prototype:
* <tt>bool on_my_%motion_notify_event(GdkEventMotion* motion_event)</tt>
*
* Flags: Run Last
*
* The signal_motion_notify_event() signal is emitted when the pointer moves
* over the widget's Gdk::Window.
*
* To receive this signal, the Gdk::Window associated to the widget
* needs to enable the Gdk::POINTER_MOTION_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param motion_event The Gdk::EventMotion which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventMotion* > signal_motion_notify_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%delete_event(GdkEventAny* any_event)</tt>
*
* Flags: Run Last
*
* The signal_delete_event() signal is emitted if a user requests that
* a toplevel window is closed. The default handler for this signal
* destroys the window. Connecting Gtk::Widget::hide_on_delete() to
* this signal will cause the window to be hidden instead, so that
* it can later be shown again without reconstructing it.
*
* @param any_event The event which triggered this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventAny* > signal_delete_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%draw(const ::Cairo::RefPtr< ::Cairo::Context>& cr)</tt>
*
* Flags: Run Last
*
* This signal is emitted when a widget is supposed to render itself.
* The @a widget's top left corner must be painted at the origin of
* the passed in context and be sized to the values returned by
* Gtk::Widget::get_allocated_width() and
* Gtk::Widget::get_allocated_height().
*
* Signal handlers connected to this signal can modify the cairo
* context passed as @a cr in any way they like and don't need to
* restore it. The signal emission takes care of calling cairo_save()
* before and cairo_restore() after invoking the handler.
*
* The signal handler will get a @a cr with a clip region already set to the
* widget's dirty region, i.e. to the area that needs repainting. Complicated
* widgets that want to avoid redrawing themselves completely can get the full
* extents of the clip region with gdk_cairo_get_clip_rectangle(), or they can
* get a finer-grained representation of the dirty region with
* cairo_copy_clip_rectangle_list().
*
* @newin{3,0}
*
* @param cr The cairo context to draw to.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,const ::Cairo::RefPtr< ::Cairo::Context>& > signal_draw();
/** Event triggered by a key press will widget has focus.
*
* @par Slot Prototype:
* <tt>bool on_my_%key_press_event(GdkEventKey* key_event)</tt>
*
* Flags: Run Last
*
* The signal_key_press_event() signal is emitted when a key is pressed. The signal
* emission will reoccur at the key-repeat rate when the key is kept pressed.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::KEY_PRESS_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param key_event The Gdk::EventKey which triggered this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventKey* > signal_key_press_event();
/** Event triggered by a key release will widget has focus.
*
* @par Slot Prototype:
* <tt>bool on_my_%key_release_event(GdkEventKey* key_event)</tt>
*
* Flags: Run Last
*
* The signal_key_release_event() signal is emitted when a key is released.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::KEY_RELEASE_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param key_event The Gdk::EventKey which triggered this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventKey* > signal_key_release_event();
/** Event triggered by pointer entering widget area.
*
* @par Slot Prototype:
* <tt>bool on_my_%enter_notify_event(GdkEventCrossing* crossing_event)</tt>
*
* Flags: Run Last
*
* The signal_enter_notify_event() will be emitted when the pointer enters
* the @a widget's window.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::ENTER_NOTIFY_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param crossing_event The Gdk::EventCrossing which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventCrossing* > signal_enter_notify_event();
/** Event triggered by pointer leaving widget area.
*
* @par Slot Prototype:
* <tt>bool on_my_%leave_notify_event(GdkEventCrossing* crossing_event)</tt>
*
* Flags: Run Last
*
* The signal_leave_notify_event() will be emitted when the pointer leaves
* the @a widget's window.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::LEAVE_NOTIFY_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param crossing_event The Gdk::EventCrossing which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventCrossing* > signal_leave_notify_event();
/** Event triggered by a window resizing.
*
* @par Slot Prototype:
* <tt>bool on_my_%configure_event(GdkEventConfigure* configure_event)</tt>
*
* Flags: Run Last
*
* The signal_configure_event() signal will be emitted when the size, position or
* stacking of the @a widget's window has changed.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::STRUCTURE_MASK mask. GDK will enable this mask
* automatically for all new windows.
*
* @param configure_event The Gdk::EventConfigure which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventConfigure* > signal_configure_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%focus_in_event(GdkEventFocus* focus_event)</tt>
*
* Flags: Run Last
*
* The signal_focus_in_event() signal will be emitted when the keyboard focus
* enters the @a widget's window.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::FOCUS_CHANGE_MASK mask.
*
* @param focus_event The Gdk::EventFocus which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventFocus* > signal_focus_in_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%focus_out_event(GdkEventFocus* gdk_event)</tt>
*
* Flags: Run Last
*
* The signal_focus_out_event() signal will be emitted when the keyboard focus
* leaves the @a widget's window.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::FOCUS_CHANGE_MASK mask.
*
* @param gdk_event The Gdk::EventFocus which triggered this
* signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventFocus* > signal_focus_out_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%map_event(GdkEventAny* any_event)</tt>
*
* Flags: Run Last
*
* The signal_map_event() signal will be emitted when the @a widget's window is
* mapped. A window is mapped when it becomes visible on the screen.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::STRUCTURE_MASK mask. GDK will enable this mask
* automatically for all new windows.
*
* @param any_event The Gdk::EventAny which triggered this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventAny* > signal_map_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%unmap_event(GdkEventAny* any_event)</tt>
*
* Flags: Run Last
*
* The signal_unmap_event() signal will be emitted when the @a widget's window is
* unmapped. A window is unmapped when it becomes invisible on the screen.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::STRUCTURE_MASK mask. GDK will enable this mask
* automatically for all new windows.
*
* @param any_event The Gdk::EventAny which triggered this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventAny* > signal_unmap_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%property_notify_event(GdkEventProperty* property_event)</tt>
*
* Flags: Run Last
*
* The signal_property_notify_event() signal will be emitted when a property on
* the @a widget's window has been changed or deleted.
*
* To receive this signal, the Gdk::Window associated to the widget needs
* to enable the Gdk::PROPERTY_CHANGE_MASK mask.
*
* @param property_event The Gdk::EventProperty which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventProperty* > signal_property_notify_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%selection_clear_event(GdkEventSelection* selection_event)</tt>
*
* Flags: Run Last
*
* The signal_selection_clear_event() signal will be emitted when the
* the @a widget's window has lost ownership of a selection.
*
* @param selection_event The Gdk::EventSelection which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventSelection* > signal_selection_clear_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%selection_request_event(GdkEventSelection* selection_event)</tt>
*
* Flags: Run Last
*
* The signal_selection_request_event() signal will be emitted when
* another client requests ownership of the selection owned by
* the @a widget's window.
*
* @param selection_event The Gdk::EventSelection which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventSelection* > signal_selection_request_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%selection_notify_event(GdkEventSelection* selection_event)</tt>
*
* Flags: Run Last
*
* @return <tt>true</tt> to stop other handlers from being invoked for the event. <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventSelection* > signal_selection_notify_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%proximity_in_event(GdkEventProximity* proximity_event)</tt>
*
* Flags: Run Last
*
* To receive this signal the Gdk::Window associated to the widget needs
* to enable the Gdk::PROXIMITY_IN_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param proximity_event The Gdk::EventProximity which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventProximity* > signal_proximity_in_event();
/**
* @par Slot Prototype:
* <tt>bool on_my_%proximity_out_event(GdkEventProximity* proximity_event)</tt>
*
* Flags: Run Last
*
* To receive this signal the Gdk::Window associated to the widget needs
* to enable the Gdk::PROXIMITY_OUT_MASK mask.
*
* This signal will be sent to the grab widget if there is one.
*
* @param proximity_event The Gdk::EventProximity which triggered
* this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventProximity* > signal_proximity_out_event();
#ifndef GTKMM_DISABLE_DEPRECATED
/**
* @par Slot Prototype:
* <tt>bool on_my_%visibility_notify_event(GdkEventVisibility* visibility_event)</tt>
*
* Flags: Run Last
*
* The signal_visibility_notify_event() will be emitted when the @a widget's
* window is obscured or unobscured.
*
* To receive this signal the Gdk::Window associated to the widget needs
* to enable the Gdk::VISIBILITY_NOTIFY_MASK mask.
*
* Deprecated: 3.12: Modern composited windowing systems with pervasive
* transparency make it impossible to track the visibility of a window
* reliably, so this signal can not be guaranteed to provide useful
* information.
*
* @deprecated Modern composited windowing systems with pervasive transparency make it impossible to track the visibility of a window reliably, so this signal can not be guaranteed to provide useful information.
*
* @param visibility_event The Gdk::EventVisibility which
* triggered this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventVisibility* > signal_visibility_notify_event();
#endif // GTKMM_DISABLE_DEPRECATED
/**
* @par Slot Prototype:
* <tt>bool on_my_%window_state_event(GdkEventWindowState* window_state_event)</tt>
*
* Flags: Run Last
*
* The signal_window_state_event() will be emitted when the state of the
* toplevel window associated to the @a widget changes.
*
* To receive this signal the Gdk::Window associated to the widget
* needs to enable the Gdk::STRUCTURE_MASK mask. GDK will enable
* this mask automatically for all new windows.
*
* @param window_state_event The Gdk::EventWindowState which
* triggered this signal.
* @return <tt>true</tt> to stop other handlers from being invoked for the
* event. <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventWindowState* > signal_window_state_event();
//We use the optional custom_c_callback parameter with _WRAP_SIGNAL() for some of these,
//so that we can write special code to wrap the non-const SelectionData& output parameters:
/**
* @par Slot Prototype:
* <tt>void on_my_%selection_get(SelectionData& selection_data, guint info, guint time)</tt>
*
* Flags: Run Last
*
*
*/
Glib::SignalProxy< void,SelectionData&,guint,guint > signal_selection_get();
/**
* @par Slot Prototype:
* <tt>void on_my_%selection_received(const SelectionData& selection_data, guint time)</tt>
*
* Flags: Run Last
*
*
*/
Glib::SignalProxy< void,const SelectionData&,guint > signal_selection_received();
/**
* @par Slot Prototype:
* <tt>void on_my_%drag_begin(const Glib::RefPtr<Gdk::DragContext>& context)</tt>
*
* Flags: Run Last
*
* The signal_drag_begin() signal is emitted on the drag source when a drag is
* started. A typical reason to connect to this signal is to set up a
* custom drag icon with e.g. gtk_drag_source_set_icon_pixbuf().
*
* Note that some widgets set up a drag icon in the default handler of
* this signal, so you may have to use Glib::signal_connect_after() to
* override what the default handler did.
*
* @param context The drag context.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gdk::DragContext>& > signal_drag_begin();
/**
* @par Slot Prototype:
* <tt>void on_my_%drag_end(const Glib::RefPtr<Gdk::DragContext>& context)</tt>
*
* Flags: Run Last
*
* The signal_drag_end() signal is emitted on the drag source when a drag is
* finished. A typical reason to connect to this signal is to undo
* things done in Gtk::Widget::signal_drag_begin().
*
* @param context The drag context.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gdk::DragContext>& > signal_drag_end();
/**
* @par Slot Prototype:
* <tt>void on_my_%drag_data_get(const Glib::RefPtr<Gdk::DragContext>& context, SelectionData& selection_data, guint info, guint time)</tt>
*
* Flags: Run Last
*
* The signal_drag_data_get() signal is emitted on the drag source when the drop
* site requests the data which is dragged. It is the responsibility of
* the signal handler to fill @a selection_data with the data in the format which
* is indicated by @a info. See Gtk::SelectionData::set() and
* Gtk::SelectionData::set_text().
*
* @param context The drag context.
* @param selection_data The Gtk::SelectionData to be filled with the dragged data.
* @param info The info that has been registered with the target in the
* Gtk::TargetList.
* @param time The timestamp at which the data was requested.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gdk::DragContext>&,SelectionData&,guint,guint > signal_drag_data_get();
/**
* @par Slot Prototype:
* <tt>void on_my_%drag_data_delete(const Glib::RefPtr<Gdk::DragContext>& context)</tt>
*
* Flags: Run Last
*
* The signal_drag_data_delete() signal is emitted on the drag source when a drag
* with the action Gdk::ACTION_MOVE is successfully completed. The signal
* handler is responsible for deleting the data that has been dropped. What
* "delete" means depends on the context of the drag operation.
*
* @param context The drag context.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gdk::DragContext>& > signal_drag_data_delete();
/**
* @par Slot Prototype:
* <tt>bool on_my_%drag_failed(const Glib::RefPtr<Gdk::DragContext>& context, DragResult result)</tt>
*
* Flags: Run Last
*
* The signal_drag_failed() signal is emitted on the drag source when a drag has
* failed. The signal handler may hook custom code to handle a failed DnD
* operation based on the type of error, it returns <tt>true</tt> is the failure has
* been already handled (not showing the default "drag operation failed"
* animation), otherwise it returns <tt>false</tt>.
*
* @newin{2,12}
*
* @param context The drag context.
* @param result The result of the drag operation.
* @return <tt>true</tt> if the failed drag operation has been already handled.
*/
Glib::SignalProxy< bool,const Glib::RefPtr<Gdk::DragContext>&,DragResult > signal_drag_failed();
/**
* @par Slot Prototype:
* <tt>void on_my_%drag_leave(const Glib::RefPtr<Gdk::DragContext>& context, guint time)</tt>
*
* Flags: Run Last
*
* The signal_drag_leave() signal is emitted on the drop site when the cursor
* leaves the widget. A typical reason to connect to this signal is to
* undo things done in Gtk::Widget::signal_drag_motion(), e.g. undo highlighting
* with gtk_drag_unhighlight().
*
*
* Likewise, the Gtk::Widget::signal_drag_leave() signal is also emitted before the
* signal_drag_drop() signal, for instance to allow cleaning up of a preview item
* created in the Gtk::Widget::signal_drag_motion() signal handler.
*
* @param context The drag context.
* @param time The timestamp of the motion event.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gdk::DragContext>&,guint > signal_drag_leave();
/**
* @par Slot Prototype:
* <tt>bool on_my_%drag_motion(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, guint time)</tt>
*
* Flags: Run Last
*
* The signal_drag_motion() signal is emitted on the drop site when the user
* moves the cursor over the widget during a drag. The signal handler
* must determine whether the cursor position is in a drop zone or not.
* If it is not in a drop zone, it returns <tt>false</tt> and no further processing
* is necessary. Otherwise, the handler returns <tt>true</tt>. In this case, the
* handler is responsible for providing the necessary information for
* displaying feedback to the user, by calling gdk_drag_status().
*
* If the decision whether the drop will be accepted or rejected can't be
* made based solely on the cursor position and the type of the data, the
* handler may inspect the dragged data by calling gtk_drag_get_data() and
* defer the gdk_drag_status() call to the Gtk::Widget::signal_drag_data_received()
* handler. Note that you must pass Gtk::DEST_DEFAULT_DROP,
* Gtk::DEST_DEFAULT_MOTION or Gtk::DEST_DEFAULT_ALL to gtk_drag_dest_set()
* when using the drag-motion signal that way.
*
* Also note that there is no drag-enter signal. The drag receiver has to
* keep track of whether he has received any drag-motion signals since the
* last Gtk::Widget::signal_drag_leave() and if not, treat the drag-motion signal as
* an "enter" signal. Upon an "enter", the handler will typically highlight
* the drop site with gtk_drag_highlight().
*
* [C example ellipted]
*
* @param context The drag context.
* @param x The x coordinate of the current cursor position.
* @param y The y coordinate of the current cursor position.
* @param time The timestamp of the motion event.
* @return Whether the cursor position is in a drop zone.
*/
Glib::SignalProxy< bool,const Glib::RefPtr<Gdk::DragContext>&,int,int,guint > signal_drag_motion();
/**
* @par Slot Prototype:
* <tt>bool on_my_%drag_drop(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, guint time)</tt>
*
* Flags: Run Last
*
* The signal_drag_drop() signal is emitted on the drop site when the user drops
* the data onto the widget. The signal handler must determine whether
* the cursor position is in a drop zone or not. If it is not in a drop
* zone, it returns <tt>false</tt> and no further processing is necessary.
* Otherwise, the handler returns <tt>true</tt>. In this case, the handler must
* ensure that gtk_drag_finish() is called to let the source know that
* the drop is done. The call to gtk_drag_finish() can be done either
* directly or in a Gtk::Widget::signal_drag_data_received() handler which gets
* triggered by calling gtk_drag_get_data() to receive the data for one
* or more of the supported targets.
*
* @param context The drag context.
* @param x The x coordinate of the current cursor position.
* @param y The y coordinate of the current cursor position.
* @param time The timestamp of the motion event.
* @return Whether the cursor position is in a drop zone.
*/
Glib::SignalProxy< bool,const Glib::RefPtr<Gdk::DragContext>&,int,int,guint > signal_drag_drop();
/**
* @par Slot Prototype:
* <tt>void on_my_%drag_data_received(const Glib::RefPtr<Gdk::DragContext>& context, int x, int y, const SelectionData& selection_data, guint info, guint time)</tt>
*
* Flags: Run Last
*
* The signal_drag_data_received() signal is emitted on the drop site when the
* dragged data has been received. If the data was received in order to
* determine whether the drop will be accepted, the handler is expected
* to call gdk_drag_status() and not finish the drag.
* If the data was received in response to a Gtk::Widget::signal_drag_drop() signal
* (and this is the last target to be received), the handler for this
* signal is expected to process the received data and then call
* gtk_drag_finish(), setting the @a success parameter depending on
* whether the data was processed successfully.
*
* Applications must create some means to determine why the signal was emitted
* and therefore whether to call gdk_drag_status() or gtk_drag_finish().
*
* The handler may inspect the selected action with
* gdk_drag_context_get_selected_action() before calling
* gtk_drag_finish(), e.g. to implement Gdk::ACTION_ASK as
* shown in the following example:
*
* [C example ellipted]
*
* @param context The drag context.
* @param x Where the drop happened.
* @param y Where the drop happened.
* @param selection_data The received data.
* @param info The info that has been registered with the target in the
* Gtk::TargetList.
* @param time The timestamp at which the data was received.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gdk::DragContext>&,int,int,const SelectionData&,guint,guint > signal_drag_data_received();
/**
* @par Slot Prototype:
* <tt>void on_my_%screen_changed(const Glib::RefPtr<Gdk::Screen>& previous_screen)</tt>
*
* Flags: Run Last
*
* The signal_screen_changed() signal gets emitted when the
* screen of a widget has changed.
*
* @param previous_screen The previous screen, or <tt>nullptr</tt> if the
* widget was not associated with a screen before.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gdk::Screen>& > signal_screen_changed();
#ifndef GTKMM_DISABLE_DEPRECATED
/**
* @par Slot Prototype:
* <tt>void on_my_%composited_changed()</tt>
*
* Flags: Run Last
*
* The signal_composited_changed() signal is emitted when the composited
* status of @a widgets screen changes.
* See gdk_screen_is_composited().
*
* @deprecated Use Gdk::Screen::signal_composited_changed() instead.
*/
Glib::SignalProxy< void > signal_composited_changed();
#endif // GTKMM_DISABLE_DEPRECATED
//TODO: The signal_id is very C-like here:
//_WRAP_SIGNAL(bool can_activate_accel(guint signal_id), "can_activate_accel")
// TODO: Remove no_default_handler when we can break ABI:
/**
* @par Slot Prototype:
* <tt>bool on_my_%popup_menu()</tt>
*
* Flags: Run Last
*
* This signal gets emitted whenever a widget should pop up a context
* menu. This usually happens through the standard key binding mechanism;
* by pressing a certain key while a widget is focused, the user can cause
* the widget to pop up a menu. For example, the Gtk::Entry widget creates
* a menu with clipboard commands. See the
* [Popup Menu Migration Checklist][checklist-popup-menu]
* for an example of how to use this signal.
*
* @return <tt>true</tt> if a menu was activated.
*/
Glib::SignalProxy< bool > signal_popup_menu();
//Note that popup-menu is a keybinding signal, but is really meant to be wrapped.
//Keybinding signals:
// TODO: Remove no_default_handler when we can break ABI:
/**
* @par Slot Prototype:
* <tt>bool on_my_%query_tooltip(int x, int y, bool keyboard_tooltip, const Glib::RefPtr<Tooltip>& tooltip)</tt>
*
* Flags: Run Last
*
* Emitted when Gtk::Widget::property_has_tooltip() is <tt>true</tt> and the hover timeout
* has expired with the cursor hovering "above" @a widget; or emitted when @a widget got
* focus in keyboard mode.
*
* Using the given coordinates, the signal handler should determine
* whether a tooltip should be shown for @a widget. If this is the case
* <tt>true</tt> should be returned, <tt>false</tt> otherwise. Note that if
* @a keyboard_tooltip is <tt>true</tt>, the values of @a x and @a y are undefined and
* should not be used.
*
* The signal handler is free to manipulate @a tooltip with the therefore
* destined function calls.
*
* @newin{2,12}
*
* @param x The x coordinate of the cursor position where the request has
* been emitted, relative to @a widget's left side.
* @param y The y coordinate of the cursor position where the request has
* been emitted, relative to @a widget's top.
* @param keyboard_tooltip <tt>true</tt> if the tooltip was triggered using the keyboard.
* @param tooltip A Gtk::Tooltip.
* @return <tt>true</tt> if @a tooltip should be shown right now, <tt>false</tt> otherwise.
*/
Glib::SignalProxy< bool,int,int,bool,const Glib::RefPtr<Tooltip>& > signal_query_tooltip();
//(This was added to GTK+ 2.8 but forgotten by us until gtkmm 2.13/14):
/**
* @par Slot Prototype:
* <tt>bool on_my_%grab_broken_event(GdkEventGrabBroken* grab_broken_event)</tt>
*
* Flags: Run Last
*
* Emitted when a pointer or keyboard grab on a window belonging
* to @a widget gets broken.
*
* On X11, this happens when the grab window becomes unviewable
* (i.e. it or one of its ancestors is unmapped), or if the same
* application grabs the pointer or keyboard again.
*
* @newin{2,8}
*
* @param grab_broken_event The Gdk::EventGrabBroken event.
* @return <tt>true</tt> to stop other handlers from being invoked for
* the event. <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventGrabBroken* > signal_grab_broken_event();
// TODO: Remove no_default_handler when we can break ABI:
/**
* @par Slot Prototype:
* <tt>bool on_my_%damage_event(GdkEventExpose* expose_event)</tt>
*
* Flags: Run Last
*
* Emitted when a redirected window belonging to @a widget gets drawn into.
* The region/area members of the event shows what area of the redirected
* drawable was drawn into.
*
* @newin{2,14}
*
* @param expose_event The Gdk::EventExpose event.
* @return <tt>true</tt> to stop other handlers from being invoked for the event.
* <tt>false</tt> to propagate the event further.
*/
Glib::SignalProxy< bool,GdkEventExpose* > signal_damage_event();
// TODO: Remove no_default_handler when we can break ABI:
/**
* @par Slot Prototype:
* <tt>bool on_my_%touch_event(GdkEventTouch* touch_event)</tt>
*
* Flags: Run Last
*
*/
Glib::SignalProxy< bool,GdkEventTouch* > signal_touch_event();
/** The name of the widget.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Glib::ustring > property_name() ;
/** The name of the widget.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::ustring > property_name() const;
/** The parent widget of this widget. Must be a Container widget.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Container* > property_parent() ;
/** The parent widget of this widget. Must be a Container widget.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Container* > property_parent() const;
/** Override for width request of the widget, or -1 if natural request should be used.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_width_request() ;
/** Override for width request of the widget, or -1 if natural request should be used.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_width_request() const;
/** Override for height request of the widget, or -1 if natural request should be used.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_height_request() ;
/** Override for height request of the widget, or -1 if natural request should be used.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_height_request() const;
/** Whether the widget is visible.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_visible() ;
/** Whether the widget is visible.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_visible() const;
/** Whether the widget responds to input.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_sensitive() ;
/** Whether the widget responds to input.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_sensitive() const;
/** Whether the application will paint directly on the widget.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_app_paintable() ;
/** Whether the application will paint directly on the widget.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_app_paintable() const;
/** Whether the widget can accept the input focus.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_can_focus() ;
/** Whether the widget can accept the input focus.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_can_focus() const;
/** Whether the widget has the input focus.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_has_focus() ;
/** Whether the widget has the input focus.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_has_focus() const;
/** Whether the widget is the focus widget within the toplevel.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_is_focus() ;
/** Whether the widget is the focus widget within the toplevel.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_is_focus() const;
/** Whether the widget should grab focus when it is clicked with the mouse.
*
* This property is only relevant for widgets that can take focus.
*
* Before 3.20, several widgets (GtkButton, GtkFileChooserButton,
* GtkComboBox) implemented this property individually.
*
* @newin{3,20}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_focus_on_click() ;
/** Whether the widget should grab focus when it is clicked with the mouse.
*
* This property is only relevant for widgets that can take focus.
*
* Before 3.20, several widgets (GtkButton, GtkFileChooserButton,
* GtkComboBox) implemented this property individually.
*
* @newin{3,20}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_focus_on_click() const;
/** Whether the widget can be the default widget.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_can_default() ;
/** Whether the widget can be the default widget.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_can_default() const;
/** Whether the widget is the default widget.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_has_default() ;
/** Whether the widget is the default widget.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_has_default() const;
/** If TRUE, the widget will receive the default action when it is focused.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_receives_default() ;
/** If TRUE, the widget will receive the default action when it is focused.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_receives_default() const;
/** Whether the widget is part of a composite widget.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_composite_child() const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** The style of the widget, which contains information about how it will look (colors, etc).
*
* Deprecated: Use Gtk::StyleContext instead
*
* @deprecated Don't use this API. There is no Style class in gtkmm 3.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Glib::RefPtr<Style> > property_style() ;
/** The style of the widget, which contains information about how it will look (colors, etc).
*
* Deprecated: Use Gtk::StyleContext instead
*
* @deprecated Don't use this API. There is no Style class in gtkmm 3.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Style> > property_style() const;
#endif // GTKMM_DISABLE_DEPRECATED
/** The event mask that decides what kind of GdkEvents this widget gets.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Gdk::EventMask > property_events() ;
/** The event mask that decides what kind of GdkEvents this widget gets.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Gdk::EventMask > property_events() const;
/** Enables or disables the emission of Gtk::Widget::signal_query_tooltip() on @a widget.
* A value of <tt>true</tt> indicates that @a widget can have a tooltip, in this case
* the widget will be queried using Gtk::Widget::signal_query_tooltip() to determine
* whether it will provide a tooltip or not.
*
* Note that setting this property to <tt>true</tt> for the first time will change
* the event masks of the GdkWindows of this widget to include leave-notify
* and motion-notify events. This cannot and will not be undone when the
* property is set to <tt>false</tt> again.
*
* @newin{2,12}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_has_tooltip() ;
/** Enables or disables the emission of Gtk::Widget::signal_query_tooltip() on @a widget.
* A value of <tt>true</tt> indicates that @a widget can have a tooltip, in this case
* the widget will be queried using Gtk::Widget::signal_query_tooltip() to determine
* whether it will provide a tooltip or not.
*
* Note that setting this property to <tt>true</tt> for the first time will change
* the event masks of the GdkWindows of this widget to include leave-notify
* and motion-notify events. This cannot and will not be undone when the
* property is set to <tt>false</tt> again.
*
* @newin{2,12}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_has_tooltip() const;
/** Sets the text of tooltip to be the given string, which is marked up
* with the [Pango text markup language][PangoMarkupFormat].
* Also see Gtk::Tooltip::set_markup().
*
* This is a convenience property which will take care of getting the
* tooltip shown if the given string is not <tt>nullptr</tt>: Gtk::Widget::property_has_tooltip()
* will automatically be set to <tt>true</tt> and there will be taken care of
* Gtk::Widget::signal_query_tooltip() in the default signal handler.
*
* Note that if both Gtk::Widget::property_tooltip_text() and Gtk::Widget::property_tooltip_markup()
* are set, the last one wins.
*
* @newin{2,12}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Glib::ustring > property_tooltip_markup() ;
/** Sets the text of tooltip to be the given string, which is marked up
* with the [Pango text markup language][PangoMarkupFormat].
* Also see Gtk::Tooltip::set_markup().
*
* This is a convenience property which will take care of getting the
* tooltip shown if the given string is not <tt>nullptr</tt>: Gtk::Widget::property_has_tooltip()
* will automatically be set to <tt>true</tt> and there will be taken care of
* Gtk::Widget::signal_query_tooltip() in the default signal handler.
*
* Note that if both Gtk::Widget::property_tooltip_text() and Gtk::Widget::property_tooltip_markup()
* are set, the last one wins.
*
* @newin{2,12}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::ustring > property_tooltip_markup() const;
/** Sets the text of tooltip to be the given string.
*
* Also see Gtk::Tooltip::set_text().
*
* This is a convenience property which will take care of getting the
* tooltip shown if the given string is not <tt>nullptr</tt>: Gtk::Widget::property_has_tooltip()
* will automatically be set to <tt>true</tt> and there will be taken care of
* Gtk::Widget::signal_query_tooltip() in the default signal handler.
*
* Note that if both Gtk::Widget::property_tooltip_text() and Gtk::Widget::property_tooltip_markup()
* are set, the last one wins.
*
* @newin{2,12}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Glib::ustring > property_tooltip_text() ;
/** Sets the text of tooltip to be the given string.
*
* Also see Gtk::Tooltip::set_text().
*
* This is a convenience property which will take care of getting the
* tooltip shown if the given string is not <tt>nullptr</tt>: Gtk::Widget::property_has_tooltip()
* will automatically be set to <tt>true</tt> and there will be taken care of
* Gtk::Widget::signal_query_tooltip() in the default signal handler.
*
* Note that if both Gtk::Widget::property_tooltip_text() and Gtk::Widget::property_tooltip_markup()
* are set, the last one wins.
*
* @newin{2,12}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::ustring > property_tooltip_text() const;
/** The widget's window if it is realized, <tt>nullptr</tt> otherwise.
*
* @newin{2,14}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Gdk::Window> > property_window() const;
/** Whether gtk_widget_show_all() should not affect this widget.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_no_show_all() ;
/** Whether gtk_widget_show_all() should not affect this widget.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_no_show_all() const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** Whether the widget is double buffered.
*
* @newin{2,18}
*
* Deprecated: 3.14: Widgets should not use this property.
*
* @deprecated Widgets should not use this property.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_double_buffered() ;
/** Whether the widget is double buffered.
*
* @newin{2,18}
*
* Deprecated: 3.14: Widgets should not use this property.
*
* @deprecated Widgets should not use this property.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_double_buffered() const;
#endif // GTKMM_DISABLE_DEPRECATED
/** How to distribute horizontal space if widget gets extra space, see Gtk::Align
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Align > property_halign() ;
/** How to distribute horizontal space if widget gets extra space, see Gtk::Align
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Align > property_halign() const;
/** How to distribute vertical space if widget gets extra space, see Gtk::Align
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Align > property_valign() ;
/** How to distribute vertical space if widget gets extra space, see Gtk::Align
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Align > property_valign() const;
#ifndef GTKMM_DISABLE_DEPRECATED
/** Margin on left side of widget.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* Deprecated: 3.12: Use Gtk::Widget::property_margin_start() instead.
*
* @newin{3,0}
*
* @deprecated Use property_margin_start() instead.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_margin_left() ;
/** Margin on left side of widget.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* Deprecated: 3.12: Use Gtk::Widget::property_margin_start() instead.
*
* @newin{3,0}
*
* @deprecated Use property_margin_start() instead.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_margin_left() const;
#endif // GTKMM_DISABLE_DEPRECATED
#ifndef GTKMM_DISABLE_DEPRECATED
/** Margin on right side of widget.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* Deprecated: 3.12: Use Gtk::Widget::property_margin_end() instead.
*
* @newin{3,0}
*
* @deprecated Use property_margin_end() instead.
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_margin_right() ;
/** Margin on right side of widget.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* Deprecated: 3.12: Use Gtk::Widget::property_margin_end() instead.
*
* @newin{3,0}
*
* @deprecated Use property_margin_end() instead.
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_margin_right() const;
#endif // GTKMM_DISABLE_DEPRECATED
/** Margin on start of widget, horizontally. This property supports
* left-to-right and right-to-left text directions.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* @newin{3,12}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_margin_start() ;
/** Margin on start of widget, horizontally. This property supports
* left-to-right and right-to-left text directions.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* @newin{3,12}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_margin_start() const;
/** Margin on end of widget, horizontally. This property supports
* left-to-right and right-to-left text directions.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* @newin{3,12}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_margin_end() ;
/** Margin on end of widget, horizontally. This property supports
* left-to-right and right-to-left text directions.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* @newin{3,12}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_margin_end() const;
/** Margin on top side of widget.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_margin_top() ;
/** Margin on top side of widget.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_margin_top() const;
/** Margin on bottom side of widget.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_margin_bottom() ;
/** Margin on bottom side of widget.
*
* This property adds margin outside of the widget's normal size
* request, the margin will be added in addition to the size from
* Gtk::Widget::set_size_request() for example.
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_margin_bottom() const;
/** Sets all four sides' margin at once. If read, returns max
* margin on any side.
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_margin() ;
/** Sets all four sides' margin at once. If read, returns max
* margin on any side.
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_margin() const;
/** Whether to expand horizontally. See Gtk::Widget::set_hexpand().
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_hexpand() ;
/** Whether to expand horizontally. See Gtk::Widget::set_hexpand().
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_hexpand() const;
/** Whether to use the Gtk::Widget::property_hexpand() property. See Gtk::Widget::get_hexpand_set().
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_hexpand_set() ;
/** Whether to use the Gtk::Widget::property_hexpand() property. See Gtk::Widget::get_hexpand_set().
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_hexpand_set() const;
/** Whether to expand vertically. See Gtk::Widget::set_vexpand().
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_vexpand() ;
/** Whether to expand vertically. See Gtk::Widget::set_vexpand().
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_vexpand() const;
/** Whether to use the Gtk::Widget::property_vexpand() property. See Gtk::Widget::get_vexpand_set().
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_vexpand_set() ;
/** Whether to use the Gtk::Widget::property_vexpand() property. See Gtk::Widget::get_vexpand_set().
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_vexpand_set() const;
/** Whether to expand in both directions. Setting this sets both Gtk::Widget::property_hexpand() and Gtk::Widget::property_vexpand()
*
* @newin{3,0}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< bool > property_expand() ;
/** Whether to expand in both directions. Setting this sets both Gtk::Widget::property_hexpand() and Gtk::Widget::property_vexpand()
*
* @newin{3,0}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< bool > property_expand() const;
/** The requested opacity of the widget. See Gtk::Widget::set_opacity() for
* more details about window opacity.
*
* Before 3.8 this was only available in GtkWindow
*
* @newin{3,8}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< double > property_opacity() ;
/** The requested opacity of the widget. See Gtk::Widget::set_opacity() for
* more details about window opacity.
*
* Before 3.8 this was only available in GtkWindow
*
* @newin{3,8}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< double > property_opacity() const;
/** The scale factor of the widget. See Gtk::Widget::get_scale_factor() for
* more details about widget scaling.
*
* @newin{3,10}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_scale_factor() const;
protected:
//comment in GTK+ header: "seldomly overidden"
virtual void dispatch_child_properties_changed_vfunc(guint p1, GParamSpec** p2);
virtual void show_all_vfunc();
#ifdef GTKMM_ATKMM_ENABLED
virtual Glib::RefPtr<Atk::Object> get_accessible_vfunc();
#endif // GTKMM_ATKMM_ENABLED
virtual SizeRequestMode get_request_mode_vfunc() const;
virtual void get_preferred_width_vfunc(int& minimum_width, int& natural_width) const;
virtual void get_preferred_height_for_width_vfunc(int width, int& minimum_height, int& natural_height) const;
virtual void get_preferred_height_vfunc(int& minimum_height, int& natural_height) const;
virtual void get_preferred_width_for_height_vfunc(int height, int& minimum_width, int& natural_width) const;
//TODO: Wrap all the new vfuncs when we can break ABI.
protected:
Widget();
/** Creates the GDK (windowing system) resources associated with a
* widget. For example, @a widget->window will be created when a widget
* is realized. Normally realization happens implicitly; if you show
* a widget and all its parent containers, then the widget will be
* realized and mapped automatically.
*
* Realizing a widget requires all
* the widget’s parent widgets to be realized; calling
* realize() realizes the widget’s parents in addition to
* @a widget itself. If a widget is not yet inside a toplevel window
* when you realize it, bad things will happen.
*
* This function is primarily used in widget implementations, and
* isn’t very useful otherwise. Many times when you think you might
* need it, a better approach is to connect to a signal that will be
* called after the widget is realized automatically, such as
* Gtk::Widget::signal_draw(). Or simply Glib::signal_connect() to the
* Gtk::Widget::signal_realize() signal.
*/
void realize();
/** This function is only useful in widget implementations.
* Causes a widget to be unrealized (frees all GDK resources
* associated with the widget, such as @a widget->window).
*/
void unrealize();
/** Draws @a widget to @a cr. The top left corner of the widget will be
* drawn to the currently set origin point of @a cr.
*
* You should pass a cairo context as @a cr argument that is in an
* original state. Otherwise the resulting drawing is undefined. For
* example changing the operator using cairo_set_operator() or the
* line width using cairo_set_line_width() might have unwanted side
* effects.
* You may however change the context’s transform matrix - like with
* cairo_scale(), cairo_translate() or cairo_set_matrix() and clip
* region with cairo_clip() prior to calling this function. Also, it
* is fine to modify the context with cairo_save() and
* cairo_push_group() prior to calling this function.
*
* Note that special-purpose widgets may contain special code for
* rendering to the screen and might appear differently on screen
* and when rendered using draw().
*
* @newin{3,0}
*
* @param cr A cairo context to draw to.
*/
void draw(const ::Cairo::RefPtr< ::Cairo::Context>& cr);
/** Marks the widget as being realized.
*
* This function should only ever be called in a derived widget's
* “map” or “unmap” implementation.
*
* @newin{2,20}
*
* @param mapped <tt>true</tt> to mark the widget as mapped.
*/
void set_mapped(bool mapped = true);
/** Marks the widget as being realized. This function must only be
* called after all Gdk::Windows for the @a widget have been created
* and registered.
*
* This function should only ever be called in a derived widget's
* “realize” or “unrealize” implementation.
*
* @newin{2,20}
*
* @param realized <tt>true</tt> to mark the widget as realized.
*/
void set_realized(bool realized = true);
/** Specifies whether @a widget has a Gdk::Window of its own. Note that
* all realized widgets have a non-<tt>nullptr</tt> “window” pointer
* (get_window() never returns a <tt>nullptr</tt> window when a widget
* is realized), but for many of them it’s actually the Gdk::Window of
* one of its parent widgets. Widgets that do not create a %window for
* themselves in Gtk::Widget::signal_realize() must announce this by
* calling this function with @a has_window = <tt>false</tt>.
*
* This function should only be called by widget implementations,
* and they should call it in their init() function.
*
* @newin{2,18}
*
* @param has_window Whether or not @a widget has a window.
*/
void set_has_window(bool has_window = true);
/** Sets a widget's window. This function should only be used in a
* widget's Gtk::Widget::on_realize() implementation. The %window passed is
* usually either a new window created with Gdk::Window::create(), or the
* window of its parent widget as returned by get_parent_window().
*
* Widgets must indicate whether they will create their own Gdk::Window
* by calling set_has_window(). This is usually done in the
* widget's constructor.
*
* This function should only be called by custom widget implementations,
* and they should call it in their on_realize() function.
*
* @newin{2,18}
*
* @param window A Gdk::Window.
*/
void set_window(const Glib::RefPtr<Gdk::Window>& window);
/** This function is supposed to be called in Gtk::Widget::signal_draw()
* implementations for widgets that support multiple windows.
* @a cr must be untransformed from invoking of the draw function.
* This function will return <tt>true</tt> if the contents of the given
* @a window are supposed to be drawn and <tt>false</tt> otherwise. Note
* that when the drawing was not initiated by the windowing
* system this function will return <tt>true</tt> for all windows, so
* you need to draw the bottommost window first. Also, do not
* use “else if” statements to check which window should be drawn.
*
* @newin{3,0}
*
* @param cr A cairo context.
* @param window The window to check. @a window may not be an input-only
* window.
* @return <tt>true</tt> if @a window should be drawn.
*/
static bool should_draw_window(const ::Cairo::RefPtr<const ::Cairo::Context>& cr, const Glib::RefPtr<const Gdk::Window>& window);
/** Transforms the given cairo context @a cr from widget-relative
* coordinates to window-relative coordinates.
* If the widget's window is not an ancestor of @a window, no
* modification will be applied.
*
* This is the inverse to the transformation GTK applies when
* preparing an expose event to be emitted with the Widget's draw
* signal. It is intended to help porting multiwindow widgets from
* GTK+ 2 to the rendering architecture of GTK+ 3.
*
* @param cr The cairo context to transform.
* @param window The window to transform the context to.
*
* @newin{3,0}
*/
void transform_cairo_context_to_window(const ::Cairo::RefPtr< ::Cairo::Context>& cr, const Glib::RefPtr<const Gdk::Window>& window);
#ifndef GTKMM_DISABLE_DEPRECATED
/** Retrieves the widget's requisition.
*
* This method should only be used by widget implementations in
* order to discover whether the widget's requisition has actually
* changed after some internal state change (so that they can call
* queue_resize() instead of queue_draw()).
*
* Normally, size_request() should be used.
*
* @result The widget's requisition.
*
* @newin{2,20}
* @deprecated Use get_preferred_size() instead.
*/
Requisition get_requisition() const;
#endif // GTKMM_DISABLE_DEPRECATED
//deprecated
//deprecated.
//The parameter name is "the_property_name" to avoid a warning because there is a method with the "property_name" name.
/** Gets the value of a style property of @a widget.
*
* It is usually easier to use get_style_property(), to avoid the use of
* Glib::Value.
*
* @param the_property_name The name of a style property.
* @param value Location to return the property value.
*/
void get_style_property_value(const Glib::ustring& the_property_name, Glib::ValueBase& value) const;
void realize_if_needed();
};
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//The parameter name is "the_property_name" to avoid a warning because there is a method with the "property_name" name.
template <class PropertyType>
void Widget::get_style_property(const Glib::ustring& the_property_name, PropertyType& value) const
{
Glib::Value<PropertyType> property_value;
property_value.init(Glib::Value<PropertyType>::value_type());
this->get_style_property_value(the_property_name, property_value);
value = property_value.get();
}
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
} // namespace Gtk
namespace Glib
{
/** A Glib::wrap() method for this object.
*
* @param object The C instance.
* @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
* @result A C++ instance that wraps this C instance.
*
* @relates Gtk::Widget
*/
Gtk::Widget* wrap(GtkWidget* object, bool take_copy = false);
} //namespace Glib
#endif /* _GTKMM_WIDGET_H */