1 \section{\module{fl
} ---
2 FORMS library for graphical user interfaces
}
4 \declaremodule{builtin
}{fl
}
6 \modulesynopsis{FORMS library for applications with graphical user
10 This module provides an interface to the FORMS Library
\index{FORMS
11 Library
} by Mark Overmars
\index{Overmars, Mark
}. The source for the
12 library can be retrieved by anonymous ftp from host
13 \samp{ftp.cs.ruu.nl
}, directory
\file{SGI/FORMS
}. It was last tested
16 Most functions are literal translations of their C equivalents,
17 dropping the initial
\samp{fl_
} from their name. Constants used by
18 the library are defined in module
\refmodule[fl-constants
]{FL
}
21 The creation of objects is a little different in Python than in C:
22 instead of the `current form' maintained by the library to which new
23 FORMS objects are added, all functions that add a FORMS object to a
24 form are methods of the Python object representing the form.
25 Consequently, there are no Python equivalents for the C functions
26 \cfunction{fl_addto_form()
} and
\cfunction{fl_end_form()
}, and the
27 equivalent of
\cfunction{fl_bgn_form()
} is called
28 \function{fl.make_form()
}.
30 Watch out for the somewhat confusing terminology: FORMS uses the word
31 \dfn{object
} for the buttons, sliders etc. that you can place in a form.
32 In Python, `object' means any value. The Python interface to FORMS
33 introduces two new Python object types: form objects (representing an
34 entire form) and FORMS objects (representing one button, slider etc.).
35 Hopefully this isn't too confusing.
37 There are no `free objects' in the Python interface to FORMS, nor is
38 there an easy way to add object classes written in Python. The FORMS
39 interface to GL event handling is available, though, so you can mix
40 FORMS with pure GL windows.
42 \strong{Please note:
} importing
\module{fl
} implies a call to the GL
43 function
\cfunction{foreground()
} and to the FORMS routine
44 \cfunction{fl_init()
}.
46 \subsection{Functions Defined in Module
\module{fl
}}
47 \nodename{FL Functions
}
49 Module
\module{fl
} defines the following functions. For more
50 information about what they do, see the description of the equivalent
51 C function in the FORMS documentation:
53 \begin{funcdesc
}{make_form
}{type, width, height
}
54 Create a form with given type, width and height. This returns a
55 \dfn{form
} object, whose methods are described below.
58 \begin{funcdesc
}{do_forms
}{}
59 The standard FORMS main loop. Returns a Python object representing
60 the FORMS object needing interaction, or the special value
64 \begin{funcdesc
}{check_forms
}{}
65 Check for FORMS events. Returns what
\function{do_forms()
} above
66 returns, or
\code{None
} if there is no event that immediately needs
70 \begin{funcdesc
}{set_event_call_back
}{function
}
71 Set the event callback function.
74 \begin{funcdesc
}{set_graphics_mode
}{rgbmode, doublebuffering
}
75 Set the graphics modes.
78 \begin{funcdesc
}{get_rgbmode
}{}
79 Return the current rgb mode. This is the value of the C global
80 variable
\cdata{fl_rgbmode
}.
83 \begin{funcdesc
}{show_message
}{str1, str2, str3
}
84 Show a dialog box with a three-line message and an OK button.
87 \begin{funcdesc
}{show_question
}{str1, str2, str3
}
88 Show a dialog box with a three-line message and YES and NO buttons.
89 It returns
\code{1} if the user pressed YES,
\code{0} if NO.
92 \begin{funcdesc
}{show_choice
}{str1, str2, str3, but1
\optional{,
93 but2
\optional{, but3
}}}
94 Show a dialog box with a three-line message and up to three buttons.
95 It returns the number of the button clicked by the user
96 (
\code{1},
\code{2} or
\code{3}).
99 \begin{funcdesc
}{show_input
}{prompt, default
}
100 Show a dialog box with a one-line prompt message and text field in
101 which the user can enter a string. The second argument is the default
102 input string. It returns the string value as edited by the user.
105 \begin{funcdesc
}{show_file_selector
}{message, directory, pattern, default
}
106 Show a dialog box in which the user can select a file. It returns
107 the absolute filename selected by the user, or
\code{None
} if the user
111 \begin{funcdesc
}{get_directory
}{}
112 \funcline{get_pattern
}{}
113 \funcline{get_filename
}{}
114 These functions return the directory, pattern and filename (the tail
115 part only) selected by the user in the last
116 \function{show_file_selector()
} call.
119 \begin{funcdesc
}{qdevice
}{dev
}
120 \funcline{unqdevice
}{dev
}
121 \funcline{isqueued
}{dev
}
124 %\funcline{blkqread}{?}
126 \funcline{qenter
}{dev, val
}
127 \funcline{get_mouse
}{}
128 \funcline{tie
}{button, valuator1, valuator2
}
129 These functions are the FORMS interfaces to the corresponding GL
130 functions. Use these if you want to handle some GL events yourself
131 when using
\function{fl.do_events()
}. When a GL event is detected that
132 FORMS cannot handle,
\function{fl.do_forms()
} returns the special value
133 \constant{FL.EVENT
} and you should call
\function{fl.qread()
} to read
134 the event from the queue. Don't use the equivalent GL functions!
137 \begin{funcdesc
}{color}{}
138 \funcline{mapcolor
}{}
139 \funcline{getmcolor
}{}
140 See the description in the FORMS documentation of
141 \cfunction{fl_color()
},
\cfunction{fl_mapcolor()
} and
142 \cfunction{fl_getmcolor()
}.
145 \subsection{Form Objects
}
148 Form objects (returned by
\function{make_form()
} above) have the
149 following methods. Each method corresponds to a C function whose
150 name is prefixed with
\samp{fl_
}; and whose first argument is a form
151 pointer; please refer to the official FORMS documentation for
154 All the
\method{add_*()
} methods return a Python object representing
155 the FORMS object. Methods of FORMS objects are described below. Most
156 kinds of FORMS object also have some methods specific to that kind;
157 these methods are listed here.
161 \begin{methoddesc
}[form
]{show_form
}{placement, bordertype, name
}
165 \begin{methoddesc
}[form
]{hide_form
}{}
169 \begin{methoddesc
}[form
]{redraw_form
}{}
173 \begin{methoddesc
}[form
]{set_form_position
}{x, y
}
174 Set the form's position.
177 \begin{methoddesc
}[form
]{freeze_form
}{}
181 \begin{methoddesc
}[form
]{unfreeze_form
}{}
185 \begin{methoddesc
}[form
]{activate_form
}{}
189 \begin{methoddesc
}[form
]{deactivate_form
}{}
193 \begin{methoddesc
}[form
]{bgn_group
}{}
194 Begin a new group of objects; return a group object.
197 \begin{methoddesc
}[form
]{end_group
}{}
198 End the current group of objects.
201 \begin{methoddesc
}[form
]{find_first
}{}
202 Find the first object in the form.
205 \begin{methoddesc
}[form
]{find_last
}{}
206 Find the last object in the form.
211 \begin{methoddesc
}[form
]{add_box
}{type, x, y, w, h, name
}
212 Add a box object to the form.
216 \begin{methoddesc
}[form
]{add_text
}{type, x, y, w, h, name
}
217 Add a text object to the form.
221 %\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
222 %Add a bitmap object to the form.
225 \begin{methoddesc
}[form
]{add_clock
}{type, x, y, w, h, name
}
226 Add a clock object to the form. \\
228 \method{get_clock()
}.
233 \begin{methoddesc
}[form
]{add_button
}{type, x, y, w, h, name
}
234 Add a button object to the form. \\
236 \method{get_button()
},
237 \method{set_button()
}.
240 \begin{methoddesc
}[form
]{add_lightbutton
}{type, x, y, w, h, name
}
241 Add a lightbutton object to the form. \\
243 \method{get_button()
},
244 \method{set_button()
}.
247 \begin{methoddesc
}[form
]{add_roundbutton
}{type, x, y, w, h, name
}
248 Add a roundbutton object to the form. \\
250 \method{get_button()
},
251 \method{set_button()
}.
256 \begin{methoddesc
}[form
]{add_slider
}{type, x, y, w, h, name
}
257 Add a slider object to the form. \\
259 \method{set_slider_value()
},
260 \method{get_slider_value()
},
261 \method{set_slider_bounds()
},
262 \method{get_slider_bounds()
},
263 \method{set_slider_return()
},
264 \method{set_slider_size()
},
265 \method{set_slider_precision()
},
266 \method{set_slider_step()
}.
269 \begin{methoddesc
}[form
]{add_valslider
}{type, x, y, w, h, name
}
270 Add a valslider object to the form. \\
272 \method{set_slider_value()
},
273 \method{get_slider_value()
},
274 \method{set_slider_bounds()
},
275 \method{get_slider_bounds()
},
276 \method{set_slider_return()
},
277 \method{set_slider_size()
},
278 \method{set_slider_precision()
},
279 \method{set_slider_step()
}.
282 \begin{methoddesc
}[form
]{add_dial
}{type, x, y, w, h, name
}
283 Add a dial object to the form. \\
285 \method{set_dial_value()
},
286 \method{get_dial_value()
},
287 \method{set_dial_bounds()
},
288 \method{get_dial_bounds()
}.
291 \begin{methoddesc
}[form
]{add_positioner
}{type, x, y, w, h, name
}
292 Add a positioner object to the form. \\
294 \method{set_positioner_xvalue()
},
295 \method{set_positioner_yvalue()
},
296 \method{set_positioner_xbounds()
},
297 \method{set_positioner_ybounds()
},
298 \method{get_positioner_xvalue()
},
299 \method{get_positioner_yvalue()
},
300 \method{get_positioner_xbounds()
},
301 \method{get_positioner_ybounds()
}.
304 \begin{methoddesc
}[form
]{add_counter
}{type, x, y, w, h, name
}
305 Add a counter object to the form. \\
307 \method{set_counter_value()
},
308 \method{get_counter_value()
},
309 \method{set_counter_bounds()
},
310 \method{set_counter_step()
},
311 \method{set_counter_precision()
},
312 \method{set_counter_return()
}.
317 \begin{methoddesc
}[form
]{add_input
}{type, x, y, w, h, name
}
318 Add a input object to the form. \\
320 \method{set_input()
},
321 \method{get_input()
},
322 \method{set_input_color()
},
323 \method{set_input_return()
}.
328 \begin{methoddesc
}[form
]{add_menu
}{type, x, y, w, h, name
}
329 Add a menu object to the form. \\
333 \method{addto_menu()
}.
336 \begin{methoddesc
}[form
]{add_choice
}{type, x, y, w, h, name
}
337 Add a choice object to the form. \\
339 \method{set_choice()
},
340 \method{get_choice()
},
341 \method{clear_choice()
},
342 \method{addto_choice()
},
343 \method{replace_choice()
},
344 \method{delete_choice()
},
345 \method{get_choice_text()
},
346 \method{set_choice_fontsize()
},
347 \method{set_choice_fontstyle()
}.
350 \begin{methoddesc
}[form
]{add_browser
}{type, x, y, w, h, name
}
351 Add a browser object to the form. \\
353 \method{set_browser_topline()
},
354 \method{clear_browser()
},
355 \method{add_browser_line()
},
356 \method{addto_browser()
},
357 \method{insert_browser_line()
},
358 \method{delete_browser_line()
},
359 \method{replace_browser_line()
},
360 \method{get_browser_line()
},
361 \method{load_browser()
},
362 \method{get_browser_maxline()
},
363 \method{select_browser_line()
},
364 \method{deselect_browser_line()
},
365 \method{deselect_browser()
},
366 \method{isselected_browser_line()
},
367 \method{get_browser()
},
368 \method{set_browser_fontsize()
},
369 \method{set_browser_fontstyle()
},
370 \method{set_browser_specialkey()
}.
375 \begin{methoddesc
}[form
]{add_timer
}{type, x, y, w, h, name
}
376 Add a timer object to the form. \\
378 \method{set_timer()
},
379 \method{get_timer()
}.
383 Form objects have the following data attributes; see the FORMS
386 \begin{tableiii
}{l|l|l
}{member
}{Name
}{C Type
}{Meaning
}
387 \lineiii{window
}{int (read-only)
}{GL window id
}
388 \lineiii{w
}{float
}{form width
}
389 \lineiii{h
}{float
}{form height
}
390 \lineiii{x
}{float
}{form x origin
}
391 \lineiii{y
}{float
}{form y origin
}
392 \lineiii{deactivated
}{int
}{nonzero if form is deactivated
}
393 \lineiii{visible
}{int
}{nonzero if form is visible
}
394 \lineiii{frozen
}{int
}{nonzero if form is frozen
}
395 \lineiii{doublebuf
}{int
}{nonzero if double buffering on
}
398 \subsection{FORMS Objects
}
399 \label{forms-objects
}
401 Besides methods specific to particular kinds of FORMS objects, all
402 FORMS objects also have the following methods:
404 \begin{methoddesc
}[FORMS object
]{set_call_back
}{function, argument
}
405 Set the object's callback function and argument. When the object
406 needs interaction, the callback function will be called with two
407 arguments: the object, and the callback argument. (FORMS objects
408 without a callback function are returned by
\function{fl.do_forms()
}
409 or
\function{fl.check_forms()
} when they need interaction.) Call this
410 method without arguments to remove the callback function.
413 \begin{methoddesc
}[FORMS object
]{delete_object
}{}
417 \begin{methoddesc
}[FORMS object
]{show_object
}{}
421 \begin{methoddesc
}[FORMS object
]{hide_object
}{}
425 \begin{methoddesc
}[FORMS object
]{redraw_object
}{}
429 \begin{methoddesc
}[FORMS object
]{freeze_object
}{}
433 \begin{methoddesc
}[FORMS object
]{unfreeze_object
}{}
437 %\begin{methoddesc}[FORMS object]{handle_object}{} XXX
440 %\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
443 FORMS objects have these data attributes; see the FORMS documentation:
445 \begin{tableiii
}{l|l|l
}{member
}{Name
}{C Type
}{Meaning
}
446 \lineiii{objclass
}{int (read-only)
}{object class
}
447 \lineiii{type
}{int (read-only)
}{object type
}
448 \lineiii{boxtype
}{int
}{box type
}
449 \lineiii{x
}{float
}{x origin
}
450 \lineiii{y
}{float
}{y origin
}
451 \lineiii{w
}{float
}{width
}
452 \lineiii{h
}{float
}{height
}
453 \lineiii{col1
}{int
}{primary
color}
454 \lineiii{col2
}{int
}{secondary
color}
455 \lineiii{align
}{int
}{alignment
}
456 \lineiii{lcol
}{int
}{label
color}
457 \lineiii{lsize
}{float
}{label font size
}
458 \lineiii{label
}{string
}{label string
}
459 \lineiii{lstyle
}{int
}{label style
}
460 \lineiii{pushed
}{int (read-only)
}{(see FORMS docs)
}
461 \lineiii{focus
}{int (read-only)
}{(see FORMS docs)
}
462 \lineiii{belowmouse
}{int (read-only)
}{(see FORMS docs)
}
463 \lineiii{frozen
}{int (read-only)
}{(see FORMS docs)
}
464 \lineiii{active
}{int (read-only)
}{(see FORMS docs)
}
465 \lineiii{input
}{int (read-only)
}{(see FORMS docs)
}
466 \lineiii{visible
}{int (read-only)
}{(see FORMS docs)
}
467 \lineiii{radio
}{int (read-only)
}{(see FORMS docs)
}
468 \lineiii{automatic
}{int (read-only)
}{(see FORMS docs)
}
472 \section{\module{FL
} ---
473 Constants used with the
\module{fl
} module
}
475 \declaremodule[fl-constants
]{standard
}{FL
}
477 \modulesynopsis{Constants used with the
\module{fl
} module.
}
480 This module defines symbolic constants needed to use the built-in
481 module
\refmodule{fl
} (see above); they are equivalent to those defined in
482 the C header file
\code{<forms.h>
} except that the name prefix
483 \samp{FL_
} is omitted. Read the module source for a complete list of
484 the defined names. Suggested use:
492 \section{\module{flp
} ---
493 Functions for loading stored FORMS designs
}
495 \declaremodule{standard
}{flp
}
497 \modulesynopsis{Functions for loading stored FORMS designs.
}
500 This module defines functions that can read form definitions created
501 by the `form designer' (
\program{fdesign
}) program that comes with the
502 FORMS library (see module
\refmodule{fl
} above).
504 For now, see the file
\file{flp.doc
} in the Python library source
505 directory for a description.
507 XXX A complete description should be inserted here!
