/src/wrappers/gtk/library/gtk_assistant.e
Specman e | 470 lines | 181 code | 112 blank | 177 comment | 4 complexity | f77144e44acb78a6ce42385284169fbe MD5 | raw file
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