/src/wrappers/gtk/library/gtk_container.e
Specman e | 486 lines | 86 code | 128 blank | 272 comment | 2 complexity | 4af2f0e60056f37b06c4871a02ac7ef2 MD5 | raw file
1indexing 2 description: "GtkContainer -- Base class for widgets which contain other widgets" 3 copyright: "[ 4 Copyright (C) 2006 eiffel-libraries team, GTK+ team 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Lesser General Public License 8 as published by the Free Software Foundation; either version 2.1 of 9 the License, or (at your option) any later version. 10 11 This library is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Lesser General Public License for more details. 15 16 You should have received a copy of the GNU Lesser General Public 17 License along with this library; if not, write to the Free Software 18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA 20 ]" 21 -- TODO: add long description from GTK docs 22 23deferred class GTK_CONTAINER 24 25inherit GTK_WIDGET 26 -- Implemented Interfaces: GtkContainer implements 27 -- AtkImplementorIface. 28 29insert GTK_CONTAINER_EXTERNALS 30 31feature 32 add (a_widget: GTK_WIDGET) is 33 -- Adds widget to container. Typically used for simple 34 -- containers such as GtkWindow, GtkFrame, or GtkButton; for 35 -- more complicated layout containers such as GtkBox or 36 -- GtkTable, this function will pick default packing 37 -- parameters that may not be correct. So consider functions 38 -- such as gtk_box_pack_start() and gtk_table_attach() as an 39 -- alternative to gtk_container_add() in those cases. A 40 -- widget may be added to only one container at a time; you 41 -- can't place the same widget inside two different 42 -- containers. 43 require valid_widget: a_widget /= Void 44 do 45 gtk_container_add (handle, a_widget.handle) 46 end 47 48 remove (a_widget: GTK_WIDGET) is 49 -- Removes widget from container. widget must be inside 50 -- container. Note that container will own a reference to 51 -- widget, and that this may be the last reference held; so 52 -- removing a widget from its container can destroy that 53 -- widget. If you want to use widget again, you need to add a 54 -- reference to it while it's not inside a container, using 55 -- g_object_ref(). If you don't want to use widget again it's 56 -- usually more efficient to simply destroy it directly using 57 -- gtk_widget_destroy() since this will remove it from the 58 -- container and help break any circular reference count 59 -- cycles. 60 require 61 valid_widget: a_widget /= Void 62 widget_contained: True -- TODO: has (a_widget) 63 do 64 gtk_container_remove (handle, a_widget.handle) 65 end 66 67 68 -- TODO: (since it's variadic) gtk_container_add_with_properties () 69 70 -- void gtk_container_add_with_properties (GtkContainer *container, 71 -- GtkWidget *widget, const gchar *first_prop_name, ...); 72 73 -- Adds widget to container, setting child properties at the same 74 -- time. See gtk_container_add() and gtk_container_child_set() for 75 -- more details. 76 77 -- container : a GtkContainer 78 -- widget : a widget to be placed inside container 79 -- first_prop_name : the name of the first child property to set 80 -- ... : a NULL-terminated list of property names and values, starting with first_prop_name. 81 82 resize_mode: INTEGER is 83 -- the resize mode for the container. See set_resize_mode. 84 do 85 Result:= gtk_container_get_resize_mode (handle) 86 end 87 88 is_resize_parent: BOOLEAN is 89 -- Is resize request passed to the parent? 90 do 91 Result := (resize_mode = gtk_resize_parent) 92 end 93 94 is_resize_queue: BOOLEAN is 95 -- Is resizes on this widget queued? 96 do 97 Result := (resize_mode = gtk_resize_queue) 98 end 99 100 set_resize_mode (a_mode: INTEGER) is 101 -- Sets the resize mode for the container. The resize mode 102 -- of a container determines whether a resize request will be 103 -- passed to the container's parent or queued for later 104 -- execution. 105 require valid_mode: is_valid_gtk_resize_mode (a_mode) 106 do 107 gtk_container_set_resize_mode (handle, a_mode) 108 end 109 110 check_resize is 111 -- TODO: undocumented in GTK+ documentation 112 do 113 gtk_container_check_resize (handle) 114 end 115 116 set_border_width (a_width: INTEGER) is 117 require 118 a_width.in_range(0, 65535) 119 do 120 gtk_container_set_border_width (handle, a_width) 121 ensure 122 border_width = a_width 123 end 124 125 border_width: INTEGER is 126 do 127 Result := gtk_container_get_border_width (handle) 128 end 129 130 131 -- TODO: wrap gtk_container_foreach () 132 133 -- void gtk_container_foreach (GtkContainer *container, GtkCallback 134 -- callback, gpointer callback_data); 135 136 -- Invokes callback on each non-internal child of container. See 137 -- gtk_container_forall() for details on what constitutes an 138 -- "internal" child. Most applications should use 139 -- gtk_container_foreach(), rather than gtk_container_forall(). 140 141 -- container : a GtkContainer 142 -- callback : a callback 143 -- callback_data : callback user data 144 145 146 children: G_LIST [GTK_WIDGET] is 147 -- container's non-internal children. See `forall' for 148 -- details on what constitutes an "internal" child. 149 local ptr: POINTER 150 do 151 ptr:=gtk_container_get_children(handle) 152 create {G_OBJECT_LIST[GTK_WIDGET]} Result.from_external_pointer (ptr) 153 ensure result_not_void: Result/=Void 154 end 155 156 set_reallocate_redraws is 157 -- Sets the reallocate_redraws flag of the container to the 158 -- given value. Containers requesting reallocation redraws 159 -- get automatically redrawn if any of their children changed 160 -- allocation. 161 do 162 gtk_container_set_reallocate_redraws (handle,1) 163 end 164 165 unset_reallocate_redraws is 166 -- Opposite of `set_reallocate_redraws' 167 do 168 gtk_container_set_reallocate_redraws (handle,0) 169 end 170 171 set_focus_child (a_child: GTK_WIDGET) is 172 do 173 gtk_container_set_focus_child (handle,a_child.handle) 174 end 175 176 177-- gtk_container_get_focus_vadjustment () 178 179-- GtkAdjustment* gtk_container_get_focus_vadjustment 180-- (GtkContainer *container); 181 182-- Retrieves the vertical focus adjustment for the container. See gtk_container_set_focus_vadjustment(). 183 184-- container : a GtkContainer 185-- Returns : the vertical focus adjustment, or NULL if none has been set. 186-- gtk_container_set_focus_vadjustment () 187 188-- void gtk_container_set_focus_vadjustment 189-- (GtkContainer *container, 190-- GtkAdjustment *adjustment); 191 192-- Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the adjustment is scrolled to show that widget. This function sets the vertical alignment. See gtk_scrolled_window_get_vadjustment() for a typical way of obtaining the adjustment and gtk_container_set_focus_hadjustment() for setting the horizontal adjustment. 193 194-- The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the container. 195 196-- container : a GtkContainer 197-- adjustment : an adjustment which should be adjusted when the focus is moved among the descendents of container 198-- gtk_container_get_focus_hadjustment () 199 200-- GtkAdjustment* gtk_container_get_focus_hadjustment 201-- (GtkContainer *container); 202 203-- Retrieves the horizontal focus adjustment for the container. See gtk_container_set_focus_hadjustment(). 204 205-- container : a GtkContainer 206-- Returns : the horizontal focus adjustment, or NULL if none has been set. 207-- gtk_container_set_focus_hadjustment () 208 209-- void gtk_container_set_focus_hadjustment 210-- (GtkContainer *container, 211-- GtkAdjustment *adjustment); 212 213-- Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the adjustment is scrolled to show that widget. This function sets the horizontal alignment. See gtk_scrolled_window_get_hadjustment() for a typical way of obtaining the adjustment and gtk_container_set_focus_vadjustment() for setting the vertical adjustment. 214 215-- The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the container. 216 217-- container : a GtkContainer 218-- adjustment : an adjustment which should be adjusted when the focus is moved among the descendents of container 219-- gtk_container_resize_children () 220 221-- void gtk_container_resize_children (GtkContainer *container); 222 223-- container : 224-- gtk_container_child_type () 225 226-- GType gtk_container_child_type (GtkContainer *container); 227 228-- Returns the type of the children supported by the container. 229 230-- Note that this may return G_TYPE_NONE to indicate that no more children can be added, e.g. for a GtkPaned which already has two children. 231 232-- container : a GtkContainer. 233 -- Returns : a GType. 234 235 236 -- Made external calls till here, the rest is TODO: Paolo 2005-12-31 237 238 239 240-- gtk_container_child_get () 241 242-- void gtk_container_child_get (GtkContainer *container, 243-- GtkWidget *child, 244-- const gchar *first_prop_name, 245-- ...); 246 247-- Gets the values of one or more child properties for child and container. 248 249-- container : a GtkContainer 250-- child : a widget which is a child of container 251-- first_prop_name : the name of the first property to get 252-- ... : a NULL-terminated list of property names and GValue*, starting with first_prop_name. 253-- gtk_container_child_set () 254 255-- void gtk_container_child_set (GtkContainer *container, 256-- GtkWidget *child, 257-- const gchar *first_prop_name, 258-- ...); 259 260-- Sets one or more child properties for child and container. 261 262-- container : a GtkContainer 263-- child : a widget which is a child of container 264-- first_prop_name : the name of the first property to set 265-- ... : a NULL-terminated list of property names and values, starting with first_prop_name. 266-- gtk_container_child_get_property () 267 268-- void gtk_container_child_get_property 269-- (GtkContainer *container, 270-- GtkWidget *child, 271-- const gchar *property_name, 272-- GValue *value); 273 274-- Gets the value of a child property for child and container. 275 276-- container : a GtkContainer 277-- child : a widget which is a child of container 278-- property_name : the name of the property to get 279-- value : a location to return the value 280-- gtk_container_child_set_property () 281 282-- void gtk_container_child_set_property 283-- (GtkContainer *container, 284-- GtkWidget *child, 285-- const gchar *property_name, 286-- const GValue *value); 287 288-- Sets a child property for child and container. 289 290-- container : a GtkContainer 291-- child : a widget which is a child of container 292-- property_name : the name of the property to set 293-- value : the value to set the property to 294-- gtk_container_child_get_valist () 295 296-- void gtk_container_child_get_valist (GtkContainer *container, 297-- GtkWidget *child, 298-- const gchar *first_property_name, 299-- va_list var_args); 300 301-- Gets the values of one or more child properties for child and container. 302 303-- container : a GtkContainer 304-- child : a widget which is a child of container 305-- first_property_name : the name of the first property to get 306-- var_args : a NULL-terminated list of property names and GValue*, starting with first_prop_name. 307-- gtk_container_child_set_valist () 308 309-- void gtk_container_child_set_valist (GtkContainer *container, 310-- GtkWidget *child, 311-- const gchar *first_property_name, 312-- va_list var_args); 313 314-- Sets one or more child properties for child and container. 315 316-- container : a GtkContainer 317-- child : a widget which is a child of container 318-- first_property_name : the name of the first property to set 319-- var_args : a NULL-terminated list of property names and values, starting with first_prop_name. 320-- gtk_container_forall () 321 322-- void gtk_container_forall (GtkContainer *container, 323-- GtkCallback callback, 324-- gpointer callback_data); 325 326-- Invokes callback on each child of container, including children that are considered "internal" (implementation details of the container). "Internal" children generally weren't added by the user of the container, but were added by the container implementation itself. Most applications should use gtk_container_foreach(), rather than gtk_container_forall(). 327 328-- container : a GtkContainer 329-- callback : a callback 330-- callback_data : callback user data 331-- gtk_container_get_border_width () 332 333-- guint gtk_container_get_border_width (GtkContainer *container); 334 335-- Retrieves the border width of the container. See gtk_container_set_border_width(). 336 337-- container : a GtkContainer 338-- Returns : the current border width 339-- gtk_container_set_border_width () 340 341-- void gtk_container_set_border_width (GtkContainer *container, 342-- guint border_width); 343 344-- Sets the border width of the container. 345 346-- The border width of a container is the amount of space to leave around the outside of the container. The only exception to this is GtkWindow; because toplevel windows can't leave space outside, they leave the space inside. The border is added on all sides of the container. To add space to only one side, one approach is to create a GtkAlignment widget, call gtk_widget_set_usize() to give it a size, and place it on the side of the container as a spacer. 347 348-- container : a GtkContainer 349-- border_width : amount of blank space to leave outside the container. Valid values are in the range 0-65535 pixels. 350-- gtk_container_propagate_expose () 351 352-- void gtk_container_propagate_expose (GtkContainer *container, 353-- GtkWidget *child, 354-- GdkEventExpose *event); 355 356-- When a container receives an expose event, it must send synthetic expose events to all children that don't have their own GdkWindows. This function provides a convenient way of doing this. A container, when it receives an expose event, calls gtk_container_propagate_expose() once for each child, passing in the event the container received. 357 358-- gtk_container_propagate_expose() takes care of deciding whether an expose event needs to be sent to the child, intersecting the event's area with the child area, and sending the event. 359 360-- In most cases, a container can simply either simply inherit the ::expose implementation from GtkContainer, or, do some drawing and then chain to the ::expose implementation from GtkContainer. 361 362-- container : a GtkContainer 363-- child : a child of container 364-- event : a expose event sent to container 365-- gtk_container_get_focus_chain () 366 367-- gboolean gtk_container_get_focus_chain (GtkContainer *container, 368-- GList **focusable_widgets); 369 370-- Retrieves the focus chain of the container, if one has been set explicitly. If no focus chain has been explicitly set, GTK+ computes the focus chain based on the positions of the children. In that case, GTK+ stores NULL in focusable_widgets and returns FALSE. 371 372-- container : a GtkContainer 373-- focusable_widgets : location to store the focus chain of the container, or NULL. You should free this list using g_list_free() when you are done with it, however no additional reference count is added to the individual widgets in the focus chain. 374-- Returns : TRUE if the focus chain of the container has been set explicitly. 375-- gtk_container_set_focus_chain () 376 377-- void gtk_container_set_focus_chain (GtkContainer *container, 378-- GList *focusable_widgets); 379 380-- Sets a focus chain, overriding the one computed automatically by GTK+. 381 382-- In principle each widget in the chain should be a descendant of the container, but this is not enforced by this method, since it's allowed to set the focus chain before you pack the widgets, or have a widget in the chain that isn't always packed. The necessary checks are done when the focus chain is actually traversed. 383 384-- container : a GtkContainer. 385-- focusable_widgets : the new focus chain. 386-- gtk_container_unset_focus_chain () 387 388-- void gtk_container_unset_focus_chain (GtkContainer *container); 389 390-- Removes a focus chain explicitly set with gtk_container_set_focus_chain(). 391 392-- container : a GtkContainer. 393-- gtk_container_class_find_child_property () 394 395-- GParamSpec* gtk_container_class_find_child_property 396-- (GObjectClass *cclass, 397-- const gchar *property_name); 398 399-- Finds a child property of a container class by name. 400 401-- cclass : a GtkContainerClass 402-- property_name : the name of the child property to find 403-- Returns : the GParamSpec of the child property or NULL if class has no child property with that name. 404-- gtk_container_class_install_child_property () 405 406-- void gtk_container_class_install_child_property 407-- (GtkContainerClass *cclass, 408-- guint property_id, 409-- GParamSpec *pspec); 410 411-- Installs a child property on a container class. 412 413-- cclass : a GtkContainerClass 414-- property_id : the id for the property 415-- pspec : the GParamSpec for the property 416-- gtk_container_class_list_child_properties () 417 418-- GParamSpec** gtk_container_class_list_child_properties 419-- (GObjectClass *cclass, 420-- guint *n_properties); 421 422-- Returns all child properties of a container class. 423 424-- cclass : a GtkContainerClass 425-- n_properties : location to return the number of child properties found 426-- Returns : a newly allocated array of GParamSpec*. The array must be freed with g_free(). 427-- Property Details 428-- The "border-width" property 429 430-- "border-width" guint : Read / Write 431 432-- The width of the empty border outside the containers children. 433 434-- Allowed values: <= G_MAXINT 435 436-- Default value: 0 437-- The "child" property 438 439-- "child" GtkWidget : Write 440 441-- Can be used to add a new child to the container. 442-- The "resize-mode" property 443 444-- "resize-mode" GtkResizeMode : Read / Write 445 446-- Specify how resize events are handled. 447 448-- Default value: GTK_RESIZE_PARENT 449-- Signal Details 450-- The "add" signal 451 452-- void user_function (GtkContainer *container, 453-- GtkWidget *widget, 454-- gpointer user_data) : Run first 455 456-- container : the object which received the signal. 457-- widget : 458-- user_data : user data set when the signal handler was connected. 459-- The "check-resize" signal 460 461-- void user_function (GtkContainer *container, 462-- gpointer user_data) : Run last 463 464-- container : the object which received the signal. 465-- user_data : user data set when the signal handler was connected. 466-- The "remove" signal 467 468-- void user_function (GtkContainer *container, 469-- GtkWidget *widget, 470-- gpointer user_data) : Run first 471 472-- container : the object which received the signal. 473-- widget : 474-- user_data : user data set when the signal handler was connected. 475-- The "set-focus-child" signal 476 477-- void user_function (GtkContainer *container, 478-- GtkWidget *widget, 479-- gpointer user_data) : Run first 480 481-- container : the object which received the signal. 482-- widget : 483-- user_data : user data set when the signal handler was connected. 484 485end 486