[Contents] [Back] [Prev] [Up] [Next] [Forward]

# Package Gtk.Widget

This widget is the base of the tree for displayable objects. (A displayable object is one which takes up some amount of screen real estate). It provides a common base and interface which actual widgets must adhere to.

This package provides some services which might have been more appropriate in some other packages, but could not because of dependency circularities (there are for instance some functions relating to colors and colormaps). We have tried to reference these functions in the other packages as well.

- Gtk.Widget Widget Hierarchy
- Gtk.Widget Signals
- Gtk.Widget Types
- Gtk.Widget Subprograms

## Widget Hierarchy

    GObject                       (see section Package Glib.Object)
    Gtk_Object                    (see section Package Gtk.Object)
       \___ Gtk_Widget            (see section Package Gtk.Widget)

## Signals

- "add_accelerator" ???
- "button_press_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Button)
  return Boolean;
  A button was pressed while the pointer was inside the widget. To get this signal, some widgets by have to use the Set_Events subprogram first to get this event. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "button_release_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Button)
  return Boolean;
  A button was released while the pointer was inside the widget. Note that in some cases (Gtk_Buttons for instance), another "clicked" signal could be emitted). This "button_release_event" should mainly be used for widgets that don't already have specific signals to cover that case (Gtk_Drawing_Area for instance). To get this signal, some widgets may have to use the Set_Events subprogram first to get this event. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "client_event" ???
- "configure_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Configure)
  return Boolean;
  Some configuration of the window has changed (it has been moved or resized). If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "delete_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event)
  return Boolean;
  The user has clicked on the "close" button in the window's frame (the button that is automatically set by the window manager). If the handler returns False, the widget will be destroyed (and the window closed), but if the handler returns True, nothing will be done. This is a good way to prevent the user from closing your application's window if there should be some clean ups first (like saving the document).
- "destroy_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event)
  return Boolean;
  This signal is apparently never emitted by Gtk+. You might want to use "destroy" instead, which is documented in Gtk.Object.
- "drag_begin" Event related to drag-and-drop support. See the Gtk.Dnd documentation.
- "drag_data_delete" Event related to drag-and-drop support. See the Gtk.Dnd documentation.
- "drag_data_get" Event related to drag-and-drop support. See the Gtk.Dnd documentation.
- "drag_data_received" Event related to drag-and-drop support. See the Gtk.Dnd documentation.
- "drag_drop" Event related to drag-and-drop support. See the Gtk.Dnd documentation.
- "drag_end" Event related to drag-and-drop support. See the Gtk.Dnd documentation.
- "drag_leave" Event related to drag-and-drop support. See the Gtk.Dnd documentation.
- "drag_motion" Event related to drag-and-drop support. See the Gtk.Dnd documentation.
- "draw" procedure Handler (Widget : access Gtk_Widget_Record'Class;
  Area : Gdk.Rectangle.Gdk_Rectangle);
  Emitted when a widget needs to be drawn. The default handler emits the "expose" event.
- "draw_default" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Emitted when a widget needs to be drawn and it does not have the focus. This is never called if the widget can not have the focus (ie the "Can_Focus" flag is unset).
- "draw_focus" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Emitted when a widget needs to be drawn and it has the focus. Some widgets might want to provide visual clues that they have the focus, like a black border. This is never called if the widget can not have the focus (ie the "Can_Focus" flag is unset).
- "enter_notify_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Crossing)
  return Boolean;
  The pointer has just entered the widget. If the "Can_Focus" flag is set, Widget will gain the focus, and the widget might be drawn differently. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event)
  return Boolean;
  Some event was sent to the widget. This covers all the cases below, and acts as a general handler. This is called in addition to the relevant specific handler below. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "expose_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Expose)
  return Boolean;
  The widget needs to be partly redrawn. The exact area to redraw is found in Event. For some widgets, you should rather connect to the "draw" signal. However, for instance for Gtk_Drawing_Area widgets, you have to use this, after setting the correct event mask with Set_Events. If the handler returns False, the event might be passed to the parent of widget (if no other handler of widget has returned True).
- "focus_in_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Focus)
  return Boolean;
  The widget has just gained the focus. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True). This event is only emitted if you called Add_Events with a Enter_Notify_Mask parameter
- "focus_out_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Focus)
  return Boolean;
  The widget has just lost the focus. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True). This event is only emitted if you called Add_Events with a Leave_Notify_Mask parameter
- "grab_focus" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  The widget has got the focus, ie will now get the keyboard events sent to a window. This is only called if the "Can_Focus" flag is set. The "Has_Focus" flag might not be set when this signal is emitted.
- "hide" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Emitted when a widget is to be hidden (see explanation for the Hide subprogram). Hides the widget from the screen, and if its parent is shown, the widget will not appear on the screen again.
- "key_press_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Key)
  return Boolean;
  A key has been pressed while Widget had the focus. Note that some widgets like Gtk_Editable provide some higher-level signals to handle this. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "key_release_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Key)
  return Boolean;
  A key has been released while Widget had the focus. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "leave_notify_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Crossing)
  return Boolean;
  The pointer has just leaved the widget. If the "Can_Focus" flag is set, Widget will gain the focus, and the widget might be drawn differently. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "map" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Emitted when a widget is mapped on the screen (the default handler simply emits the "show" signal).
