/src/wrappers/gtk/library/gtk_scrolled_window.e

  1indexing
  2	description: "A container that adds scrollbars to its child widget"
  3	copyright: "[
  4					Copyright (C) 2006 Paolo Redaelli, 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			
 22class GTK_SCROLLED_WINDOW
 23	-- A container the accepts a single child widget. GtkScrolledWindow
 24	-- adds scrollbars to the child widget and optionally draws a
 25	-- beveled frame around the child widget.
 26			
 27	-- The scrolled window can work in two ways. Some widgets have
 28	-- native scrolling support; these widgets have "slots" for
 29	-- GtkAdjustment objects.  Widgets with native scroll support
 30	-- include GtkTreeView, GtkTextView, and GtkLayout.
 31
 32	-- For widgets that lack native scrolling support, the GtkViewport
 33	-- widget acts as an adaptor class, implementing scrollability for
 34	-- child widgets that lack their own scrolling capabilities. Use
 35	-- GtkViewport to scroll child widgets such as GtkTable, GtkBox,
 36	-- and so on.
 37	
 38	-- If a widget has native scrolling abilities, it can be added to
 39	-- the GtkScrolledWindow with `add'. If a widget does not, you must
 40	-- first add the widget to a GtkViewport, then add the GtkViewport
 41	-- to the scrolled window. The convenience function
 42	-- gtk_scrolled_window_add_with_viewport() does exactly this, so
 43	-- you can ignore the presence of the viewport.
 44	
 45	-- The position of the scrollbars is controlled by the scroll
 46	-- adjustments. See GtkAdjustment for the fields in an adjustment -
 47	-- for GtkScrollbar, used by GtkScrolledWindow, the "value" field
 48	-- represents the position of the scrollbar, which must be between
 49	-- the "lower" field and "upper - page_size." The "page_size" field
 50	-- represents the size of the visible scrollable area. The
 51	-- "step_increment" and "page_increment" fields are used when the
 52	-- user asks to step down (using the small stepper arrows) or page
 53	-- down (using for example the PageDown key).
 54
 55	-- If a GtkScrolledWindow doesn't behave quite as you would like,
 56	-- or doesn't have exactly the right layout, it's very possible to
 57	-- set up your own scrolling with GtkScrollbar and for example a
 58	-- GtkTable.
 59
 60inherit
 61	GTK_BIN
 62		-- GtkScrolledWindow implements AtkImplementorIface interface.
 63insert
 64	GTK_POLICY_TYPE
 65	GTK_CORNER_TYPE
 66	GTK_SHADOW_TYPE
 67	
 68creation make, make_default, from_external_pointer
 69
 70feature {} -- Creation
 71	make_default is
 72			-- Creates a new scrolled window. The adjustments will be 
 73			-- created with it.
 74		require gtk_initialized: gtk.is_initialized
 75		do
 76			from_external_pointer (gtk_scrolled_window_new (default_pointer,default_pointer))
 77		end
 78	
 79	make (an_horizontal_adjustment, a_vertical_adjustment: GTK_ADJUSTMENT) is
 80			-- Creates a new scrolled window. The two arguments are the
 81			-- scrolled window's adjustments; these will be shared with
 82			-- the scrollbars and the child widget to keep the bars in
 83			-- sync with the child. Usually you want to pass `Void' for
 84			-- the adjustments, which will cause the scrolled window to
 85			-- create them for you.
 86		
 87			-- `an_horizontal_adjustment' : Horizontal adjustment.
 88			--  `a_vertical_adjustment': Vertical adjustment.
 89		do
 90			from_external_pointer (gtk_scrolled_window_new (null_or(an_horizontal_adjustment), null_or(a_vertical_adjustment)))
 91		end
 92
 93feature -- Adjustments
 94	horizontal_adjustment: GTK_ADJUSTMENT is
 95			-- the horizontal scrollbar's adjustment, used to connect the
 96			-- horizontal scrollbar to the child widget's horizontal
 97			-- scroll functionality.
 98		local factory: G_OBJECT_EXPANDED_FACTORY [GTK_ADJUSTMENT]
 99		do
