1 \section{\module{fl
} ---
2 FORMS library interface for GUI applications
}
4 \declaremodule{builtin
}{fl
}
6 \modulesynopsis{FORMS library interface for GUI applications.
}
9 This module provides an interface to the FORMS Library
\index{FORMS
10 Library
} by Mark Overmars
\index{Overmars, Mark
}. The source for the
11 library can be retrieved by anonymous ftp from host
12 \samp{ftp.cs.ruu.nl
}, directory
\file{SGI/FORMS
}. It was last tested
15 Most functions are literal translations of their C equivalents,
16 dropping the initial
\samp{fl_
} from their name. Constants used by
17 the library are defined in module
\refmodule[fl-constants
]{FL
}
20 The creation of objects is a little different in Python than in C:
21 instead of the `current form' maintained by the library to which new
22 FORMS objects are added, all functions that add a FORMS object to a
23 form are methods of the Python object representing the form.
24 Consequently, there are no Python equivalents for the C functions
25 \cfunction{fl_addto_form()
} and
\cfunction{fl_end_form()
}, and the
26 equivalent of
\cfunction{fl_bgn_form()
} is called
27 \function{fl.make_form()
}.
29 Watch out for the somewhat confusing terminology: FORMS uses the word
30 \dfn{object
} for the buttons, sliders etc. that you can place in a form.
31 In Python, `object' means any value. The Python interface to FORMS
32 introduces two new Python object types: form objects (representing an
33 entire form) and FORMS objects (representing one button, slider etc.).
34 Hopefully this isn't too confusing.
36 There are no `free objects' in the Python interface to FORMS, nor is
37 there an easy way to add object classes written in Python. The FORMS
38 interface to GL event handling is available, though, so you can mix
39 FORMS with pure GL windows.
41 \strong{Please note:
} importing
\module{fl
} implies a call to the GL
42 function
\cfunction{foreground()
} and to the FORMS routine
43 \cfunction{fl_init()
}.
45 \subsection{Functions Defined in Module
\module{fl
}}
46 \nodename{FL Functions
}
48 Module
\module{fl
} defines the following functions. For more
49 information about what they do, see the description of the equivalent
50 C function in the FORMS documentation:
52 \begin{funcdesc
}{make_form
}{type, width, height
}
53 Create a form with given type, width and height. This returns a
54 \dfn{form
} object, whose methods are described below.
57 \begin{funcdesc
}{do_forms
}{}
58 The standard FORMS main loop. Returns a Python object representing
59 the FORMS object needing interaction, or the special value
63 \begin{funcdesc
}{check_forms
}{}
64 Check for FORMS events. Returns what
\function{do_forms()
} above
65 returns, or
\code{None
} if there is no event that immediately needs
69 \begin{funcdesc
}{set_event_call_back
}{function
}
70 Set the event callback function.
73 \begin{funcdesc
}{set_graphics_mode
}{rgbmode, doublebuffering
}
74 Set the graphics modes.
77 \begin{funcdesc
}{get_rgbmode
}{}
78 Return the current rgb mode. This is the value of the C global
79 variable
\cdata{fl_rgbmode
}.
82 \begin{funcdesc
}{show_message
}{str1, str2, str3
}
83 Show a dialog box with a three-line message and an OK button.
86 \begin{funcdesc
}{show_question
}{str1, str2, str3
}
87 Show a dialog box with a three-line message and YES and NO buttons.
88 It returns
\code{1} if the user pressed YES,
\code{0} if NO.
91 \begin{funcdesc
}{show_choice
}{str1, str2, str3, but1
\optional{,
92 but2
\optional{, but3
}}}
93 Show a dialog box with a three-line message and up to three buttons.
94 It returns the number of the button clicked by the user
95 (
\code{1},
\code{2} or
\code{3}).
98 \begin{funcdesc
}{show_input
}{prompt, default
}
99 Show a dialog box with a one-line prompt message and text field in
100 which the user can enter a string. The second argument is the default
101 input string. It returns the string value as edited by the user.
104 \begin{funcdesc
}{show_file_selector
}{message, directory, pattern, default
}
105 Show a dialog box in which the user can select a file. It returns
106 the absolute filename selected by the user, or
\code{None
} if the user
110 \begin{funcdesc
}{get_directory
}{}
111 \funcline{get_pattern
}{}
112 \funcline{get_filename
}{}
113 These functions return the directory, pattern and filename (the tail
114 part only) selected by the user in the last
115 \function{show_file_selector()
} call.
118 \begin{funcdesc
}{qdevice
}{dev
}
119 \funcline{unqdevice
}{dev
}
120 \funcline{isqueued
}{dev
}
123 %\funcline{blkqread}{?}
125 \funcline{qenter
}{dev, val
}
126 \funcline{get_mouse
}{}
127 \funcline{tie
}{button, valuator1, valuator2
}
128 These functions are the FORMS interfaces to the corresponding GL
129 functions. Use these if you want to handle some GL events yourself
130 when using
\function{fl.do_events()
}. When a GL event is detected that
131 FORMS cannot handle,
\function{fl.do_forms()
} returns the special value
132 \constant{FL.EVENT
} and you should call
\function{fl.qread()
} to read
133 the event from the queue. Don't use the equivalent GL functions!
136 \begin{funcdesc
}{color}{}
137 \funcline{mapcolor
}{}
138 \funcline{getmcolor
}{}
139 See the description in the FORMS documentation of
140 \cfunction{fl_color()
},
\cfunction{fl_mapcolor()
} and
141 \cfunction{fl_getmcolor()
}.
144 \subsection{Form Objects
}
147 Form objects (returned by
\function{make_form()
} above) have the
148 following methods. Each method corresponds to a C function whose
149 name is prefixed with
\samp{fl_
}; and whose first argument is a form
150 pointer; please refer to the official FORMS documentation for
153 All the
\method{add_*()
} methods return a Python object representing
154 the FORMS object. Methods of FORMS objects are described below. Most
155 kinds of FORMS object also have some methods specific to that kind;
156 these methods are listed here.
160 \begin{methoddesc
}[form
]{show_form
}{placement, bordertype, name
}
164 \begin{methoddesc
}[form
]{hide_form
}{}
168 \begin{methoddesc
}[form
]{redraw_form
}{}
172 \begin{methoddesc
}[form
]{set_form_position
}{x, y
}
173 Set the form's position.
176 \begin{methoddesc
}[form
]{freeze_form
}{}
180 \begin{methoddesc
}[form
]{unfreeze_form
}{}
184 \begin{methoddesc
}[form
]{activate_form
}{}
188 \begin{methoddesc
}[form
]{deactivate_form
}{}
192 \begin{methoddesc
}[form
]{bgn_group
}{}
193 Begin a new group of objects; return a group object.
196 \begin{methoddesc
}[form
]{end_group
}{}
197 End the current group of objects.
200 \begin{methoddesc
}[form
]{find_first
}{}
201 Find the first object in the form.
204 \begin{methoddesc
}[form
]{find_last
}{}
205 Find the last object in the form.
210 \begin{methoddesc
}[form
]{add_box
}{type, x, y, w, h, name
}
211 Add a box object to the form.
215 \begin{methoddesc
}[form
]{add_text
}{type, x, y, w, h, name
}
216 Add a text object to the form.
220 %\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
221 %Add a bitmap object to the form.
224 \begin{methoddesc
}[form
]{add_clock
}{type, x, y, w, h, name
}
225 Add a clock object to the form. \\
227 \method{get_clock()
}.
232 \begin{methoddesc
}[form
]{add_button
}{type, x, y, w, h, name
}
233 Add a button object to the form. \\
235 \method{get_button()
},
236 \method{set_button()
}.
239 \begin{methoddesc
}[form
]{add_lightbutton
}{type, x, y, w, h, name
}
240 Add a lightbutton object to the form. \\
242 \method{get_button()
},
243 \method{set_button()
}.
246 \begin{methoddesc
}[form
]{add_roundbutton
}{type, x, y, w, h, name
}
247 Add a roundbutton object to the form. \\
249 \method{get_button()
},
250 \method{set_button()
}.
255 \begin{methoddesc
}[form
]{add_slider
}{type, x, y, w, h, name
}
256 Add a slider object to the form. \\
258 \method{set_slider_value()
},
259 \method{get_slider_value()
},
260 \method{set_slider_bounds()
},
261 \method{get_slider_bounds()
},
262 \method{set_slider_return()
},
263 \method{set_slider_size()
},
264 \method{set_slider_precision()
},
265 \method{set_slider_step()
}.
268 \begin{methoddesc
}[form
]{add_valslider
}{type, x, y, w, h, name
}
269 Add a valslider object to the form. \\
271 \method{set_slider_value()
},
272 \method{get_slider_value()
},
273 \method{set_slider_bounds()
},
274 \method{get_slider_bounds()
},
275 \method{set_slider_return()
},
276 \method{set_slider_size()
},
277 \method{set_slider_precision()
},
278 \method{set_slider_step()
}.
281 \begin{methoddesc
}[form
]{add_dial
}{type, x, y, w, h, name
}
282 Add a dial object to the form. \\
284 \method{set_dial_value()
},
285 \method{get_dial_value()
},
286 \method{set_dial_bounds()
},
287 \method{get_dial_bounds()
}.
290 \begin{methoddesc
}[form
]{add_positioner
}{type, x, y, w, h, name
}
291 Add a positioner object to the form. \\
293 \method{set_positioner_xvalue()
},
294 \method{set_positioner_yvalue()
},
295 \method{set_positioner_xbounds()
},
296 \method{set_positioner_ybounds()
},
297 \method{get_positioner_xvalue()
},
298 \method{get_positioner_yvalue()
},
299 \method{get_positioner_xbounds()
},
300 \method{get_positioner_ybounds()
}.
303 \begin{methoddesc
}[form
]{add_counter
}{type, x, y, w, h, name
}
304 Add a counter object to the form. \\
306 \method{set_counter_value()
},
307 \method{get_counter_value()
},
308 \method{set_counter_bounds()
},
309 \method{set_counter_step()
},
310 \method{set_counter_precision()
},
311 \method{set_counter_return()
}.
316 \begin{methoddesc
}[form
]{add_input
}{type, x, y, w, h, name
}
317 Add a input object to the form. \\
319 \method{set_input()
},
320 \method{get_input()
},
321 \method{set_input_color()
},
322 \method{set_input_return()
}.
327 \begin{methoddesc
}[form
]{add_menu
}{type, x, y, w, h, name
}
328 Add a menu object to the form. \\
332 \method{addto_menu()
}.
335 \begin{methoddesc
}[form
]{add_choice
}{type, x, y, w, h, name
}
336 Add a choice object to the form. \\
338 \method{set_choice()
},
339 \method{get_choice()
},
340 \method{clear_choice()
},
341 \method{addto_choice()
},
342 \method{replace_choice()
},
343 \method{delete_choice()
},
344 \method{get_choice_text()
},
345 \method{set_choice_fontsize()
},
346 \method{set_choice_fontstyle()
}.
349 \begin{methoddesc
}[form
]{add_browser
}{type, x, y, w, h, name
}
350 Add a browser object to the form. \\
352 \method{set_browser_topline()
},
353 \method{clear_browser()
},
354 \method{add_browser_line()
},
355 \method{addto_browser()
},
356 \method{insert_browser_line()
},
357 \method{delete_browser_line()
},
358 \method{replace_browser_line()
},
359 \method{get_browser_line()
},
360 \method{load_browser()
},
361 \method{get_browser_maxline()
},
362 \method{select_browser_line()
},
363 \method{deselect_browser_line()
},
364 \method{deselect_browser()
},
365 \method{isselected_browser_line()
},
366 \method{get_browser()
},
367 \method{set_browser_fontsize()
},
368 \method{set_browser_fontstyle()
},
369 \method{set_browser_specialkey()
}.
374 \begin{methoddesc
}[form
]{add_timer
}{type, x, y, w, h, name
}
375 Add a timer object to the form. \\
377 \method{set_timer()
},
378 \method{get_timer()
}.
382 Form objects have the following data attributes; see the FORMS
385 \begin{tableiii
}{l|l|l
}{member
}{Name
}{C Type
}{Meaning
}
386 \lineiii{window
}{int (read-only)
}{GL window id
}
387 \lineiii{w
}{float
}{form width
}
388 \lineiii{h
}{float
}{form height
}
389 \lineiii{x
}{float
}{form x origin
}
390 \lineiii{y
}{float
}{form y origin
}
391 \lineiii{deactivated
}{int
}{nonzero if form is deactivated
}
392 \lineiii{visible
}{int
}{nonzero if form is visible
}
393 \lineiii{frozen
}{int
}{nonzero if form is frozen
}
394 \lineiii{doublebuf
}{int
}{nonzero if double buffering on
}
397 \subsection{FORMS Objects
}
398 \label{forms-objects
}
400 Besides methods specific to particular kinds of FORMS objects, all
401 FORMS objects also have the following methods:
403 \begin{methoddesc
}[FORMS object
]{set_call_back
}{function, argument
}
404 Set the object's callback function and argument. When the object
405 needs interaction, the callback function will be called with two
406 arguments: the object, and the callback argument. (FORMS objects
407 without a callback function are returned by
\function{fl.do_forms()
}
408 or
\function{fl.check_forms()
} when they need interaction.) Call this
409 method without arguments to remove the callback function.
412 \begin{methoddesc
}[FORMS object
]{delete_object
}{}
416 \begin{methoddesc
}[FORMS object
]{show_object
}{}
420 \begin{methoddesc
}[FORMS object
]{hide_object
}{}
424 \begin{methoddesc
}[FORMS object
]{redraw_object
}{}
428 \begin{methoddesc
}[FORMS object
]{freeze_object
}{}
432 \begin{methoddesc
}[FORMS object
]{unfreeze_object
}{}
436 %\begin{methoddesc}[FORMS object]{handle_object}{} XXX
439 %\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
442 FORMS objects have these data attributes; see the FORMS documentation:
444 \begin{tableiii
}{l|l|l
}{member
}{Name
}{C Type
}{Meaning
}
445 \lineiii{objclass
}{int (read-only)
}{object class
}
446 \lineiii{type
}{int (read-only)
}{object type
}
447 \lineiii{boxtype
}{int
}{box type
}
448 \lineiii{x
}{float
}{x origin
}
449 \lineiii{y
}{float
}{y origin
}
450 \lineiii{w
}{float
}{width
}
451 \lineiii{h
}{float
}{height
}
452 \lineiii{col1
}{int
}{primary
color}
453 \lineiii{col2
}{int
}{secondary
color}
454 \lineiii{align
}{int
}{alignment
}
455 \lineiii{lcol
}{int
}{label
color}
456 \lineiii{lsize
}{float
}{label font size
}
457 \lineiii{label
}{string
}{label string
}
458 \lineiii{lstyle
}{int
}{label style
}
459 \lineiii{pushed
}{int (read-only)
}{(see FORMS docs)
}
460 \lineiii{focus
}{int (read-only)
}{(see FORMS docs)
}
461 \lineiii{belowmouse
}{int (read-only)
}{(see FORMS docs)
}
462 \lineiii{frozen
}{int (read-only)
}{(see FORMS docs)
}
463 \lineiii{active
}{int (read-only)
}{(see FORMS docs)
}
464 \lineiii{input
}{int (read-only)
}{(see FORMS docs)
}
465 \lineiii{visible
}{int (read-only)
}{(see FORMS docs)
}
466 \lineiii{radio
}{int (read-only)
}{(see FORMS docs)
}
467 \lineiii{automatic
}{int (read-only)
}{(see FORMS docs)
}
471 \section{\module{FL
} ---
472 Constants used with the
\module{fl
} module
}
474 \declaremodule[fl-constants
]{standard
}{FL
}
476 \modulesynopsis{Constants used with the
\module{fl
} module.
}
479 This module defines symbolic constants needed to use the built-in
480 module
\refmodule{fl
} (see above); they are equivalent to those defined in
481 the C header file
\code{<forms.h>
} except that the name prefix
482 \samp{FL_
} is omitted. Read the module source for a complete list of
483 the defined names. Suggested use:
491 \section{\module{flp
} ---
492 Functions for loading stored FORMS designs
}
494 \declaremodule{standard
}{flp
}
496 \modulesynopsis{Functions for loading stored FORMS designs.
}
499 This module defines functions that can read form definitions created
500 by the `form designer' (
\program{fdesign
}) program that comes with the
501 FORMS library (see module
\refmodule{fl
} above).
503 For now, see the file
\file{flp.doc
} in the Python library source
504 directory for a description.
506 XXX A complete description should be inserted here!