- "map_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event)
  return Boolean;
  The widget has just been mapped. This is different from the "map" signal, which is called *before* the widget is actually mapped. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "motion_notify_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Motion)
  return Boolean;
  The pointer has moved while remaining inside the widget. The Set_Events subprogram has to be called first to get this event. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "no_expose_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event)
  return Boolean;
  ???
- "parent_set" procedure Handler (Widget : access Gtk_Widget_Record'Class;
  Previous_Parent : access Gtk_Widget_Record'Class);
  A new parent has been set for the widget. The previous parent is given in arguments (if there was none, Gdk.Is_Created (Previous_Parent) returns False).
- "property_notify_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Property)
  return Boolean;
  ???
- "proximity_in_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Proximity)
  return Boolean;
  Used for special input devices. See the description of Gdk.Event.Gdk_Event_Proximity. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "proximity_out_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Proximity)
  return Boolean;
  Used for special input devices. See the description of Gdk.Event.Gdk_Event_Proximity. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "realize" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Emitted when a widget is realized. The default handler creates the Gdk window associated with the widget, and its ancestors.
- "remove_accelerator" ???
- "selection_clear_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Selection)
  return Boolean;
  ???
- "selection_get" Related to the selection mechanism, see Gtk.Selection
- "selection_notify_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Selection)
  return Boolean;
  ???
- "selection_received" Related to the selection mechanism, see Gtk.Selection
- "selection_request_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Selection)
  return Boolean;
  ???
- "show" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Emitted when a widget is to be shown (see explanation for the Show subprogam). This schedules the widget to be displayed on the screen, and if this is a toplevel widget it actually appears on the screen and all its children that have been shown.
- "size_allocate" procedure Handler (Widget : access Gtk_Widget_Record'Class;
  Allocation : Gtk_Allocation);
  A size and position were assigned to the widget. This is called every time the size of the widget changes. The default handler takes care of resizing and moving the widget.
- "size_request" procedure Handler (Widget : access Gtk_Widget_Record'Class;
  Requisition : access Gtk_Requisition);
  Should return (in Requisition) the ideal size the widget would like to have. It is not sure this is the size that will be assigned to it, since it depends on the size of its parent).
- "state_changed" procedure Handler (Widget : access Gtk_Widget_Record'Class;
  Previous_State : Gtk.Enums.Gtk_State_Type);
  The state of the widget has changed.
- "style_set" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Previous_Style : Gtk.Style.Gtk_Style);
  The widget's style has been changed (this is not call when some settings in the style are changed, only when the style itself is completely changed with a call to Set_Style or Set_Default_Style).
- "unmap" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Emitted when a widget needs to be unmapped on the screen (the default handler simply emits the "hide" signal).
- "unmap_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event)
  return Boolean;
  The widget has just been unmapped. This is different from the "unmap" signal, which is called *before* the widget is actually unmapped. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).
