/src/wrappers/gtk/library/gtk_assistant.e

  1indexing
  2	description: "GtkAssistant -- A widget used to guide users through multi-step."
  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 hopeOA 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
 22
 23class GTK_ASSISTANT
 24	-- A GtkAssistant is a widget used to represent a generally complex
 25	-- operation splitted in several steps, guiding the user through
 26	-- its pages and controlling the page flow to collect the necessary
 27	-- data.
 28
 29inherit
 30	GTK_WINDOW
 31		undefine
 32			struct_size
 33		redefine
 34			make
 35		end
 36		-- GtkAssistant implements AtkImplementorIface.
 37
 38	CANCEL_SIGNAL_RECEIVER
 39	
 40insert
 41	G_OBJECT_FACTORY [GTK_WIDGET]
 42	GTK_ASSISTANT_EXTERNALS
 43
 44creation make, from_external_pointer
 45
 46feature {} -- Creation
 47	make is
 48			-- Creates a new GtkAssistant.
 49		do
 50			from_external_pointer(gtk_assistant_new)
 51		end
 52	
 53feature
 54	current_page: INTEGER is
 55			-- The index (starting from 0) of the current page in the
 56			-- assistant, if the assistant has no pages, it will be -1.
 57		do
 58			Result:=gtk_assistant_get_current_page (handle)
 59		ensure valid: Result >= -1
 60		end
 61
 62	set_current_page (a_page_num: INTEGER) is
 63			-- Switches the page to `a_page_num'. Note that this will
 64			-- only be necessary in custom buttons, as the assistant flow
 65			-- can be set with `set_forward_page_func'.
 66		
 67			-- `a_page_num': index of the page to switch to, starting
 68			-- from 0. If negative, the last page will be used. If
 69			-- greater than the number of pages in the assistant, nothing
 70			-- will be done.
 71		do
 72			gtk_assistant_set_current_page (handle, a_page_num)
 73		end
 74
 75	pages_n: INTEGER is
 76			-- The number of pages in the assistant.
 77		do
 78			Result:=gtk_assistant_get_n_pages(handle)
 79		end
 80
 81	item (a_page_num: INTEGER): GTK_WIDGET is
 82			-- The child widget contained in page number `a_page_num';
 83			-- set it to -1 to get the last page; Result is Void
 84			-- `a_page_num' is out of bounds.
 85		local ptr: POINTER
 86		do
 87			ptr:=gtk_assistant_get_nth_page(handle, a_page_num)
 88			if ptr.is_not_null then
 89				Result:=wrapper(ptr)
 90				if Result=Void then
 91					debug
 92						print("Warning: GTK_ASSISTANT.item received a %
 93								%GtkWidget pointer of an unwrapped widget. %
 94								%Since we don't know which the correct effective wrapper %
 95								%class feature Result will be Void.%N")
 96					end
 97				end
 98			end
 99		end
100
101	last_inserted_page: INTEGER
102			-- The index (starting at 0) of the inserted page
103	
104	prepend (a_page: GTK_WIDGET) is
105			-- Prepends `a_page' to the assistant. `last_inserted_page' 
106			-- will be updated.
107		require page_not_void: a_page /= Void
108		do
109			last_inserted_page:=gtk_assistant_prepend_page(handle, a_page.handle)
110		end
111
112	append (a_page: GTK_WIDGET) is
113			-- Appends `a_page' to the assistant. `last_inserted_page' 
114			-- will be updated.
115		require page_not_void: a_page /= Void
116		do
117			last_inserted_page:=gtk_assistant_append_page(handle,a_page.handle)
118		end
119
120	insert_page (a_page: GTK_WIDGET; a_position: INTEGER) is
121			-- Inserts `a_page' in the assistant at `a_position',
122			-- starting at 0; -1 to append the page to the assistant.
123		require page_not_void: a_page /= Void
124		do
125			last_inserted_page:=gtk_assistant_insert_page(handle, a_page.handle, a_position)
126		end
127
128	-- GtkAssistantPageFunc ()
129	
130	-- gint (*GtkAssistantPageFunc) (gint current_page, gpointer data);
131	
132	-- A function used by gtk_assistant_set_forward_page_func() to know
133	-- which is the next page given a current one. It's called both for
134	-- computing the next page when the user presses the "forward"
135	-- button and for handling the behavior of the "last" button.
136
137	-- current_page : The page number used to calculate the next page.
138	-- data : user data.  Returns : The next page number.
139
140	--	TODO: set_forward_page (an_agent)
141	
142	-- void gtk_assistant_set_forward_page_func (GtkAssistant
143	-- *assistant, GtkAssistantPageFunc page_func, gpointer data,
144	-- GDestroyNotify destroy);
145
146	-- Sets the page forwarding function to be page_func, this function
147	-- will be used to determine what will be the next page when the
148	-- user presses the forward button. Setting page_func to NULL will
149	-- make the assistant to use the default forward function, which
150	-- just goes to the next visible page.
151
152	--    assistant : a GtkAssistant
153	--    page_func : the GtkAssistantPageFunc, or NULL to use the default one
154	--    data :      user data for page_func
155	--    destroy :   destroy notifier for data
156	
157	set_page_type (a_page: GTK_WIDGET; a_type: INTEGER) is
158			-- Sets the page type for `a_page'. The page type determines the
159			-- page behavior in the assistant.
160		require
161			page_not_void: a_page /= Void
162			valid_page_type: is_valid_gtk_page_type(a_type)
163		do
164			gtk_assistant_set_page_type (handle, a_page.handle, a_type)
165		end
166
167	page_type (a_page: GTK_WIDGET): INTEGER is
168			-- The type of `a_page'.
169		require page_not_void: a_page /= Void
170		do
171			Result := gtk_assistant_get_page_type (handle, a_page.handle)
172		ensure valid_page_type: is_valid_gtk_page_type(Result)
173		end
174
175	set_page_title (a_page: GTK_WIDGET; a_title: STRING) is
176			-- Sets `a_title' for `a_page'. The title is displayed in the
177			-- header area of the assistant when page is the current
178			-- page.
179		require
180			page_not_void: a_page /= Void
181			title_not_void: a_title/=Void
182		do
183			gtk_assistant_set_page_title(handle, a_page.handle, a_title.to_external)
184		end
185
186	page_title (a_page: GTK_WIDGET): STRING is
187			-- the title for `a_page'.
188		require page_not_void: a_page /= Void
189		do
190			create {CONST_STRING} Result.from_external
191			(gtk_assistant_get_page_title(handle, a_page.handle))
192		end
193
194	set_page_header_image (a_page: GTK_WIDGET; a_pixbuf: GDK_PIXBUF) is
195			-- Sets a header image for page. This image is displayed in
196			-- the header area of the assistant when page is the current
197			-- page.
198		require
199			page_not_void: a_page /= Void
200			pixbuf_not_void: a_pixbuf /= Void
201		do
202			gtk_assistant_set_page_header_image(handle, a_page.handle, a_pixbuf.handle)
203		end
204
205	page_header_image (a_page: GTK_WIDGET): GDK_PIXBUF is
206			-- The header image for page; Void if there's no header image
207			-- for the page.
208		local factory: G_OBJECT_EXPANDED_FACTORY[GDK_PIXBUF]
209		do
210			Result := factory.wrapper_or_void
211			(gtk_assistant_get_page_header_image
212			(handle, a_page.handle))
213		end
214
215	set_page_side_image (a_page: GTK_WIDGET; a_pixbuf: GDK_PIXBUF) is
216		-- Sets a header image for `a_page'. This image is displayed
217		-- in the side area of the assistant when page is the current
218		-- page.
219	require
220		page_not_void: a_page /= Void
221		pixbuf_not_void: a_pixbuf /= Void
222	do
223		gtk_assistant_set_page_side_image(handle, a_page.handle, a_pixbuf.handle)
224	end
225
226	page_side_image (a_page: GTK_WIDGET): GDK_PIXBUF is
227			-- The side image for page, or Void if there's no side image
228			-- for the page.
229		require page_not_void: a_page /= Void
230		local factory: G_OBJECT_EXPANDED_FACTORY[GDK_PIXBUF]
231		do
232			Result:=factory.wrapper_or_void(gtk_assistant_get_page_side_image(handle, a_page.handle))
233		end
234	
235	set_page_complete (a_page: GTK_WIDGET; is_complete: BOOLEAN) is
236			-- Sets whether page contents are complete. This will make
237			-- assistant update the buttons state to be able to continue
238			-- the task.
239		require page_not_void: a_page /= Void
240		do
241			gtk_assistant_set_page_complete (handle, a_page.handle, is_complete.to_integer)
242		end
243
244	is_page_complete (a_page: GTK_WIDGET): BOOLEAN is
245			-- Is `a_page' complete?
246		require page_not_void: a_page /= Void
247		do
248			Result:=(gtk_assistant_get_page_complete (handle,a_page.handle)).to_boolean
249		end
250
251	add_action_widget (a_child: GTK_WIDGET) is
252			-- Adds `a_child' to the action area of a GtkAssistant.
253		require child_not_void: a_child /= Void
254		do
255			gtk_assistant_add_action_widget (handle, a_child.handle)
256		end
257	
258	remove_action_widget (a_child: GTK_WIDGET) is
259			-- Removes `a_child' from the action area of a GtkAssistant.
260		require child_not_void: a_child /= Void
261		do
262			gtk_assistant_remove_action_widget(handle, a_child.handle)
263		end
264
265	update_buttons_state is
266			-- Forces assistant to recompute the buttons state. GTK+
267			-- automatically takes care of this in most situations,
268			-- e.g. when the user goes to a different page, or when the
269			-- visibility or completeness of a page changes. One
270			-- situation where it can be necessary to call this function
271			-- is when changing a value on the current page affects the
272			-- future page flow of the assistant.
273		do
274			gtk_assistant_update_buttons_state(handle)
275		end
276
277feature -- Child Properties
278	--    "complete"             gboolean              : Read / Write
279	--    "header-image"         GdkPixbuf             : Read / Write
280	--    "page-type"            GtkAssistantPageType  : Read / Write
281	--    "sidebar-image"        GdkPixbuf             : Read / Write
282	--    "title"                gchararray            : Read / Write
283	
284	-- Child Property Details
285
286	--   The "complete" child property
287	
288	--    "complete"             gboolean              : Read / Write
289
290	--    Setting the "complete" child property to TRUE marks a page as complete
291	--    (i.e.: all the required fields are filled out). GTK+ uses this information
292	--    to control the sensitivity of the navigation buttons.
293
294	--    Default value: FALSE
295
296	--    Since 2.10
297
298	--    --------------------------------------------------------------------------
299
300	--   The "header-image" child property
301
302	--    "header-image"         GdkPixbuf             : Read / Write
303
304	--    The image that is displayed next to the page.
305
306	--    Set this to NULL to make the sidebar disappear.
307
308	--    Since 2.10
309
310	--    --------------------------------------------------------------------------
311
312	--   The "page-type" child property
313
314	--    "page-type"            GtkAssistantPageType  : Read / Write
315
316	--    The type of the assistant page.
317
318	--    Default value: GTK_ASSISTANT_PAGE_CONTENT
319
320	--    Since 2.10
321
322	--    --------------------------------------------------------------------------
323
324	--   The "sidebar-image" child property
325
326	--    "sidebar-image"        GdkPixbuf             : Read / Write
327
328	--    Sidebar image for the assistant page.
329
330	--    --------------------------------------------------------------------------
331
332	--   The "title" child property
333
334	--    "title"                gchararray            : Read / Write
335
336	--    The title that is displayed in the page header.
337
338	--    If title and header-image are both NULL, no header is displayed.
339
340	--    Default value: NULL
341
342	--    Since 2.10
343
344	-- Style Properties
345
346
347	--    "content-padding"      gint                  : Read
348	--    "header-padding"       gint                  : Read
349
350	-- Style Property Details
351
352	--   The "content-padding" style property
353
354	--    "content-padding"      gint                  : Read
355
356	--    Number of pixels around the content pages.
357
358	--    Allowed values: >= 0
359
360	--    Default value: 1
361
362	--    --------------------------------------------------------------------------
363
364	--   The "header-padding" style property
365
366	--    "header-padding"       gint                  : Read
367
368	--    Number of pixels around the header.
369
370	--    Allowed values: >= 0
371
372	--    Default value: 6
373
374	-- Signals
375	--  "cancel"    void        user_function      (GtkAssistant *assistant,
376	--                                              gpointer      user_data)      : Run last
377	--  "close"     void        user_function      (GtkAssistant *assistant,
378	--                                              gpointer      user_data)      : Run last
379	--  "prepare"   void        user_function      (GtkAssistant *assistant,
380	--                                              GtkWidget    *page,
381	--                                              gpointer      user_data)      : Run last
382
383	-- Signal Details
384
385feature -- The "apply" signal
386
387	apply_signal_name: STRING is "apply"
388
389	enable_on_apply is
390			-- Connects "apply" signal to `on_apply' feature.
391		do
392			connect (Current, apply_signal_name, $on_apply)
393		end
394
395	on_apply is
396			-- Built-in activate signal handler; empty by design; redefine it.
397		
398			-- The ::apply signal is emitted when the apply button is
399			-- clicked. The default behavior of the GtkAssistant is to
400			-- switch to the page after the current page, unless the
401			-- current page is the last one.
402			
403			-- A handler for the ::apply signal should carry out the
404			-- actions for which the wizard has collected data. If the
405			-- action takes a long time to complete, you might consider
406			-- to put a page of type GTK_ASSISTANT_PAGE_PROGRESS after
407			-- the confirmation page and handle this operation within the
408			-- ::prepare signal of the progress page.
409		do
410		end
411
412	connect_agent_to_apply_signal (a_procedure: PROCEDURE [ANY, TUPLE[GTK_ASSISTANT]]) is
413		require
414			valid_procedure: a_procedure /= Void
415		local
416			apply_callback: APPLY_CALLBACK 
417		do
418			create apply_callback.make
419			apply_callback.connect (Current, a_procedure)
420		end
421
422feature --   The "cancel" signal
423
424	-- void user_function (GtkAssistant *assistant, gpointer user_data)
425	-- : Run last
426
427	-- The ::cancel signal is emitted when then the cancel button is
428	-- clicked.
429
430	--    assistant : the GtkAssistant
431	--    user_data : user data set when the signal handler was connected.
432
433	--    Since 2.10
434
435	--    --------------------------------------------------------------------------
436
437feature --   The "close" signal
438
439	-- void user_function (GtkAssistant *assistant, gpointer user_data)
440	-- : Run last
441
442	-- The ::close signal is emitted either when the close button of a
443	-- summary page is clicked, or when the apply button in the last
444	-- page in the flow (of type GTK_ASSISTANT_PAGE_CONFIRM) is
445	-- clicked.
446
447	--    assistant : the GtkAssistant
448	--    user_data : user data set when the signal handler was connected.
449
450	--    Since 2.10
451
452	--    --------------------------------------------------------------------------
453
454feature --   The "prepare" signal
455
456	-- void user_function (GtkAssistant *assistant, GtkWidget *page,
457	-- gpointer user_data) : Run last
458
459	-- The ::prepared signal is emitted when a new page is set as the
460	-- assistant's current page, before making the new page visible. A
461	-- handler for this signal can do any preparation which are
462	-- necessary before showing page.
463
464	--    assistant : the GtkAssistant
465	--    page :      the current page
466	--    user_data : user data set when the signal handler was connected.
467
468	--    Since 2.10
469
470end -- class GTK_ASSISTANT