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.
It is recommended to use the higher-level Show instead.
"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.
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."
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.
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
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.
Note that this will not work with a Gtk_Button. Modify_Fg should be called on the button's label in order to set the color of its label. For example, assuming a simple button with a label attached to it:
Modify_Fg (Get_Child (My_Button), My_State, My_New_Color);
If the direction is set to TEXT_DIR_NONE, then the value set by Set_Default_Direction will be used.
Note the difference in behavior vs. Get_Ancestor: Get_Ancestor (Widget, GTK_TYPE_WINDOW) would return null if 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 check if the "toplevel" flag is set on the result:
Toplevel := Get_Toplevel (Widget); if Top_Level_Is_Set (Toplevel) then [ Perform some action on Toplevel. ] end if;
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.
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.
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.
Here is a simple example: Push_Composite_Child; Gtk_New (Scrolled_Window.Hscrollbar, Hadjustment); Set_Composite_Name (Scrolled_Window.Hscrollbar, "hscrollbar"); Pop_Composite_Child; Set_Parent (Scrolled_Window.Hscrollbar, Scrolled_Window); Ref (Scrolled_Window.Hscrollbar);
Null is returned if Stock_Id wasn't known.
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.
Child_Property is the name of a child property installed on Widget's parent. You should use Glib.Propert_Name to get the name from the property declaration in each of the GtkAda packages