1 2@c %start of fragment 3 4@deftp Class <gtk-dialog> 5Derives from @code{<gtk-window>}. 6 7This class defines the following slots: 8 9@table @code 10@item has-separator 11The dialog has a separator bar above its buttons 12 13@end table 14 15@end deftp 16 17@defop Signal <gtk-dialog> response (arg0@tie{}@code{<gint>}) 18Emitted when an action widget is clicked, the dialog receives a delete event, or 19the application programmer calls @code{gtk-dialog-response}. On a delete event, 20the response ID is @code{<gtk-response-none>}. Otherwise, it depends on which 21action widget was clicked. 22 23@end defop 24 25@defop Signal <gtk-dialog> close 26@end defop 27 28@deffn Function gtk-dialog-run (self@tie{}@code{<gtk-dialog>}) @result{}@tie{} (ret@tie{}@code{int}) 29@deffnx Method run 30Blocks in a recursive main loop until the @var{dialog} either emits the response 31signal, or is destroyed. If the dialog is destroyed during the call to 32@code{gtk-dialog-run}, gtk_dialog_returns @code{<gtk-response-none>}. Otherwise, 33it returns the response ID from the "response" signal emission. Before entering 34the recursive main loop, @code{gtk-dialog-run} calls @code{gtk-widget-show} on 35the dialog for you. Note that you still need to show any children of the dialog 36yourself. 37 38During @code{gtk-dialog-run}, the default behavior of "delete_event" is 39disabled; if the dialog receives "delete_event", it will not be destroyed as 40windows usually are, and @code{gtk-dialog-run} will return 41@code{<gtk-response-delete-event>}. Also, during @code{gtk-dialog-run} the 42dialog will be modal. You can force @code{gtk-dialog-run} to return at any time 43by calling @code{gtk-dialog-response} to emit the "response" signal. Destroying 44the dialog during @code{gtk-dialog-run} is a very bad idea, because your 45post-run code won't know whether the dialog was destroyed or not. 46 47After @code{gtk-dialog-run} returns, you are responsible for hiding or 48destroying the dialog if you wish to do so. 49 50Typical usage of this function might be: 51 52@example 53 54 gint result = gtk_dialog_run (GTK_DIALOG (dialog)); 55 switch (result) 56 @{ 57 case GTK_RESPONSE_ACCEPT: 58 do_application_specific_something (); 59 break; 60 default: 61 do_nothing_since_dialog_was_cancelled (); 62 break; 63 @} 64 gtk_widget_destroy (dialog); 65@end example 66 67Note that even though the recursive main loop gives the effect of a modal dialog 68(it prevents the user from interacting with other windows in the same window 69group while the dialog is run), callbacks such as timeouts, IO channel watches, 70DND drops, etc, @emph{will} be triggered during a @code{gtk-dialog-run} call. 71 72@table @var 73@item dialog 74a @code{<gtk-dialog>} 75 76@item ret 77response ID 78 79@end table 80 81@end deffn 82 83@deffn Function gtk-dialog-response (self@tie{}@code{<gtk-dialog>}) (response_id@tie{}@code{int}) 84@deffnx Method response 85Emits the "response" signal with the given response ID. Used to indicate that 86the user has responded to the dialog in some way; typically either you or 87@code{gtk-dialog-run} will be monitoring the "response" signal and take 88appropriate action. 89 90@table @var 91@item dialog 92a @code{<gtk-dialog>} 93 94@item response-id 95response ID 96 97@end table 98 99@end deffn 100 101@deffn Function gtk-dialog-add-button (self@tie{}@code{<gtk-dialog>}) (button_text@tie{}@code{mchars}) (response_id@tie{}@code{int}) @result{}@tie{} (ret@tie{}@code{<gtk-widget>}) 102@deffnx Method add-button 103Adds a button with the given text (or a stock button, if @var{button-text} is a 104stock ID) and sets things up so that clicking the button will emit the 105"response" signal with the given @var{response-id}. The button is appended to 106the end of the dialog's action area. The button widget is returned, but usually 107you don't need it. 108 109@table @var 110@item dialog 111a @code{<gtk-dialog>} 112 113@item button-text 114text of button, or stock ID 115 116@item response-id 117response ID for the button 118 119@item ret 120the button widget that was added 121 122@end table 123 124@end deffn 125 126@deffn Function gtk-dialog-add-action-widget (self@tie{}@code{<gtk-dialog>}) (child@tie{}@code{<gtk-widget>}) (response_id@tie{}@code{int}) 127@deffnx Method add-action-widget 128Adds an activatable widget to the action area of a @code{<gtk-dialog>}, 129connecting a signal handler that will emit the "response" signal on the dialog 130when the widget is activated. The widget is appended to the end of the dialog's 131action area. If you want to add a non-activatable widget, simply pack it into 132the @samp{action_area} field of the @code{<gtk-dialog>} struct. 133 134@table @var 135@item dialog 136a @code{<gtk-dialog>} 137 138@item child 139an activatable widget 140 141@item response-id 142response ID for @var{child} 143 144@end table 145 146@end deffn 147 148@deffn Function gtk-dialog-get-has-separator (self@tie{}@code{<gtk-dialog>}) @result{}@tie{} (ret@tie{}@code{bool}) 149@deffnx Method get-has-separator 150Accessor for whether the dialog has a separator. 151 152@table @var 153@item dialog 154a @code{<gtk-dialog>} 155 156@item ret 157@samp{@code{#t}} if the dialog has a separator 158 159@end table 160 161@end deffn 162 163@deffn Function gtk-dialog-set-default-response (self@tie{}@code{<gtk-dialog>}) (response_id@tie{}@code{int}) 164@deffnx Method set-default-response 165Sets the last widget in the dialog's action area with the given 166@var{response-id} as the default widget for the dialog. Pressing "Enter" 167normally activates the default widget. 168 169@table @var 170@item dialog 171a @code{<gtk-dialog>} 172 173@item response-id 174a response ID 175 176@end table 177 178@end deffn 179 180@deffn Function gtk-dialog-set-has-separator (self@tie{}@code{<gtk-dialog>}) (setting@tie{}@code{bool}) 181@deffnx Method set-has-separator 182Sets whether the dialog has a separator above the buttons. @samp{@code{#t}} by 183default. 184 185@table @var 186@item dialog 187a @code{<gtk-dialog>} 188 189@item setting 190@samp{@code{#t}} to have a separator 191 192@end table 193 194@end deffn 195 196@deffn Function gtk-dialog-set-response-sensitive (self@tie{}@code{<gtk-dialog>}) (response_id@tie{}@code{int}) (setting@tie{}@code{bool}) 197@deffnx Method set-response-sensitive 198Calls @samp{gtk_widget_set_sensitive (widget, @var{setting})} for each widget in 199the dialog's action area with the given @var{response-id}. A convenient way to 200sensitize/desensitize dialog buttons. 201 202@table @var 203@item dialog 204a @code{<gtk-dialog>} 205 206@item response-id 207a response ID 208 209@item setting 210@samp{@code{#t}} for sensitive 211 212@end table 213 214@end deffn 215 216@deffn Function gtk-dialog-get-response-for-widget (self@tie{}@code{<gtk-dialog>}) (widget@tie{}@code{<gtk-widget>}) @result{}@tie{} (ret@tie{}@code{int}) 217@deffnx Method get-response-for-widget 218Gets the response id of a widget in the action area of a dialog. 219 220@table @var 221@item dialog 222a @code{<gtk-dialog>} 223 224@item widget 225a widget in the action area of @var{dialog} 226 227@item ret 228the response id of @var{widget}, or @samp{GTK_RESPONSE_NONE} if @var{widget} 229doesn't have a response id set. 230 231@end table 232 233Since 2.8 234 235@end deffn 236 237@deffn Function gtk-alternative-dialog-button-order (screen@tie{}@code{<gdk-screen>}) @result{}@tie{} (ret@tie{}@code{bool}) 238Returns @samp{@code{#t}} if dialogs are expected to use an alternative button 239order on the screen @var{screen}. See 240@code{gtk-dialog-set-alternative-button-order} for more details about 241alternative button order. 242 243If you need to use this function, you should probably connect to the 244::notify:gtk-alternative-button-order signal on the @code{<gtk-settings>} object 245associated to @var{screen}, in order to be notified if the button order setting 246changes. 247 248@table @var 249@item screen 250a @code{<gdk-screen>}, or @samp{@code{#f}} to use the default screen 251 252@item ret 253Whether the alternative button order should be used 254 255@end table 256 257Since 2.6 258 259@end deffn 260 261 262@c %end of fragment 263