100			Result := factory.wrapper_or_void (gtk_scrolled_window_get_hadjustment (handle))
101		end
102	
103	vertical_adjustment: GTK_ADJUSTMENT is
104			-- the vertical scrollbar's adjustment, used to connect the
105			-- vertical scrollbar to the child widget's vertical
106			-- scroll functionality.
107		local factory: G_OBJECT_EXPANDED_FACTORY [GTK_ADJUSTMENT]
108		do
109			Result := factory.wrapper_or_void (gtk_scrolled_window_get_vadjustment (handle))
110		end
111
112	
113	set_horizontal_adjustment (an_adjustment: GTK_ADJUSTMENT) is
114			-- Sets the GtkAdjustment for the horizontal scrollbar.
115		require
116			adjustment_not_void: an_adjustment /= Void
117		do
118			gtk_scrolled_window_set_hadjustment (handle, an_adjustment.handle)
119		ensure adjustment_set: an_adjustment = horizontal_adjustment
120		end
121
122	set_vertical_adjustment (an_adjustment: GTK_ADJUSTMENT) is
123			-- Sets the GtkAdjustment for the vertical scrollbar.
124		require
125			adjustment_not_void: an_adjustment /= Void
126		do
127			gtk_scrolled_window_set_vadjustment (handle, an_adjustment.handle)
128		ensure adjustment_set: an_adjustment = vertical_adjustment
129		end
130
131feature -- TODO: Scrollbars
132	
133-- gtk_scrolled_window_get_hscrollbar ()
134
135-- GtkWidget*  gtk_scrolled_window_get_hscrollbar
136--                                             (GtkScrolledWindow *scrolled_window);
137
138-- Returns the horizontal scrollbar of scrolled_window.
139
140-- scrolled_window : 	a GtkScrolledWindow
141-- Returns : 	the horizontal scrollbar of the scrolled window, or NULL if it does not have one.
142
143-- Since 2.8
144-- gtk_scrolled_window_get_vscrollbar ()
145
146-- GtkWidget*  gtk_scrolled_window_get_vscrollbar
147--                                             (GtkScrolledWindow *scrolled_window);
148
149-- Returns the vertical scrollbar of scrolled_window.
150
151-- scrolled_window : 	a GtkScrolledWindow
152-- Returns : 	the vertical scrollbar of the scrolled window, or NULL if it does not have one.
153
154-- Since 2.8
155	set_policy (an_horizontal_policy, a_vertical_policy: INTEGER) is
156			-- Sets the scrollbar policy for the horizontal and vertical
157			-- scrollbars. The policy determines when the scrollbar
158			-- should appear; it is a value from the GtkPolicyType
159			-- enumeration. If `GTK_POLICY_ALWAYS', the scrollbar is
160			-- always present; if `GTK_POLICY_NEVER', the scrollbar is
161			-- never present; if `GTK_POLICY_AUTOMATIC', the scrollbar is
162			-- present only if needed (that is, if the slider part of the
163			-- bar would be smaller than the trough - the display is
164			-- larger than the page size).
165		require
166			valid_horizontal_policy: is_valid_gtk_policy (an_horizontal_policy)
167			valid_vertical_policy: is_valid_gtk_policy (a_vertical_policy)
168		do
169			gtk_scrolled_window_set_policy (handle, an_horizontal_policy, a_vertical_policy)
170		ensure -- TODO: h and v policy_set
171		end
172
173feature 
174	add_with_viewport (a_child: GTK_WIDGET) is
175			-- Adds children without native scrolling capabilities. This
176			-- is simply a convenience function; it is equivalent to
177			-- adding the unscrollable child to a viewport, then adding
178			-- the viewport to the scrolled window. If a child has native
179			-- scrolling, use `add' instead of this function.
180
181			-- The viewport scrolls the child by moving its GdkWindow,
182			-- and takes the size of the child to be the size of its
183			-- toplevel GdkWindow. This will be very wrong for most
184			-- widgets that support native scrolling; for example, if you
185			-- add a widget such as GtkTreeView with a viewport, the
186			-- whole widget will scroll, including the column
187			-- headings. Thus, widgets with native scrolling support
188			-- should not be used with the GtkViewport proxy.
189
190			-- A widget supports scrolling natively if the
191			-- set_scroll_adjustments_signal field in GtkWidgetClass is
192			-- non-zero, i.e. has been filled in with a valid signal
193			-- identifier.
194
195			-- TODO: wrap GTK_VIEWPORT
196		require
197			child_not_void: a_child /= Void
198		do
199			gtk_scrolled_window_add_with_viewport (handle, a_child.handle)
200		end
201
202	set_placement (a_window_placement: INTEGER) is
203			-- Determines the location of the child widget with respect
204			-- to the scrollbars. The default is `gtk_corner_top_left',
205			-- meaning the child is in the top left, with the scrollbars
206			-- underneath and to the right. Other values in GtkCornerType
207			-- are `gtk_corner_top_right', `gtk_corner_bottom_left', and
208			-- `gtk_corner_bottom_right'.
209		require
210			valid_placement: is_valid_gtk_corner_type (a_window_placement)
211		do
212			gtk_scrolled_window_set_placement (handle, a_window_placement)
213			ensure placement_set: a_window_placement = placement
214		end
215
216	set_shadow_type (a_type: INTEGER) is
217			-- Changes the type of shadow drawn around the contents of
218			-- scrolled_window.
219		require
220			valid_shadow: is_valid_gtk_shadow_type(a_type)
221		do
222			gtk_scrolled_window_set_shadow_type (handle, a_type)
223		ensure value_set: shadow_type = a_type
224		end
225
226	placement: INTEGER is
227			-- The placement of the scrollbars for the scrolled
228			-- window. See `set_placement'.
229		do
230			Result := gtk_scrolled_window_get_placement (handle)
231		ensure valid: is_valid_gtk_corner_type (Result)
232		end
233
234	horizontal_policy: INTEGER is
235			-- The current policy values for the horizontal
236			-- scrollbar. See `set_policy'.
237		do
238			gtk_scrolled_window_get_policy (handle, $Result, default_pointer)
239		ensure valid: is_valid_gtk_policy (Result)
240		end
241	
242	vertical_policy: INTEGER is
243			-- The current policy values for the vertical scrollbar. See
244			-- `set_policy'.
245		do
246			gtk_scrolled_window_get_policy (handle, default_pointer, $Result)
247		ensure valid: is_valid_gtk_policy (Result)
248		end
249
250	policies: TUPLE [INTEGER,INTEGER] is
251			-- The current policy values for the horizontal
252			-- scrollbar. See `set_policy'.
253		local hpol, vpol: INTEGER
254		do
255			gtk_scrolled_window_get_policy (handle, $hpol,$vpol)
256			create Result.make_2 (hpol,vpol)
257		ensure
258			valid_horizontal: is_valid_gtk_policy (Result.item_1)
259			valid_vertical: is_valid_gtk_policy (Result.item_1)
260		end
261	
262	shadow_type: INTEGER is
263			-- The shadow type of the scrolled window. See
264			-- `set_shadow_type'.
265		do
266			Result := gtk_scrolled_window_get_shadow_type (handle)
267		ensure valid: is_valid_gtk_shadow_type (Result)
268		end
269	
270feature -- Properties
271
272--   "hadjustment"          GtkAdjustment         : Read / Write / Construct
273--   "hscrollbar-policy"    GtkPolicyType         : Read / Write
274--   "shadow-type"          GtkShadowType         : Read / Write
275--   "vadjustment"          GtkAdjustment         : Read / Write / Construct
276--   "vscrollbar-policy"    GtkPolicyType         : Read / Write
277--   "window-placement"     GtkCornerType         : Read / Write
278
279-- Style Properties
280
281--   "scrollbar-spacing"    gint                  : Read
282
283-- Property Details
284-- The "hadjustment" property
285
286--   "hadjustment"          GtkAdjustment         : Read / Write / Construct
287
288-- The GtkAdjustment for the horizontal position.
289-- The "hscrollbar-policy" property
290
291--   "hscrollbar-policy"    GtkPolicyType         : Read / Write
292
293-- When the horizontal scrollbar is displayed.
294
295-- Default value: GTK_POLICY_ALWAYS
296-- The "shadow-type" property
297
298--   "shadow-type"          GtkShadowType         : Read / Write
299
300-- Style of bevel around the contents.
301
302-- Default value: GTK_SHADOW_NONE
303-- The "vadjustment" property
304
305--   "vadjustment"          GtkAdjustment         : Read / Write / Construct
306
307-- The GtkAdjustment for the vertical position.
308-- The "vscrollbar-policy" property
309
310--   "vscrollbar-policy"    GtkPolicyType         : Read / Write
311
312-- When the vertical scrollbar is displayed.
313
314-- Default value: GTK_POLICY_ALWAYS
315-- The "window-placement" property
316
317--   "window-placement"     GtkCornerType         : Read / Write
318
319-- Where the contents are located with respect to the scrollbars.
320
321-- Default value: GTK_CORNER_TOP_LEFT
322-- Style Property Details
323-- The "scrollbar-spacing" style property
324
325--   "scrollbar-spacing"    gint                  : Read
326
327-- Number of pixels between the scrollbars and the scrolled window.
328
329-- Allowed values: >= 0
330
331-- Default value: 3
332
333feature -- scroll-child signal
334
335	scroll_child_signal_name: STRING is "scroll-child"
336		-- "scroll-child"
337		--             void        user_function      (GtkScrolledWindow *scrolledwindow,
338		--                                             GtkScrollType     *arg1,
339		--                                             gboolean           arg2,
340		--                                             gpointer           user_data)           : Run last / Action
341
342	enable_on_scroll_child is
343			-- Connects "scroll-child" signal to `on_scroll_child' feature.
344		do
345			connect (Current, scroll_child_signal_name, $on_scroll_child)
346		end
347
348	on_scroll_child: INTEGER is
349			-- Built-in scroll-child signal handler; empty by design; redefine it.
350			
351			-- The `scroll-child' signal is emitted on the drag source
352			-- when a drag is started. A typical reason to connect to this
353			-- signal is to set up a custom drag icon with
354			-- gtk_drag_source_set_icon().
355		do
356		end
357
358	connect_agent_to_scroll_child_signal (a_function: FUNCTION[ANY, TUPLE [INTEGER, BOOLEAN, GTK_SCROLLED_WINDOW],
359																				  BOOLEAN]) is
360			-- scrolledwindow : 	the object which received the signal.
361			-- arg1 : 	
362			-- arg2 : 	
363		require
364			valid_function: a_function /= Void
365			wrapper_is_stored: is_eiffel_wrapper_stored
366		local
367			scroll_child_callback: SCROLL_CHILD_CALLBACK
368		do
369			create scroll_child_callback.make
370			scroll_child_callback.connect (Current, a_function)
371		end
372
373feature -- Signals
374
375-- "move-focus-out"
376--             void        user_function      (GtkScrolledWindow *scrolledwindow,
377--                                             GtkDirectionType  *arg1,
378--                                             gpointer           user_data)           : Run last / Action
379
380-- Signal Details
381-- The "move-focus-out" signal
382
383-- void        user_function                  (GtkScrolledWindow *scrolledwindow,
384--                                             GtkDirectionType  *arg1,
385--                                             gpointer           user_data)           : Run last / Action
386
387-- scrolledwindow : 	the object which received the signal.
388-- arg1 : 	
389-- user_data : 	user data set when the signal handler was connected.
390-- GtkViewport, GtkAdjustment, GtkWidgetClass
391
392-- [5] The scrolled window installs GtkAdjustment objects in the child window's slots using the set_scroll_adjustments_signal, found in GtkWidgetClass. (Conceptually, these widgets implement a "Scrollable" interface; because GTK+ 1.2 lacked interface support in the object system, this interface is hackily implemented as a signal in GtkWidgetClass. The GTK+ 2.0 object system would allow a clean implementation, but it wasn't worth breaking the API.)
393
394feature -- size
395
396	struct_size: INTEGER is
397		external "C inline use <gtk/gtk.h>"
398		alias "sizeof(GtkScrolledWindow)"
399		end
400
401feature {} -- External calls
402	gtk_scrolled_window_new (a_hadjustment, a_vadjustment: POINTER): POINTER is -- GtkWidget*
403		external "C use <gtk/gtk.h>"
404		end
405
406	gtk_scrolled_window_get_hadjustment (a_scrolled_window: POINTER): POINTER is --  GtkAdjustment*
407		external "C use <gtk/gtk.h>"
408		end
409
410	gtk_scrolled_window_get_vadjustment (a_scrolled_window: POINTER): POINTER is -- GtkAdjustment*
411		external "C use <gtk/gtk.h>"
412		end
413
414	gtk_scrolled_window_get_hscrollbar (a_scrolled_window: POINTER): POINTER is -- GtkWidget*
415		external "C use <gtk/gtk.h>"
416		end
417
418	gtk_scrolled_window_get_vscrollbar (a_scrolled_window: POINTER): POINTER is -- GtkWidget*
419		external "C use <gtk/gtk.h>"
420		end
421
422	gtk_scrolled_window_set_policy (a_scrolled_window: POINTER; hscrollbar_policy, vscrollbar_policy: INTEGER) is
423		require
424			valid_horizontal_policy: is_valid_gtk_policy (hscrollbar_policy)
425			valid_vorizontal_policy: is_valid_gtk_policy (vscrollbar_policy)
426		external "C use <gtk/gtk.h>"
427		end
428
429	gtk_scrolled_window_add_with_viewport(a_scrolled_window, a_child_gtkwidget: POINTER) is
430		external "C use <gtk/gtk.h>"
431		end
432
433	gtk_scrolled_window_set_placement (a_scrolled_window: POINTER;  window_placement: INTEGER) is
434		require
435			valid_placement: is_valid_gtk_corner_type (window_placement)
436		external "C use <gtk/gtk.h>"
437		end
438
439	gtk_scrolled_window_set_shadow_type (a_scrolled_window: POINTER; a_shadow_type: INTEGER) is
440		require
441			valid_shadow_type: is_valid_gtk_shadow_type (a_shadow_type)
442		external "C use <gtk/gtk.h>"
443		end
444
445	gtk_scrolled_window_set_hadjustment (a_scrolled_window, an_hadjustment: POINTER) is
446		external "C use <gtk/gtk.h>"
447		end
448
449	gtk_scrolled_window_set_vadjustment (a_scrolled_window, a_vadjustment: POINTER) is
450		external "C use <gtk/gtk.h>"
451		end
452
453	gtk_scrolled_window_get_placement (a_scrolled_window: POINTER): INTEGER is
454		external "C use <gtk/gtk.h>"
455		ensure
456			valid_result: is_valid_gtk_corner_type (Result)
457		end
458
459	gtk_scrolled_window_get_policy (a_scrolled_window, a_hscrollbar_policy_pointer, a_vscrollbar_policy_pointer: POINTER) is
460		external "C use <gtk/gtk.h>"
461		end
462
463	gtk_scrolled_window_get_shadow_type (a_scrolled_window: POINTER): INTEGER is
464		external "C use <gtk/gtk.h>"
465		ensure valid_result: is_valid_gtk_shadow_type (Result)
466		end
467
468-- GtkScrolledWindow struct has no public fields; it should only be
469-- accessed using the functions above. Nevertheless the original GTK+
470-- documentation still provides this detail:
471
472-- typedef struct {
473--	GtkWidget *hscrollbar;
474--	GtkWidget *vscrollbar;
475-- } GtkScrolledWindow;
476
477end -- class GTK_SCROLLED_WINDOW