Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame^] | 1 | \section{Built-in Module \sectcode{fl}} |
| 2 | \bimodindex{fl} |
| 3 | |
| 4 | This module provides an interface to the FORMS Library by Mark |
| 5 | Overmars, version 2.0b. For more info about FORMS, write to |
| 6 | {\tt markov@cs.ruu.nl}. |
| 7 | |
| 8 | Most functions are literal translations of their C equivalents, |
| 9 | dropping the initial \samp{fl_} from their name. Constants used by the |
| 10 | library are defined in module \code{FL} described below. |
| 11 | |
| 12 | The creation of objects is a little different in Python than in C: |
| 13 | instead of the `current form' maintained by the library to which new |
| 14 | FORMS objects are added, all functions that add a FORMS object to a |
| 15 | button are methods of the Python object representing the form. |
| 16 | Consequently, there are no Python equivalents for the C functions |
| 17 | \code{fl_addto_form} and \code{fl_end_form}, and the equivalent of |
| 18 | \code{fl_bgn_form} is called \code{fl.make_form}. |
| 19 | |
| 20 | Watch out for the somewhat confusing terminology: FORMS uses the word |
| 21 | \dfn{object} for the buttons, sliders etc. that you can place in a form. |
| 22 | In Python, `object' means any value. The Python interface to FORMS |
| 23 | introduces two new Python object types: form objects (representing an |
| 24 | entire form) and FORMS objects (representing one button, slider etc.). |
| 25 | Hopefully this isn't too confusing... |
| 26 | |
| 27 | There are no `free objects' in the Python interface to FORMS, nor is |
| 28 | there an easy way to add object classes written in Python. The FORMS |
| 29 | interface to GL event handling is avaiable, though, so you can mix |
| 30 | FORMS with pure GL windows. |
| 31 | |
| 32 | \strong{Please note:} importing \code{fl} implies a call to the GL function |
| 33 | \code{foreground()} and to the FORMS routine \code{fl_init()}. |
| 34 | |
| 35 | \subsection{Functions defined in module \sectcode{fl}} |
| 36 | |
| 37 | Module \code{fl} defines the following functions. For more information |
| 38 | about what they do, see the description of the equivalent C function |
| 39 | in the FORMS documentation: |
| 40 | |
| 41 | \renewcommand{\indexsubitem}{(in module fl)} |
| 42 | \begin{funcdesc}{make_form}{type\, width\, height} |
| 43 | Create a form with given type, width and height. This returns a |
| 44 | \dfn{form} object, whose methods are described below. |
| 45 | \end{funcdesc} |
| 46 | |
| 47 | \begin{funcdesc}{do_forms}{} |
| 48 | The standard FORMS main loop. Returns a Python object representing |
| 49 | the FORMS object needing interaction, or the special value |
| 50 | \code{FL.EVENT}. |
| 51 | \end{funcdesc} |
| 52 | |
| 53 | \begin{funcdesc}{check_forms}{} |
| 54 | Check for FORMS events. Returns what \code{do_forms} above returns, |
| 55 | or \code{None} if there is no event that immediately needs |
| 56 | interaction. |
| 57 | \end{funcdesc} |
| 58 | |
| 59 | \begin{funcdesc}{set_event_call_back}{function} |
| 60 | Set the event callback function. |
| 61 | \end{funcdesc} |
| 62 | |
| 63 | \begin{funcdesc}{set_graphics_mode}{rgbmode\, doublebuffering} |
| 64 | Set the graphics modes. |
| 65 | \end{funcdesc} |
| 66 | |
| 67 | \begin{funcdesc}{get_rgbmode}{} |
| 68 | Return the current rgb mode. This is the value of the C global |
| 69 | variable \code{fl_rgbmode}. |
| 70 | \end{funcdesc} |
| 71 | |
| 72 | \begin{funcdesc}{show_message}{str1\, str2\, str3} |
| 73 | Show a dialog box with a three-line message and an OK button. |
| 74 | \end{funcdesc} |
| 75 | |
| 76 | \begin{funcdesc}{show_question}{str1\, str2\, str3} |
| 77 | Show a dialog box with a three-line message and YES and NO buttons. |
| 78 | It returns \code{1} if the user pressed YES, \code{0} if NO. |
| 79 | \end{funcdesc} |
| 80 | |
| 81 | \begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\, but2\, but3} |
| 82 | Show a dialog box with a three-line message and up to three buttons. |
| 83 | It returns the number of the button clicked by the user |
| 84 | (\code{1}, \code{2} or \code{3}). |
| 85 | The \var{but2} and \var{but3} arguments are optional. |
| 86 | \end{funcdesc} |
| 87 | |
| 88 | \begin{funcdesc}{show_input}{prompt\, default} |
| 89 | Show a dialog box with a one-line prompt message and text field in |
| 90 | which the user can enter a string. The second argument is the default |
| 91 | input string. It returns the string value as edited by the user. |
| 92 | \end{funcdesc} |
| 93 | |
| 94 | \begin{funcdesc}{show_file_selector}{message\, directory\, pattern\, default} |
| 95 | Show a dialog box inm which the user can select a file. It returns |
| 96 | the absolute filename selected by the user, or \code{None} if the user |
| 97 | presses Cancel. |
| 98 | \end{funcdesc} |
| 99 | |
| 100 | \begin{funcdesc}{get_directory}{} |
| 101 | \funcline{get_pattern}{} |
| 102 | \funcline{get_filename}{} |
| 103 | These functions return the directory, pattern and filename (the tail |
| 104 | part only) selected by the user in the last \code{show_file_selector} |
| 105 | call. |
| 106 | \end{funcdesc} |
| 107 | |
| 108 | \begin{funcdesc}{qdevice}{dev} |
| 109 | \funcline{unqdevice}{dev} |
| 110 | \funcline{isqueued}{dev} |
| 111 | \funcline{qtest}{} |
| 112 | \funcline{qread}{} |
| 113 | %\funcline{blkqread}{?} |
| 114 | \funcline{qreset}{} |
| 115 | \funcline{qenter}{dev\, val} |
| 116 | \funcline{get_mouse}{} |
| 117 | \funcline{tie}{button\, valuator1\, valuator2} |
| 118 | These functions are the FORMS interfaces to the corresponding GL |
| 119 | functions. Use these if you want to handle some GL events yourself |
| 120 | when using \code{fl.do_events}. When a GL event is detected that |
| 121 | FORMS cannot handle, \code{fl.do_forms()} returns the special value |
| 122 | \code{FL.EVENT} and you should call \code{fl.qread()} to read the |
| 123 | event from the queue. Don't use the equivalent GL functions! |
| 124 | \end{funcdesc} |
| 125 | |
| 126 | \begin{funcdesc}{color}{} |
| 127 | \funcline{mapcolor}{} |
| 128 | \funcline{getmcolor}{} |
| 129 | See the description in the FORMS documentation of \code{fl_color}, |
| 130 | \code{fl_mapcolor} and \code{fl_getmcolor}. |
| 131 | \end{funcdesc} |
| 132 | |
| 133 | \subsection{Form object methods and data attributes} |
| 134 | |
| 135 | Form objects (returned by \code{fl.make_form()} above) have the |
| 136 | following methods. Each method corresponds to a C function whose name |
| 137 | is prefixed with \samp{fl_}; and whose first argument is a form |
| 138 | pointer; please refer to the official FORMS documentation for |
| 139 | descriptions. |
| 140 | |
| 141 | All the \samp{add_{\rm \ldots}} functions return a Python object representing |
| 142 | the FORMS object. Methods of FORMS objects are described below. Most |
| 143 | kinds of FORMS object also have some methods specific to that kind; |
| 144 | these methods are listed here. |
| 145 | |
| 146 | \begin{flushleft} |
| 147 | \renewcommand{\indexsubitem}{(form object method)} |
| 148 | \begin{funcdesc}{show_form}{placement\, bordertype\, name} |
| 149 | Show the form. |
| 150 | \end{funcdesc} |
| 151 | |
| 152 | \begin{funcdesc}{hide_form}{} |
| 153 | Hide the form. |
| 154 | \end{funcdesc} |
| 155 | |
| 156 | \begin{funcdesc}{redraw_form}{} |
| 157 | Redraw the form. |
| 158 | \end{funcdesc} |
| 159 | |
| 160 | \begin{funcdesc}{set_form_position}{x\, y} |
| 161 | Set the form's position. |
| 162 | \end{funcdesc} |
| 163 | |
| 164 | \begin{funcdesc}{freeze_form}{} |
| 165 | Freeze the form. |
| 166 | \end{funcdesc} |
| 167 | |
| 168 | \begin{funcdesc}{unfreeze_form}{} |
| 169 | Unfreeze the form. |
| 170 | \end{funcdesc} |
| 171 | |
| 172 | \begin{funcdesc}{activate_form}{} |
| 173 | Activate the form. |
| 174 | \end{funcdesc} |
| 175 | |
| 176 | \begin{funcdesc}{deactivate_form}{} |
| 177 | Deactivate the form. |
| 178 | \end{funcdesc} |
| 179 | |
| 180 | \begin{funcdesc}{bgn_group}{} |
| 181 | Begin a new group of objects; return a group object. |
| 182 | \end{funcdesc} |
| 183 | |
| 184 | \begin{funcdesc}{end_group}{} |
| 185 | End the current group of objects. |
| 186 | \end{funcdesc} |
| 187 | |
| 188 | \begin{funcdesc}{find_first}{} |
| 189 | Find the first object in the form. |
| 190 | \end{funcdesc} |
| 191 | |
| 192 | \begin{funcdesc}{find_last}{} |
| 193 | Find the last object in the form. |
| 194 | \end{funcdesc} |
| 195 | |
| 196 | %--- |
| 197 | |
| 198 | \begin{funcdesc}{add_box}{type\, x\, y\, w\, h\, name} |
| 199 | Add a box object to the form. |
| 200 | No extra methods. |
| 201 | \end{funcdesc} |
| 202 | |
| 203 | \begin{funcdesc}{add_text}{type\, x\, y\, w\, h\, name} |
| 204 | Add a text object to the form. |
| 205 | No extra methods. |
| 206 | \end{funcdesc} |
| 207 | |
| 208 | %\begin{funcdesc}{add_bitmap}{type\, x\, y\, w\, h\, name} |
| 209 | %Add a bitmap object to the form. |
| 210 | %\end{funcdesc} |
| 211 | |
| 212 | \begin{funcdesc}{add_clock}{type\, x\, y\, w\, h\, name} |
| 213 | Add a clock object to the form. \\ |
| 214 | Method: |
| 215 | \code{get_clock}. |
| 216 | \end{funcdesc} |
| 217 | |
| 218 | %--- |
| 219 | |
| 220 | \begin{funcdesc}{add_button}{type\, x\, y\, w\, h\, name} |
| 221 | Add a button object to the form. \\ |
| 222 | Methods: |
| 223 | \code{get_button}, |
| 224 | \code{set_button}. |
| 225 | \end{funcdesc} |
| 226 | |
| 227 | \begin{funcdesc}{add_lightbutton}{type\, x\, y\, w\, h\, name} |
| 228 | Add a lightbutton object to the form. \\ |
| 229 | Methods: |
| 230 | \code{get_button}, |
| 231 | \code{set_button}. |
| 232 | \end{funcdesc} |
| 233 | |
| 234 | \begin{funcdesc}{add_roundbutton}{type\, x\, y\, w\, h\, name} |
| 235 | Add a roundbutton object to the form. \\ |
| 236 | Methods: |
| 237 | \code{get_button}, |
| 238 | \code{set_button}. |
| 239 | \end{funcdesc} |
| 240 | |
| 241 | %--- |
| 242 | |
| 243 | \begin{funcdesc}{add_slider}{type\, x\, y\, w\, h\, name} |
| 244 | Add a slider object to the form. \\ |
| 245 | Methods: |
| 246 | \code{set_slider_value}, |
| 247 | \code{get_slider_value}, |
| 248 | \code{set_slider_bounds}, |
| 249 | \code{get_slider_bounds}, |
| 250 | \code{set_slider_return}, |
| 251 | \code{set_slider_size}, |
| 252 | \code{set_slider_precision}, |
| 253 | \code{set_slider_step}. |
| 254 | \end{funcdesc} |
| 255 | |
| 256 | \begin{funcdesc}{add_valslider}{type\, x\, y\, w\, h\, name} |
| 257 | Add a valslider object to the form. \\ |
| 258 | Methods: |
| 259 | \code{set_slider_value}, |
| 260 | \code{get_slider_value}, |
| 261 | \code{set_slider_bounds}, |
| 262 | \code{get_slider_bounds}, |
| 263 | \code{set_slider_return}, |
| 264 | \code{set_slider_size}, |
| 265 | \code{set_slider_precision}, |
| 266 | \code{set_slider_step}. |
| 267 | \end{funcdesc} |
| 268 | |
| 269 | \begin{funcdesc}{add_dial}{type\, x\, y\, w\, h\, name} |
| 270 | Add a dial object to the form. \\ |
| 271 | Methods: |
| 272 | \code{set_dial_value}, |
| 273 | \code{get_dial_value}, |
| 274 | \code{set_dial_bounds}, |
| 275 | \code{get_dial_bounds}. |
| 276 | \end{funcdesc} |
| 277 | |
| 278 | \begin{funcdesc}{add_positioner}{type\, x\, y\, w\, h\, name} |
| 279 | Add a positioner object to the form. \\ |
| 280 | Methods: |
| 281 | \code{set_positioner_xvalue}, |
| 282 | \code{set_positioner_yvalue}, |
| 283 | \code{set_positioner_xbounds}, |
| 284 | \code{set_positioner_ybounds}, |
| 285 | \code{get_positioner_xvalue}, |
| 286 | \code{get_positioner_yvalue}, |
| 287 | \code{get_positioner_xbounds}, |
| 288 | \code{get_positioner_ybounds}. |
| 289 | \end{funcdesc} |
| 290 | |
| 291 | \begin{funcdesc}{add_counter}{type\, x\, y\, w\, h\, name} |
| 292 | Add a counter object to the form. \\ |
| 293 | Methods: |
| 294 | \code{set_counter_value}, |
| 295 | \code{get_counter_value}, |
| 296 | \code{set_counter_bounds}, |
| 297 | \code{set_counter_step}, |
| 298 | \code{set_counter_precision}, |
| 299 | \code{set_counter_return}. |
| 300 | \end{funcdesc} |
| 301 | |
| 302 | %--- |
| 303 | |
| 304 | \begin{funcdesc}{add_input}{type\, x\, y\, w\, h\, name} |
| 305 | Add a input object to the form. \\ |
| 306 | Methods: |
| 307 | \code{set_input}, |
| 308 | \code{get_input}, |
| 309 | \code{set_input_color}, |
| 310 | \code{set_input_return}. |
| 311 | \end{funcdesc} |
| 312 | |
| 313 | %--- |
| 314 | |
| 315 | \begin{funcdesc}{add_menu}{type\, x\, y\, w\, h\, name} |
| 316 | Add a menu object to the form. \\ |
| 317 | Methods: |
| 318 | \code{set_menu}, |
| 319 | \code{get_menu}, |
| 320 | \code{addto_menu}. |
| 321 | \end{funcdesc} |
| 322 | |
| 323 | \begin{funcdesc}{add_choice}{type\, x\, y\, w\, h\, name} |
| 324 | Add a choice object to the form. \\ |
| 325 | Methods: |
| 326 | \code{set_choice}, |
| 327 | \code{get_choice}, |
| 328 | \code{clear_choice}, |
| 329 | \code{addto_choice}, |
| 330 | \code{replace_choice}, |
| 331 | \code{delete_choice}, |
| 332 | \code{get_choice_text}, |
| 333 | \code{set_choice_fontsize}, |
| 334 | \code{set_choice_fontstyle}. |
| 335 | \end{funcdesc} |
| 336 | |
| 337 | \begin{funcdesc}{add_browser}{type\, x\, y\, w\, h\, name} |
| 338 | Add a browser object to the form. \\ |
| 339 | Methods: |
| 340 | \code{set_browser_topline}, |
| 341 | \code{clear_browser}, |
| 342 | \code{add_browser_line}, |
| 343 | \code{addto_browser}, |
| 344 | \code{insert_browser_line}, |
| 345 | \code{delete_browser_line}, |
| 346 | \code{replace_browser_line}, |
| 347 | \code{get_browser_line}, |
| 348 | \code{load_browser}, |
| 349 | \code{get_browser_maxline}, |
| 350 | \code{select_browser_line}, |
| 351 | \code{deselect_browser_line}, |
| 352 | \code{deselect_browser}, |
| 353 | \code{isselected_browser_line}, |
| 354 | \code{get_browser}, |
| 355 | \code{set_browser_fontsize}, |
| 356 | \code{set_browser_fontstyle}, |
| 357 | \code{set_browser_specialkey}. |
| 358 | \end{funcdesc} |
| 359 | |
| 360 | %--- |
| 361 | |
| 362 | \begin{funcdesc}{add_timer}{type\, x\, y\, w\, h\, name} |
| 363 | Add a timer object to the form. \\ |
| 364 | Methods: |
| 365 | \code{set_timer}, |
| 366 | \code{get_timer}. |
| 367 | \end{funcdesc} |
| 368 | \end{flushleft} |
| 369 | |
| 370 | Form objects have the following data attributes; see the FORMS |
| 371 | documentation: |
| 372 | |
| 373 | \begin{tableiii}{|l|c|l|}{code}{Name}{Type}{Meaning} |
| 374 | \lineiii{window}{int (read-only)}{GL window id} |
| 375 | \lineiii{w}{float}{form width} |
| 376 | \lineiii{h}{float}{form height} |
| 377 | \lineiii{x}{float}{form x origin} |
| 378 | \lineiii{y}{float}{form y origin} |
| 379 | \lineiii{deactivated}{int}{nonzero if form is deactivated} |
| 380 | \lineiii{visible}{int}{nonzero if form is visible} |
| 381 | \lineiii{frozen}{int}{nonzero if form is frozen} |
| 382 | \lineiii{doublebuf}{int}{nonzero if double buffering on} |
| 383 | \end{tableiii} |
| 384 | |
| 385 | \subsection{FORMS object methods and data attributes} |
| 386 | |
| 387 | Besides methods specific to particular kinds of FORMS objects, all |
| 388 | FORMS objects also have the following methods: |
| 389 | |
| 390 | \renewcommand{\indexsubitem}{(FORMS object method)} |
| 391 | \begin{funcdesc}{set_call_back}{function\, argument} |
| 392 | Set the object's callback function and argument. When the object |
| 393 | needs interaction, the callback function will be called with two |
| 394 | arguments: the object, and the callback argument. (FORMS objects |
| 395 | without a callback function are returned by \code{fl.do_forms()} or |
| 396 | \code{fl.check_forms()} when they need interaction.) Call this method |
| 397 | without arguments to remove the callback function. |
| 398 | \end{funcdesc} |
| 399 | |
| 400 | \begin{funcdesc}{delete_object}{} |
| 401 | Delete the object. |
| 402 | \end{funcdesc} |
| 403 | |
| 404 | \begin{funcdesc}{show_object}{} |
| 405 | Show the object. |
| 406 | \end{funcdesc} |
| 407 | |
| 408 | \begin{funcdesc}{hide_object}{} |
| 409 | Hide the object. |
| 410 | \end{funcdesc} |
| 411 | |
| 412 | \begin{funcdesc}{redraw_object}{} |
| 413 | Redraw the object. |
| 414 | \end{funcdesc} |
| 415 | |
| 416 | \begin{funcdesc}{freeze_object}{} |
| 417 | Freeze the object. |
| 418 | \end{funcdesc} |
| 419 | |
| 420 | \begin{funcdesc}{unfreeze_object}{} |
| 421 | Unfreeze the object. |
| 422 | \end{funcdesc} |
| 423 | |
| 424 | %\begin{funcdesc}{handle_object}{} XXX |
| 425 | %\end{funcdesc} |
| 426 | |
| 427 | %\begin{funcdesc}{handle_object_direct}{} XXX |
| 428 | %\end{funcdesc} |
| 429 | |
| 430 | FORMS objects have these data attributes; see the FORMS documentation: |
| 431 | |
| 432 | \begin{tableiii}{|l|c|l|}{code}{Name}{Type}{Meaning} |
| 433 | \lineiii{objclass}{int (read-only)}{object class} |
| 434 | \lineiii{type}{int (read-only)}{object type} |
| 435 | \lineiii{boxtype}{int}{box type} |
| 436 | \lineiii{x}{float}{x origin} |
| 437 | \lineiii{y}{float}{y origin} |
| 438 | \lineiii{w}{float}{width} |
| 439 | \lineiii{h}{float}{height} |
| 440 | \lineiii{col1}{int}{primary color} |
| 441 | \lineiii{col2}{int}{secondary color} |
| 442 | \lineiii{align}{int}{alignment} |
| 443 | \lineiii{lcol}{int}{label color} |
| 444 | \lineiii{lsize}{float}{label font size} |
| 445 | \lineiii{label}{string}{label string} |
| 446 | \lineiii{lstyle}{int}{label style} |
| 447 | \lineiii{pushed}{int (read-only)}{(see FORMS docs)} |
| 448 | \lineiii{focus}{int (read-only)}{(see FORMS docs)} |
| 449 | \lineiii{belowmouse}{int (read-only)}{(see FORMS docs)} |
| 450 | \lineiii{frozen}{int (read-only)}{(see FORMS docs)} |
| 451 | \lineiii{active}{int (read-only)}{(see FORMS docs)} |
| 452 | \lineiii{input}{int (read-only)}{(see FORMS docs)} |
| 453 | \lineiii{visible}{int (read-only)}{(see FORMS docs)} |
| 454 | \lineiii{radio}{int (read-only)}{(see FORMS docs)} |
| 455 | \lineiii{automatic}{int (read-only)}{(see FORMS docs)} |
| 456 | \end{tableiii} |
| 457 | |
| 458 | \section{Standard Module \sectcode{FL}} |
| 459 | \nodename{FL (uppercase)} |
| 460 | \stmodindex{FL} |
| 461 | |
| 462 | This module defines symbolic constants needed to use the built-in |
| 463 | module \code{fl} (see above); they are equivalent to those defined in |
| 464 | the C header file \file{<forms.h>} except that the name prefix |
| 465 | \samp{FL_} is omitted. Read the module source for a complete list of |
| 466 | the defined names. Suggested use: |
| 467 | |
| 468 | \bcode\begin{verbatim} |
| 469 | import fl |
| 470 | from FL import * |
| 471 | \end{verbatim}\ecode |
| 472 | |
| 473 | \section{Standard Module \sectcode{flp}} |
| 474 | \stmodindex{flp} |
| 475 | |
| 476 | This module defines functions that can read form definitions created |
| 477 | by the `form designer' (\code{fdesign}) program that comes with the |
| 478 | FORMS library (see module \code{fl} above). |
| 479 | |
| 480 | For now, see the file \file{flp.doc} in the Python library source |
| 481 | directory for a description. |
| 482 | |
| 483 | XXX A complete description should be inserted here! |