- "unrealize" procedure Handler (Widget : access Gtk_Widget_Record'Class);
  Emitted when a widget is unrealized. The default handler destroys the Gdk windows of the widget and all its children.
- "visibility_notify_event" function Handler (Widget : access Gtk_Widget_Record'Class;
  Event : Gdk.Event.Gdk_Event_Visibility)
  return Boolean;
  The visibility state of the widget has changed (partially visible, fully visible, ...). You might want to use the "expose" signal instead. If the handler returns False, the event might be pass to the parent of widget (if no other handler of widget has returned True).

## Types

    type Expose_Event_Handler is access function
        (Widget : System.Address; Event : Gdk.Event.Gdk_Event) return Boolean;

    type Gtk_Allocation is record
        X      : Gint;
        Y      : Gint;
        Width  : Allocation_Int;
        Height : Allocation_Int;
        end record;

| Gtk_Allocation indicates a size and position a widget was allocated. See the section in the user guide on how to create new widgets for more information. pragma Convention (C, Gtk_Allocation);

    type Gtk_Allocation_Access is access all Gtk_Allocation;

    type Gtk_Requisition is record
        Width  : Gint;
        Height : Gint;
        end record;

| Gtk_Requisition is the desired amount of screen real-estate a widget requests to the server. Its real allocated size might be different. See the section in the GtkAda user guide on how to create new widgets in Ada, and the examples/base_widget directory for an example on how to use this. pragma Convention (C, Gtk_Requisition);

    type Gtk_Requisition_Access is access all Gtk_Requisition;

    type Size_Allocate_Handler is access procedure

    type Widget_Type is new Gtk_Widget_Record with private;

## Subprograms

    function Get_Type              return Glib.GType;

| Return the internal value associated with a Gtk_Widget.

### Widgets' life cycle

    procedure Destroy_Cb
      (Widget             : access Gtk_Widget_Record'Class);

| This function should be used as a callback to destroy a widget. All it does is call Destroy on its argument, but its profile is compatible with the handlers found in Gtk.Handlers.

    procedure Unparent
      (Widget             : access Gtk_Widget_Record'Class);

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. Users should call Remove instead. This function might be dangereous: it correctly updates widget to reflect that it no longer belongs to its parent, however the parent keeps an internal pointer to the widget, which will result in a storage_error if you try to further access it.

    procedure Show
      (Widget             : access Gtk_Widget_Record);

| Schedule the widget to be displayed on the screen when its parent is also shown (emits the "show" signal). If its ancestors are already mapped to the screen, then the widget is immediately displayed through a call to Map below.

    procedure Show_Now
      (Widget             : access Gtk_Widget_Record);

| Show the widget. If it is an unmapped toplevel widget, wait for it to be mapped. This creates a recursive main_loop.

    procedure Hide
      (Widget             : access Gtk_Widget_Record);

| Hide the widget from the screen (emits the "hide" signal). If Widget was visible, it is immediately hidden. If one of its ancestor is later shown on the screen, Widget won't appear. Note that on some window managers, including CDE, hiding an iconified window will not do anything. You should in addition call Gdk.Window.Withdraw to make sure the window is properly hidden.

    procedure Show_All
      (Widget             : access Gtk_Widget_Record);

| Show Widget and all its children recursively. See also Set_Child_Visible below

    procedure Hide_All
      (Widget             : access Gtk_Widget_Record);

| Hide Widget and all its children. Note that if you simply want to delete Widget from the screen, you can simply call the Hide subprogram on it. This procedure Hide_All should only be used if you want to unschedule a widget to be displayed later, not to remove an actual widget from the screen. See also Set_Child_Visible below.

    procedure Map
      (Widget             : access Gtk_Widget_Record);

| Map a widget to the screen. A window is created for it on the screen (through a call to Realize) and Widget is then drawn on the screen (if its ancestors are also mapped). This function is recursive and will also map all the children of Widget. It is recommended to use the higher-level Show instead.

    procedure Unmap
      (Widget             : access Gtk_Widget_Record);

| Unmap a widget from the screen. This results in the widget being hidden, but not destroyed. It can be shown again any time through a call to Map (provided its ancestors are also mapped). It is recommended to use the higher-level Hide instead.

    procedure Realize
      (Widget             : access Gtk_Widget_Record);

| Create a window for Widget and its ancestors (emit the "realize" signal) This does not mean that the widget will appear on the screen, but resources such as colormaps, etc. become available. Some routines require that the widget is realized before any call. You must set the Event_Mask before calling this routine if you want to change it from its default value.

    procedure Unrealize
      (Widget             : access Gtk_Widget_Record);

| Hide the widget from the screen and deletes the associated window. This does not destroy the widget itself, only its server-side resources.

    procedure Set_Realize
      (Widget             : access Gtk_Widget_Record'Class);

| Set the realize handler at the low level. This is needed to replace the default realize in new widgets.

    function Hide_On_Delete
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Hide widget and return True. This function is intended to be used as a callback.

    procedure Set_Child_Visible
      (Widget             : access Gtk_Widget_Record;
       Is_Visible         :        Boolean);

Sets whether Widget should be mapped along with its parent when its
parent is mapped and Widget has been shown with Show.

"mapped" indicates the moment the window is actually shown on the screen. Show and Hide indicate your intention to show Widget on the scree or not, but if the parent of Widget is itself not shown at that time, the two commands Show and Hide have no immediate effect, and just set a flag to save your intent. Set_Child_Visible indicates that the widget shouldn't be part of the recursive processing done by Show_All and Hide_All on the parent. You have decided once and for all what the behavior should be, and you don't want it to be changed by future calls to Show_All and Hide_All.

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 True 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 should generally not be called by an application.

    function Get_Child_Visible
      (Widget             : access Gtk_Widget_Record)
       return Boolean;

| Return the value set by Set_Child_Visible

### Drawing a widget

    procedure Queue_Draw
      (Widget             : access Gtk_Widget_Record);

| Add a drawing request to the event queue for the whole widget. This is more efficient than calling Draw directly, since GtkAda groups drawing requests as much as possible to speed up the drawing process. The actual drawing will take place as soon as GtkAda is not busy processing other events, but before idle events.

    procedure Queue_Draw_Area
      (Widget             : access Gtk_Widget_Record;
       X                  :        Gint;
       Y                  :        Gint;
       Width              :        Gint;
       Height             :        Gint);

| Add a drawing request to the event queue for part of the widget. This is more efficient that calling Draw directly (see Queue_Draw).

    procedure Queue_Resize
      (Widget             : access Gtk_Widget_Record);

| Queue drawing requests after a resizing of the widget. This clears the widget, and its parent if any, so that everything is correctly redrawn. You should not have to call this function directly. For a Gtk_Window, check the procedure Gtk.Window.Resize instead.

    procedure Draw
      (Widget             : access Gtk_Widget_Record;
       Area               :        Gdk.Rectangle.Gdk_Rectangle
                           := Gdk.Rectangle.Full_Area);

| Emit a "draw" signal for a specific area of the widget. The visual aspect might be different whether the widget has the focus or not. pragma Deprecated (Draw);

### Size and position

    procedure Size_Request
      (Widget             : access Gtk_Widget_Record;
       Requisition        : in out Gtk_Requisition);

| Emit a "size_request" event for the widget

    procedure Set_Size_Request
      (Widget             : access Gtk_Widget_Record;
       Width, Height      :        Gint := -1);

Sets the minimum size of a widget; that is, the widget's size request
will be Width by Height. You can use this function to force a widget to be either larger or smaller than it normally would be.

In most cases, 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.Windo.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.

Widgets can't actually be allocated a size less than 1 by 1, but you can pass 0,0 to this function to mean "as small as possible."

    procedure Size_Allocate
      (Widget             : access Gtk_Widget_Record;
       Allocation         :        Gtk_Allocation);

| Emit a "size_allocate" event for the widget. Allocation'size is first constrained to a range between 1x1 and 32767x32767. A clear and draw request is also queued if required.

    function Get_Child_Requisition
      (Widget             : access Gtk_Widget_Record)
       return Gtk_Requisition;

| Return the size requests by the widget. This is the ideal size for the widget, not necessarily its actual size. See the user guide's section on how to create new widgets for more information on the size requisition and allocation.

    procedure Set_UPosition
      (Widget             : access Gtk_Widget_Record;
       X, Y               :        Gint);

| Modify the position of the widget. This should be used only for toplevel widgets (windows and dialogs), since other widgets' positions are handled by their parent.

    function Get_Allocation_Width
      (Widget             : access Gtk_Widget_Record)
       return Allocation_Int;

| Return the current width of the widget.

    function Get_Allocation_Height
      (Widget             : access Gtk_Widget_Record)
       return Allocation_Int;

| Return the current height of the widget.

    function Get_Allocation_X
      (Widget             : access Gtk_Widget_Record)
       return Gint;

| Return the current position of the widget, relative to its parent.

    function Get_Allocation_Y
      (Widget             : access Gtk_Widget_Record)
       return Gint;

| Return the current position of the widget, relative to its parent.

### Accelerators

    procedure Add_Accelerator
      (Widget             : access Gtk_Widget_Record;
       Accel_Signal       :        String;
       Accel_Group        :        Gtk.Accel_Group.Gtk_Accel_Group;
       Accel_Key          :        Gdk.Types.Gdk_Key_Type;
       Accel_Mods         :        Gdk.Types.Gdk_Modifier_Type;
       Accel_Flags        :        Gtk.Accel_Group.Gtk_Accel_Flags);

| Add a new accelerator for the widget. The signal Accel_Signal will be sent to Widget when the matching key is pressed and the widget has the focus. Consider using Gtk.Accel_Map.Add_Entry instead, which is compatible with interactive change of accelerators by the user.

    procedure Remove_Accelerator
      (Widget             : access Gtk_Widget_Record;
       Accel_Group        :        Gtk.Accel_Group.Gtk_Accel_Group;
       Accel_Key          :        Gdk.Types.Gdk_Key_Type;
       Accel_Mods         :        Gdk.Types.Gdk_Modifier_Type);

| Remove an accelerator for the widget.

    procedure Set_Accel_Path
      (Widget             : access Gtk_Widget_Record;
       Accel_Path         :        UTF8_String;
       Group              :        Gtk.Accel_Group.Gtk_Accel_Group);

| Set the path that will be used to reference the widget in calls to the subprograms in Gtk.Accel_Map. This means, for instance, that the widget is fully setup for interactive modification of the shortcuts by the user, should he choose to activate this possibility in his themes (see gtk-accel_map.ads for more information).

### Events and signals

    function Event
      (Widget             : access Gtk_Widget_Record'Class;
       Event              :        Gdk.Event.Gdk_Event)
       return Boolean;

| Emit a signal on the widget. The exact signal depends on the event type (i.e. if the type is Gdk_Button_Press, then a "button_press" signal is emitted).

    procedure Send_Expose
      (Widget             : access Gtk_Widget_Record;
       Event              :        Gdk.Event.Gdk_Event_Expose);

Emit an expose event signals on a widget.
This function is not normally used directly. The only time it is used is when propagating an expose event to a child No_Window widget, and that is normally done using Gtk.Container.Propagate_Expose.

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.

    procedure Activate
      (Widget             : access Gtk_Widget_Record);

| Emit an activate signal on the widget. The exact signal emitted depends on the widget type (i.e. for a Gtk_Button this emits a "clicked" signal, for a Gtk_Editable this emits the "activate" signal, ...).

    procedure Grab_Focus
      (Widget             : access Gtk_Widget_Record);

| Emit the "grab_focus" signal for the widget. This is sent when the widget gets the focus. Its visual aspect might change. The "Can_Focus" flag must have been set first. See also Gtk.Widget.Child_Focus, which should be used instead when writting new widgets in Ada

    function Child_Focus
      (Child              : access Gtk_Widget_Record'Class;
       Direction          :        Gtk.Enums.Gtk_Direction_Type
                           := Gtk.Enums.Dir_Tab_Forward)
       return Boolean;

Used by custom widget implementations to indicate the focus child.
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. Direction indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). Child_Focus invokes the "focus" signal on Child; widgets override the default handler for this signal in order to implement appropriate focus behavior.

The "focus" default handler for a widget should return True if moving in Direction left the focus on a focusable location inside that widget, and False if moving in Direction moved the focus outside the widget. If returning True, widgets normally call Grab_Focus to place the focus accordingly; if returning False, they don't modify the current focus location.

This function replaces Gtk.Container.Focus from GTK+ 1.2. It was necessary to check that the child was visible, sensitive, and focusable before calling Gtk.Container.Focus. Child_Focus returns False if the widget is not currently in a focusable state, so there's no need for those checks.

Return value: True if focus ended up inside Child

    procedure Set_Events
      (Widget             : access Gtk_Widget_Record;
       Events             :        Gdk.Event.Gdk_Event_Mask);

| Sets the event mask for the widget. Widget should not have been realized before, or nothing is done. This is the only way you can explicitly get mouse or keyboards events on widgets that do not automatically get them, as for instance in a Gtk_Drawing_Area.

    function Get_Events
      (Widget             : access Gtk_Widget_Record)
       return Gdk.Event.Gdk_Event_Mask;

| Get the event mask for the widget. This indicates the list of events that the widget receives.

    procedure Add_Events
      (Widget             : access Gtk_Widget_Record;
       Events             :        Gdk.Event.Gdk_Event_Mask);

| Add some events to the current event mask of the widget.

    procedure Set_Extension_Events
      (Widget             : access Gtk_Widget_Record;
       Mode               :        Gdk.Types.Gdk_Extension_Mode);

| Set the extension event mask for the widget. This is used to activate some special input modes for other devices than keyboard and mouse.

    function Get_Extension_Events
      (Widget             : access Gtk_Widget_Record)
       return Gdk.Types.Gdk_Extension_Mode;

| Return the current extension events mask.

    function Default_Motion_Notify_Event
      (Widget             : access Gtk_Widget_Record'Class;
       Event              :        Gdk.Event.Gdk_Event)
       return Gint;

| Access to the standard default callback for motion events: This is mainly used for rulers in Gtk.Ruler (See the example in testgtk, with create_rulers.adb)

    function Has_Default_Motion_Notify_Handler
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Return True if Widget has a default handler for motion_notify events. Note that the function Default_Motion_Notify_Event should not be called if this one returns False, since it would create a segmentation fault.

### Colors and colormaps

    function Get_Colormap
      (Widget             : access Gtk_Widget_Record)
       return Gdk.Color.Gdk_Colormap;

| Return the colormap used for the widget. This will generally be the same one for all widgets, but might be different if for instance a Gtk_Drawing_Area needs to display some different colors on a screen that only has a limited amount of colors.

    function Get_Visual
      (Widget             : access Gtk_Widget_Record)
       return Gdk.Visual.Gdk_Visual;

| Get the visual used for the widget. I.e. the structure that indicates the depth of the widget (number of bits per pixel), and some information used internally by GtkAda to handle colors and colormaps.

    procedure Set_Colormap
      (Widget             : access Gtk_Widget_Record;
       Cmap               :        Gdk.Color.Gdk_Colormap);

| Modify the colormap of the widget. The widget must not have been realized.

    procedure Push_Colormap
      (Cmap               :        Gdk.Color.Gdk_Colormap);

| Modify temporarily the default colormap set for newly created widgets. You should use this in pair with Pop_Colormap below (Push the new value, create the widget, and pop the value).

    procedure Pop_Colormap;

| See Push_Colormap for more information.

    function Get_Default_Colormap  return Gdk.Color.Gdk_Colormap;

| Return the default colormap used when a widget is created.

    procedure Set_Default_Colormap
      (Cmap               :        Gdk.Color.Gdk_Colormap);

| Modify permanently the default colormap used when a widget is created. If you only want to modify this colormap temporarily for a few widgets, you should consider using Push_Colormap and Pop_Colormap instead.

    function Get_Default_Visual    return Gdk.Visual.Gdk_Visual;

| Return the default visual used when a new widget is created.

### Styles

    procedure Push_Style
      (Style              :        Gtk.Style.Gtk_Style);

| Change the default values for styles. This is generally used just before creating a widget. You should use this procedure in pair with Pop_Style (Push the new value, create the widget then pop the value)

    procedure Pop_Style;

| Restore the default values for styles. This is generally used just after creating a widget. You should use this procedure in pair with Push_Style (Push the new value, create the widget then pop the value)

    procedure Set_Style
      (Widget             : access Gtk_Widget_Record;
       Style              :        Gtk.Style.Gtk_Style);

| Set the style for a given widget.

    function Get_Style
      (Widget             : access Gtk_Widget_Record)
       return Gtk.Style.Gtk_Style;

| Return the style of a given widget.

    function Get_Default_Style     return Gtk.Style.Gtk_Style;

| Get the default global style.

    procedure Ensure_Style
      (Widget             : access Gtk_Widget_Record);

| Make sure that the widget has a style associated to it. Either the default one as set by Set_Default_Style above or one set by the user with Set_Style.

    procedure Restore_Default_Style
      (Widget             : access Gtk_Widget_Record);

| Restore the default style that was set for the widget. The default style is the first one that was set either by a call to Set_Style or Set_Default_Style.

    procedure Reset_Rc_Styles
      (Widget             : access Gtk_Widget_Record);

| Restore the Rc style recursively for widget and its children.

    function Get_Pango_Context
      (Widget             : access Gtk_Widget_Record)
       return Pango.Context.Pango_Context;

Get a Pango_Context with the appropriate colormap, 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 as long as widget exists), and will be updated to match any changes to the widget's attributes.

If you create and keep a Pango_Layout using this context, you must deal with changes to the context by calling Pango_Layout.Context_Changed on the layout in response to the ::style_set and ::direction_set signals for the widget.

    function Create_Pango_Context
      (Widget             : access Gtk_Widget_Record)
       return Pango.Context.Pango_Context;

| Create a new Pango_Context with the appropriate colormap, font description, and base direction for drawing text for this widget. See also Get_Pango_Context. The returned context must be freed by the caller.

    function Create_Pango_Layout
      (Widget             : access Gtk_Widget_Record;
       Text               :        UTF8_String := "")
       return Pango.Layout.Pango_Layout;

| Return a new pango_layout that displays Text. This fully handles internationalization, and should be the preferred way to display text, rather than Gdk.Drawable.Draw_Text Text must be a valid Utf8 text, see Glib.Convert.

    procedure Modify_Fg
      (Widget             : access Gtk_Widget_Record;
       State_Type         :        Enums.Gtk_State_Type;
       Color              :        Gdk.Color.Gdk_Color);

| Sets the foreground color for a widget in a particular state. All other style values are left untouched.

    procedure Modify_Bg
      (Widget             : access Gtk_Widget_Record;
       State_Type         :        Enums.Gtk_State_Type;
       Color              :        Gdk.Color.Gdk_Color);

| Sets the background color for a widget in a particular state. All other style values are left untouched.

    procedure Modify_Text
      (Widget             : access Gtk_Widget_Record;
       State_Type         :        Enums.Gtk_State_Type;
       Color              :        Gdk.Color.Gdk_Color);

| Sets the text color for a widget in a particular state. All other style values are left untouched. The text color is the foreground color used along with the base color (see Modify_Base) for widgets such as Gtk_Entry and Gtk_Text_View.

    procedure Modify_Base
      (Widget             : access Gtk_Widget_Record;
       State_Type         :        Enums.Gtk_State_Type;
       Color              :        Gdk.Color.Gdk_Color);

| Sets the base color for a widget in a particular state. All other style values are left untouched. The base color is the background color used along with the text color (see Modify_Text) for widgets such as Gtk_Entry and Gtk_Text_View.

    procedure Modify_Font
      (Widget             : access Gtk_Widget_Record;
       Desc               :        Pango.Font.Pango_Font_Description);

| Modify the font used for the widget. Desc must be freed by the caller to avoid memory leaks

### Widgets' tree

    procedure Set_Name
      (Widget             : access Gtk_Widget_Record;
       Name               :        UTF8_String);

| Set the name for the widget. This name is used purely internally to identify the widget, and does not give any visual clue.

    function Get_Name
      (Widget             : access Gtk_Widget_Record)
       return UTF8_String;

| Return the name of the widget if it was set by Set_Name. Return the name of its class otherwise.

    procedure Set_Parent
      (Widget             : access Gtk_Widget_Record;
       Parent             : access Gtk_Widget_Record'Class);

| Modify the parent for the widget. This is not the recommended way to do this, you should use Gtk.Container.Add or Gtk.Box.Pack_Start instead.

    procedure Set_Parent_Window
      (Widget             : access Gtk_Widget_Record;
       Window             :        Gdk.Window.Gdk_Window);

| Set the parent window for the actual Gdk_Window of the widget. This sets up required internal fields, and should be used only when you implement your own container, as opposed to using one of the standard containers.

    function Get_Parent
      (Widget             : access Gtk_Widget_Record)
       return Gtk_Widget;

| Return the parent of the widget, or null if Widget is a toplevel widget.

    function Get_Parent_Window
      (Widget             : access Gtk_Widget_Record)
       return Gdk.Window.Gdk_Window;

| Return the widget's parent window.

    function Get_Toplevel
      (Widget             : access Gtk_Widget_Record)
       return Gtk_Widget;

| Return the toplevel ancestor of the widget. This is the window or dialog in which the widget is included. The widget returned does not have any parent.

    function Get_Ancestor
      (Widget             : access Gtk_Widget_Record;
       Ancestor_Type      :        Gtk_Type)
       return Gtk_Widget;

| Return the closest ancestor of Widget which is of type Ancestor_Type. Return null if there is none.

    function Is_Ancestor
      (Widget             : access Gtk_Widget_Record;
       Ancestor           : access Gtk_Widget_Record'Class)
       return Boolean;

| Return True if Ancestor is in the ancestor tree for Widget. I.e. if Widget is contained within Ancestor.

    procedure Reparent
      (Widget             : access Gtk_Widget_Record;
       New_Parent         : access Gtk_Widget_Record'Class);

| Change the parent of the widget dynamically. If both the new parent and the widget are shown, then the widget is visually redrawn in its new parent.

    procedure Translate_Coordinates
      (Src_Widget         :        Gtk_Widget;
       Dest_Widget        :        Gtk_Widget;
       Src_X              :        Gint;
       Src_Y              :        Gint;
       Dest_X             : out    Gint;
       Dest_Y             : out    Gint;
       Result             : out    Boolean);

| Translate coordinates relative to Src_Widget's allocation to coordinates relative to Dest_Widget's allocations. In order to perform this operation, both widgets must be realized, and must share a common toplevel. Result is set to False if either widget was not realized, or there was no common ancestor. In this case, nothing is stored in Dest_X and Dest_Y. Otherwise True.

### Misc functions

    procedure Set_Scroll_Adjustments
      (Widget             : access Gtk_Widget_Record;
       Hadj               :        Gtk.Adjustment.Gtk_Adjustment;
       Vadj               :        Gtk.Adjustment.Gtk_Adjustment);

| Emit the "set_scroll_adjustments" signal. The exact signal emitted depends on the widget type (see Gtk.Object.Initialize_Class_Record). The handler creates the adjustments if null is passed as argument, and makes sure both adjustments are in the correct range.

    function Intersect
      (Widget             : access Gtk_Widget_Record;
       Area               :        Gdk.Rectangle.Gdk_Rectangle;
       Intersection       : access Gdk.Rectangle.Gdk_Rectangle)
       return Boolean;

| Return True if the widget intersects the screen area Area. The intersection area is returned in Intersection.

    procedure Grab_Default
      (Widget             : access Gtk_Widget_Record);

| The widget becomes the default widget for its parent window or dialog. All keyboard events will be sent to it if no other widget has the focus. Note that the "Can_Default" flag must have been set first on WIDGET.

    procedure Set_State
      (Widget             : access Gtk_Widget_Record;
       State              :        Enums.Gtk_State_Type);

| Modify the state of the widget. This modifies its visual aspect, and thus should be used only if you change its behavior at the same time, so as not to confuse the user.

    function Get_State
      (Widget             : access Gtk_Widget_Record)
       return Enums.Gtk_State_Type;

| Return the state of the widget.

    procedure Set_Sensitive
      (Widget             : access Gtk_Widget_Record;
       Sensitive          :        Boolean := True);

| Modify the sensitivity of the widget. An insensitive widget is generally grayed out, and can not be activated. For instance, an insensitive menu item is grayed, and can never be selected.

    procedure Set_App_Paintable
      (Widget             : access Gtk_Widget_Record;
       App_Paintable      :        Boolean);

| Modify the "App_Paintable" flag for the widget.

    procedure Set_Double_Buffered
      (Widget             : access Gtk_Widget_Record;
       Double_Buffered    :        Boolean := True);

| Modify the "Double_Buffered" flag for the widget.

    procedure Get_Pointer
      (Widget             : access Gtk_Widget_Record;
       X                  : out    Gint;
       Y                  : out    Gint);

| Return the coordinates of the pointer (i.e. mouse) relative to Widget.

    procedure Set_Window
      (Widget             : access Gtk_Widget_Record;
       Window             :        Gdk.Window.Gdk_Window);

| Set the Gdk window associated with the widget.

    function Get_Window
      (Widget             : access Gtk_Widget_Record)
       return Gdk.Window.Gdk_Window;

| Get the Gdk window associated with the widget. You can use this window if you need to draw directly on the widget using the functions found in the Gdk hierarchy.

    procedure Shape_Combine_Mask
      (Widget             : access Gtk_Widget_Record;
       Shape_Mask         :        Gdk.Bitmap.Gdk_Bitmap;
       Offset_X           :        Gint;
       Offset_Y           :        Gint);

| Modify the shape of the window that contains the widget. This allows for transparent windows, and requires the Xext library to be available on your system. If this library is not available, your program will still work. See the manual page for XShapeCombineMask(3x) for more information.

    function Render_Icon
      (Widget             : access Gtk_Widget_Record;
       Stock_Id           :        String;
       Size               :        Gtk.Enums.Gtk_Icon_Size;
       Detail             :        UTF8_String := "")
       return Gdk.Pixbuf.Gdk_Pixbuf;

A convenience function that uses the theme engine for Widget, to lookup
a Stock_Id (see Gtk.Stock) and render it to a pixbuf (see Gdk.Pixbuf). Detail should be a string that identifies the widget or code doing the rendering, so that the theme engine can special-case rendering for that widget or code. It can be left to the empty stirng to get the default behavior.

Null is returned if Stock_Id wasn't known.

### Creating new widgets

Although the core subprogram for creating new widgets is Glib.Gobjects.Initialize_Class_Record, it is often useful to override some internal pointers to functions. The functions below are not needed unless you are writting your own widgets, and should be reserved for advanced customization of the standard widgets.

    procedure Set_Scroll_Adjustments_Signal
      (Widget             :        Glib.Object.GObject_Class;
       Signal             :        String);

Modify the signal to be sent when the adjustments are modified.
This is only useful when you are rewritting your own widget that can be embedded directly in a Gtk_Scrolled_Window, without any Gtk_Viewport.

Signal is the name of the signal that will be emitted when Widget is put inside a Gtk_Scrolled_Window.

Note that the handlers for this signal must take two arguments in addition to the widget (the horizontal and vertical adjustments to be used). See Gtk.Scrolled_Window and Gtk.Widget.Set_Scroll_Adjustment for more information on this signal.

    procedure Set_Default_Size_Allocate_Handler
      (Klass              :        Glib.Object.GObject_Class;
       Handler            :        Size_Allocate_Handler);

Override the default size_allocate handler for this class. This handler
is automatically called in several cases (when a widget is dynamically resized for instance), not through a signal. Thus, if you need to override the default behavior provided by one of the standard containers, you can not simply use Gtk.Handlers.Emit_Stop_By_Name, and you must override the default handler. Note also that this handler is automatically inherited by children of this class.

    procedure Set_Allocation
      (Widget             : access Gtk_Widget_Record'Class;
       Alloc              :        Gtk_Allocation);

| Modifies directly the internal field of Widget to register the new allocation. Beware that the only use of this method is inside a callback set by Set_Default_Size_Allocate_Handler. If you simply want to resize or reposition a widget, use Size_Allocate instead.

    function Default_Expose_Event_Handler
      (Klass              :        GObject_Class)
       return Expose_Event_Handler;

| Return the default expose event handler for the widget class Klass. The typical use for this function is when you are writting your own container class. You should then, from your own handler for expose_event, call the one of the parent class, so that all the children are automatically redrawn.

### Flags

Some additional flags are defined for all the visual objects (widgets).
They are defined in addition to the ones defined in Gtk.Object. These flags are important in that they define exactly the different states a widget can be in.

- "Toplevel": Set if the widget is a toplevel widget, ie has no parent. This is mostly true for windows and dialogs.
- "No_Window": Set if the widget does not have an associated X11 window, ie can not receive events directly. For instance, a Gtk_Toolbar does not have an associated window. These objects are more lightweight, but require more work from GtkAda. This flag is only set if the widget will never have a window, even after it is realized.
- "Realized": Set if the widget has been realized, ie its associated X11 window has been created (providing the widget excepts a window, see the No_Window flag
- "Mapped": Set if the widget is visible on the screen. This is only possible if the Visible flag is also set.
- "Visible": Set if the widget will be displayed on the screen when mapped (see the functions Show and Hide in this package).
- "Sensitive": Set if the widget is listening to events. See the function Set_Sensitive in this package. An insensitive widget will generally have a different visual aspect to clue that it is unavailable (for instance an insensitive item menu will be grayed)
- "Parent_Sensitive": Set if the parent is sensitive. A widget is sensitive only if both the Sensitive and Parent_Sensitive are set.
- "Can_Focus": Set if the widget can have the focus, ie get keyboard events. Most widgets can not have the focus.
- "Has_Focus": Set if the widget currently has the focus. See the function Grab_Focus in this package.
- "Can_Default": Set if the widget can be the default widget in a window, ie the one that will get the keyboard events by default. For instance, the default button in a dialog is the one that gets clicked on when the user pressed Enter anywhere in the dialog.
- "Has_Default": Set if the widget is currently the default widget. See the function Grab_Default in this package.
- "Has_Grab": Set if the widget currently grabs all mouse and keyboard events in the application, even if it does not have the focus. There can be only such widget per application at any given time.
- "Rc_Style": Set if the widget's style is either the default style, or in a customization file. This is unset if the style has been modified by the user.
- "Composite_Child": This indicates whether the widget is composed of other widgets
- "No_Reparent": This flags is never used in gtk+.
- "App_Paintable": For some containers (including Gtk_Window and Gtk_Layout), this is unset when the container itself has some special drawing routines. It indicates whether the application will paint directly on the widget.
- "Receives_Default": Set when the widget receives the default at the time it receives the focus. This is how the default button in a dialog is automatically changed when you press another button.

    function Toplevel_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Toplevel flag is set.

    function No_Window_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the No_Window flag is set.

    function Realized_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Realized flag is set.

    function Mapped_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Mapped flag is set.

    function Visible_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Visible flag is set.

    function Drawable_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| True if the widget is both visible and mapped. In other words, if it does appear on the screen.

    function Is_Sensitive
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the widget is Sensitive.

    function Can_Focus_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Can_Focus flag is set.

    function Has_Focus_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Has_Focus flag is set.

    function Has_Default_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Has_Default flag is set.

    function Has_Grab_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Has_Grab flag is set.

    function Rc_Style_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Rc_Style flag is set.

    function Double_Buffered_Is_Set
      (Widget             : access Gtk_Widget_Record'Class)
       return Boolean;

| Test whether the Double_Buffered flag is set.

### GValue support

    function Get_Requisition
      (Value              :        Glib.Values.GValue)
       return Gtk_Requisition_Access;

| Convert a value into a Gtk_Requisition_Access.

    function Get_Allocation
      (Value              :        Glib.Values.GValue)
       return Gtk_Allocation_Access;

| Convert a value into a Gtk_Allocation_Access.

[Contents] [Back] [Prev] [Up] [Next] [Forward]