1 \section{Built-in Module
\module{fl
}}
5 This module provides an interface to the FORMS Library
\index{FORMS
6 Library
} by Mark Overmars
\index{Overmars, Mark
}. The source for the
7 library can be retrieved by anonymous ftp from host
8 \samp{ftp.cs.ruu.nl
}, directory
\file{SGI/FORMS
}. It was last tested
11 Most functions are literal translations of their
\C{} equivalents,
12 dropping the initial
\samp{fl_
} from their name. Constants used by
13 the library are defined in module
\module{FL
} described below.
15 The creation of objects is a little different in Python than in C:
16 instead of the `current form' maintained by the library to which new
17 FORMS objects are added, all functions that add a FORMS object to a
18 form are methods of the Python object representing the form.
19 Consequently, there are no Python equivalents for the C functions
20 \cfunction{fl_addto_form()
} and
\cfunction{fl_end_form()
}, and the
21 equivalent of
\cfunction{fl_bgn_form()
} is called
22 \function{fl.make_form()
}.
24 Watch out for the somewhat confusing terminology: FORMS uses the word
25 \dfn{object
} for the buttons, sliders etc. that you can place in a form.
26 In Python, `object' means any value. The Python interface to FORMS
27 introduces two new Python object types: form objects (representing an
28 entire form) and FORMS objects (representing one button, slider etc.).
29 Hopefully this isn't too confusing.
31 There are no `free objects' in the Python interface to FORMS, nor is
32 there an easy way to add object classes written in Python. The FORMS
33 interface to GL event handling is available, though, so you can mix
34 FORMS with pure GL windows.
36 \strong{Please note:
} importing
\module{fl
} implies a call to the GL
37 function
\cfunction{foreground()
} and to the FORMS routine
38 \cfunction{fl_init()
}.
40 \subsection{Functions Defined in Module
\module{fl
}}
41 \nodename{FL Functions
}
43 Module
\module{fl
} defines the following functions. For more
44 information about what they do, see the description of the equivalent
45 \C{} function in the FORMS documentation:
47 \begin{funcdesc
}{make_form
}{type, width, height
}
48 Create a form with given type, width and height. This returns a
49 \dfn{form
} object, whose methods are described below.
52 \begin{funcdesc
}{do_forms
}{}
53 The standard FORMS main loop. Returns a Python object representing
54 the FORMS object needing interaction, or the special value
58 \begin{funcdesc
}{check_forms
}{}
59 Check for FORMS events. Returns what
\function{do_forms()
} above
60 returns, or
\code{None
} if there is no event that immediately needs
64 \begin{funcdesc
}{set_event_call_back
}{function
}
65 Set the event callback function.
68 \begin{funcdesc
}{set_graphics_mode
}{rgbmode, doublebuffering
}
69 Set the graphics modes.
72 \begin{funcdesc
}{get_rgbmode
}{}
73 Return the current rgb mode. This is the value of the
\C{} global
74 variable
\cdata{fl_rgbmode
}.
77 \begin{funcdesc
}{show_message
}{str1, str2, str3
}
78 Show a dialog box with a three-line message and an OK button.
81 \begin{funcdesc
}{show_question
}{str1, str2, str3
}
82 Show a dialog box with a three-line message and YES and NO buttons.
83 It returns
\code{1} if the user pressed YES,
\code{0} if NO.
86 \begin{funcdesc
}{show_choice
}{str1, str2, str3, but1
\optional{,
87 but2
\optional{, but3
}}}
88 Show a dialog box with a three-line message and up to three buttons.
89 It returns the number of the button clicked by the user
90 (
\code{1},
\code{2} or
\code{3}).
93 \begin{funcdesc
}{show_input
}{prompt, default
}
94 Show a dialog box with a one-line prompt message and text field in
95 which the user can enter a string. The second argument is the default
96 input string. It returns the string value as edited by the user.
99 \begin{funcdesc
}{show_file_selector
}{message, directory, pattern, default
}
100 Show a dialog box in which the user can select a file. It returns
101 the absolute filename selected by the user, or
\code{None
} if the user
105 \begin{funcdesc
}{get_directory
}{}
106 \funcline{get_pattern
}{}
107 \funcline{get_filename
}{}
108 These functions return the directory, pattern and filename (the tail
109 part only) selected by the user in the last
110 \function{show_file_selector()
} call.
113 \begin{funcdesc
}{qdevice
}{dev
}
114 \funcline{unqdevice
}{dev
}
115 \funcline{isqueued
}{dev
}
118 %\funcline{blkqread}{?}
120 \funcline{qenter
}{dev, val
}
121 \funcline{get_mouse
}{}
122 \funcline{tie
}{button, valuator1, valuator2
}
123 These functions are the FORMS interfaces to the corresponding GL
124 functions. Use these if you want to handle some GL events yourself
125 when using
\function{fl.do_events()
}. When a GL event is detected that
126 FORMS cannot handle,
\function{fl.do_forms()
} returns the special value
127 \constant{FL.EVENT
} and you should call
\function{fl.qread()
} to read
128 the event from the queue. Don't use the equivalent GL functions!
131 \begin{funcdesc
}{color}{}
132 \funcline{mapcolor
}{}
133 \funcline{getmcolor
}{}
134 See the description in the FORMS documentation of
135 \cfunction{fl_color()
},
\cfunction{fl_mapcolor()
} and
136 \cfunction{fl_getmcolor()
}.
139 \subsection{Form Objects
}
142 Form objects (returned by
\function{make_form()
} above) have the
143 following methods. Each method corresponds to a
\C{} function whose
144 name is prefixed with
\samp{fl_
}; and whose first argument is a form
145 pointer; please refer to the official FORMS documentation for
148 All the
\method{add_*()
} methods return a Python object representing
149 the FORMS object. Methods of FORMS objects are described below. Most
150 kinds of FORMS object also have some methods specific to that kind;
151 these methods are listed here.
155 \begin{methoddesc
}[form
]{show_form
}{placement, bordertype, name
}
159 \begin{methoddesc
}[form
]{hide_form
}{}
163 \begin{methoddesc
}[form
]{redraw_form
}{}
167 \begin{methoddesc
}[form
]{set_form_position
}{x, y
}
168 Set the form's position.
171 \begin{methoddesc
}[form
]{freeze_form
}{}
175 \begin{methoddesc
}[form
]{unfreeze_form
}{}
179 \begin{methoddesc
}[form
]{activate_form
}{}
183 \begin{methoddesc
}[form
]{deactivate_form
}{}
187 \begin{methoddesc
}[form
]{bgn_group
}{}
188 Begin a new group of objects; return a group object.
191 \begin{methoddesc
}[form
]{end_group
}{}
192 End the current group of objects.
195 \begin{methoddesc
}[form
]{find_first
}{}
196 Find the first object in the form.
199 \begin{methoddesc
}[form
]{find_last
}{}
200 Find the last object in the form.
205 \begin{methoddesc
}[form
]{add_box
}{type, x, y, w, h, name
}
206 Add a box object to the form.
210 \begin{methoddesc
}[form
]{add_text
}{type, x, y, w, h, name
}
211 Add a text object to the form.
215 %\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
216 %Add a bitmap object to the form.
219 \begin{methoddesc
}[form
]{add_clock
}{type, x, y, w, h, name
}
220 Add a clock object to the form. \\
222 \method{get_clock()
}.
227 \begin{methoddesc
}[form
]{add_button
}{type, x, y, w, h, name
}
228 Add a button object to the form. \\
230 \method{get_button()
},
231 \method{set_button()
}.
234 \begin{methoddesc
}[form
]{add_lightbutton
}{type, x, y, w, h, name
}
235 Add a lightbutton object to the form. \\
237 \method{get_button()
},
238 \method{set_button()
}.
241 \begin{methoddesc
}[form
]{add_roundbutton
}{type, x, y, w, h, name
}
242 Add a roundbutton object to the form. \\
244 \method{get_button()
},
245 \method{set_button()
}.
250 \begin{methoddesc
}[form
]{add_slider
}{type, x, y, w, h, name
}
251 Add a slider object to the form. \\
253 \method{set_slider_value()
},
254 \method{get_slider_value()
},
255 \method{set_slider_bounds()
},
256 \method{get_slider_bounds()
},
257 \method{set_slider_return()
},
258 \method{set_slider_size()
},
259 \method{set_slider_precision()
},
260 \method{set_slider_step()
}.
263 \begin{methoddesc
}[form
]{add_valslider
}{type, x, y, w, h, name
}
264 Add a valslider object to the form. \\
266 \method{set_slider_value()
},
267 \method{get_slider_value()
},
268 \method{set_slider_bounds()
},
269 \method{get_slider_bounds()
},
270 \method{set_slider_return()
},
271 \method{set_slider_size()
},
272 \method{set_slider_precision()
},
273 \method{set_slider_step()
}.
276 \begin{methoddesc
}[form
]{add_dial
}{type, x, y, w, h, name
}
277 Add a dial object to the form. \\
279 \method{set_dial_value()
},
280 \method{get_dial_value()
},
281 \method{set_dial_bounds()
},
282 \method{get_dial_bounds()
}.
285 \begin{methoddesc
}[form
]{add_positioner
}{type, x, y, w, h, name
}
286 Add a positioner object to the form. \\
288 \method{set_positioner_xvalue()
},
289 \method{set_positioner_yvalue()
},
290 \method{set_positioner_xbounds()
},
291 \method{set_positioner_ybounds()
},
292 \method{get_positioner_xvalue()
},
293 \method{get_positioner_yvalue()
},
294 \method{get_positioner_xbounds()
},
295 \method{get_positioner_ybounds()
}.
298 \begin{methoddesc
}[form
]{add_counter
}{type, x, y, w, h, name
}
299 Add a counter object to the form. \\
301 \method{set_counter_value()
},
302 \method{get_counter_value()
},
303 \method{set_counter_bounds()
},
304 \method{set_counter_step()
},
305 \method{set_counter_precision()
},
306 \method{set_counter_return()
}.
311 \begin{methoddesc
}[form
]{add_input
}{type, x, y, w, h, name
}
312 Add a input object to the form. \\
314 \method{set_input()
},
315 \method{get_input()
},
316 \method{set_input_color()
},
317 \method{set_input_return()
}.
322 \begin{methoddesc
}[form
]{add_menu
}{type, x, y, w, h, name
}
323 Add a menu object to the form. \\
327 \method{addto_menu()
}.
330 \begin{methoddesc
}[form
]{add_choice
}{type, x, y, w, h, name
}
331 Add a choice object to the form. \\
333 \method{set_choice()
},
334 \method{get_choice()
},
335 \method{clear_choice()
},
336 \method{addto_choice()
},
337 \method{replace_choice()
},
338 \method{delete_choice()
},
339 \method{get_choice_text()
},
340 \method{set_choice_fontsize()
},
341 \method{set_choice_fontstyle()
}.
344 \begin{methoddesc
}[form
]{add_browser
}{type, x, y, w, h, name
}
345 Add a browser object to the form. \\
347 \method{set_browser_topline()
},
348 \method{clear_browser()
},
349 \method{add_browser_line()
},
350 \method{addto_browser()
},
351 \method{insert_browser_line()
},
352 \method{delete_browser_line()
},
353 \method{replace_browser_line()
},
354 \method{get_browser_line()
},
355 \method{load_browser()
},
356 \method{get_browser_maxline()
},
357 \method{select_browser_line()
},
358 \method{deselect_browser_line()
},
359 \method{deselect_browser()
},
360 \method{isselected_browser_line()
},
361 \method{get_browser()
},
362 \method{set_browser_fontsize()
},
363 \method{set_browser_fontstyle()
},
364 \method{set_browser_specialkey()
}.
369 \begin{methoddesc
}[form
]{add_timer
}{type, x, y, w, h, name
}
370 Add a timer object to the form. \\
372 \method{set_timer()
},
373 \method{get_timer()
}.
377 Form objects have the following data attributes; see the FORMS
380 \begin{tableiii
}{l|l|l
}{member
}{Name
}{C Type
}{Meaning
}
381 \lineiii{window
}{int (read-only)
}{GL window id
}
382 \lineiii{w
}{float
}{form width
}
383 \lineiii{h
}{float
}{form height
}
384 \lineiii{x
}{float
}{form x origin
}
385 \lineiii{y
}{float
}{form y origin
}
386 \lineiii{deactivated
}{int
}{nonzero if form is deactivated
}
387 \lineiii{visible
}{int
}{nonzero if form is visible
}
388 \lineiii{frozen
}{int
}{nonzero if form is frozen
}
389 \lineiii{doublebuf
}{int
}{nonzero if double buffering on
}
392 \subsection{FORMS Objects
}
393 \label{forms-objects
}
395 Besides methods specific to particular kinds of FORMS objects, all
396 FORMS objects also have the following methods:
398 \begin{methoddesc
}[FORMS object
]{set_call_back
}{function, argument
}
399 Set the object's callback function and argument. When the object
400 needs interaction, the callback function will be called with two
401 arguments: the object, and the callback argument. (FORMS objects
402 without a callback function are returned by
\function{fl.do_forms()
}
403 or
\function{fl.check_forms()
} when they need interaction.) Call this
404 method without arguments to remove the callback function.
407 \begin{methoddesc
}[FORMS object
]{delete_object
}{}
411 \begin{methoddesc
}[FORMS object
]{show_object
}{}
415 \begin{methoddesc
}[FORMS object
]{hide_object
}{}
419 \begin{methoddesc
}[FORMS object
]{redraw_object
}{}
423 \begin{methoddesc
}[FORMS object
]{freeze_object
}{}
427 \begin{methoddesc
}[FORMS object
]{unfreeze_object
}{}
431 %\begin{methoddesc}[FORMS object]{handle_object}{} XXX
434 %\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
437 FORMS objects have these data attributes; see the FORMS documentation:
439 \begin{tableiii
}{l|l|l
}{member
}{Name
}{C Type
}{Meaning
}
440 \lineiii{objclass
}{int (read-only)
}{object class
}
441 \lineiii{type
}{int (read-only)
}{object type
}
442 \lineiii{boxtype
}{int
}{box type
}
443 \lineiii{x
}{float
}{x origin
}
444 \lineiii{y
}{float
}{y origin
}
445 \lineiii{w
}{float
}{width
}
446 \lineiii{h
}{float
}{height
}
447 \lineiii{col1
}{int
}{primary
color}
448 \lineiii{col2
}{int
}{secondary
color}
449 \lineiii{align
}{int
}{alignment
}
450 \lineiii{lcol
}{int
}{label
color}
451 \lineiii{lsize
}{float
}{label font size
}
452 \lineiii{label
}{string
}{label string
}
453 \lineiii{lstyle
}{int
}{label style
}
454 \lineiii{pushed
}{int (read-only)
}{(see FORMS docs)
}
455 \lineiii{focus
}{int (read-only)
}{(see FORMS docs)
}
456 \lineiii{belowmouse
}{int (read-only)
}{(see FORMS docs)
}
457 \lineiii{frozen
}{int (read-only)
}{(see FORMS docs)
}
458 \lineiii{active
}{int (read-only)
}{(see FORMS docs)
}
459 \lineiii{input
}{int (read-only)
}{(see FORMS docs)
}
460 \lineiii{visible
}{int (read-only)
}{(see FORMS docs)
}
461 \lineiii{radio
}{int (read-only)
}{(see FORMS docs)
}
462 \lineiii{automatic
}{int (read-only)
}{(see FORMS docs)
}
465 \section{Standard Module
\module{FL
}}
466 \label{module-FLuppercase
}
469 This module defines symbolic constants needed to use the built-in
470 module
\module{fl
} (see above); they are equivalent to those defined in
471 the
\C{} header file
\code{<forms.h>
} except that the name prefix
472 \samp{FL_
} is omitted. Read the module source for a complete list of
473 the defined names. Suggested use:
480 \section{Standard Module
\module{flp
}}
484 This module defines functions that can read form definitions created
485 by the `form designer' (
\program{fdesign
}) program that comes with the
486 FORMS library (see module
\module{fl
} above).
488 For now, see the file
\file{flp.doc
} in the Python library source
489 directory for a description.
491 XXX A complete description should be inserted here!
